001: /*
002: This software is OSI Certified Open Source Software.
003: OSI Certified is a certification mark of the Open Source Initiative.
004:
005: The license (Mozilla version 1.0) can be read at the MMBase site.
006: See http://www.MMBase.org/license
007:
008: */
009:
010: package org.mmbase.util.logging;
011:
012: /**
013: * The `Logger' interface for MMBase.
014: *
015: * It was designed for use with Log4j, but it is of course easy to
016: * implement it differently as well.
017: * <p>
018: * Implementations should also supply a getLoggerInstance static
019: * method, and can supply a configure static method.
020: * </p>
021: * </p>
022: * For example:
023: * <code>
024: * <pre>
025: * <tt>
026: * <b><font color=#0000FF>import</font></b> org.mmbase.util.logging.Logging;
027: * <b><font color=#0000FF>import</font></b> org.mmbase.util.logging.Logger;
028: *
029: * <b><font color=#0000FF>public</font></b> <b><font color=#0000FF>class</font></b> Foo {
030: * <b><font color=#0000FF>static</font></b> Logger log = Logging.getLoggerInstance(Foo.<b><font color=#0000FF>class</font></b>.getName());
031: * <b><font color=#0000FF>public</font></b> <font color=#009900>void</font> bar() {
032: * ...
033: * log.info(<font color=#FF0000>"Hello world!"</font>);
034: * ...
035: * <b><font color=#0000FF>if</font></b>(log.isDebugEnabled()) {
036: * log.debug(<font color=#FF0000>"Oops, that's not quite right!"</font>);
037: * }
038: * ...
039: * }
040: * }
041: * </tt>
042: * </pre>
043: * </code>
044: * </p>
045: *
046: * @author Michiel Meeuwissen
047: *
048: **/
049:
050: public interface Logger {
051:
052: // these static methods should also be implemented:
053: // public static void configure(String s); // well, this one is optional
054: // public static Logger getLoggerInstance(String name);
055:
056: /**
057: * Logs the message m with trace priority. For detailled debugging.
058: * @see #debug(Object)
059: */
060: void trace(Object m);
061:
062: /**
063: * @since MMBase-1.8
064: */
065:
066: void trace(Object m, Throwable t);
067:
068: /**
069: * Logs the message m with debug priority. Everything a
070: * non-developer never wants to see, but you do, to * keep track
071: * of what is happening. There can be a lot of them in the code,
072: * so it is important that you well protect them with
073: * `isDebugEnabled's, to minimize overhead.
074: */
075: void debug(Object m);
076:
077: /**
078: * @since MMBase-1.8
079: */
080:
081: void debug(Object m, Throwable t);
082:
083: /**
084: * Logs the message m with service priority. An interested system
085: * administrator might want to see these things. For examples all
086: * queries to the database could be logged with `service'
087: * priority. Or if a image is calculated, that could be logged as
088: * a `service'. One would get a fairly good idea what MMBase is
089: * doing if `service' is switched on.
090: */
091: void service(Object m);
092:
093: /**
094: * @since MMBase-1.8
095: */
096:
097: void service(Object m, Throwable t);
098:
099: /**
100: * Logs the message m with info priority. As `service', but
101: * focussed on things system administrators are usually most
102: * interested in, like authorisation issues. For example changes on
103: * the database could be logged, such that one can see in the logs
104: * what happened.
105: */
106: void info(Object m);
107:
108: /**
109: * @since MMBase-1.8
110: */
111: void info(Object m, Throwable t);
112:
113: /**
114: * Logs the message m with warn priority. Something strange
115: * happened, but it is not necessarily an error.
116: */
117: void warn(Object m);
118:
119: /**
120: * @since MMBase-1.8
121: */
122: void warn(Object m, Throwable t);
123:
124: /**
125: * Logs the message m with error priority. Something is definitely
126: * wrong. An inconsistency was detected. It might be unpredictable
127: * what will happen.
128: */
129: void error(Object m);
130:
131: /**
132: * @since MMBase-1.8
133: */
134: void error(Object m, Throwable t);
135:
136: /**
137: * Logs the message m with fatal priority. The progam could not
138: * function any more. Normally, you would throw an exception,
139: * which then will be logged with fatal priority. I've made an
140: * arangement in `Logger' that logs uncatched exceptions with
141: * fatal priority, but nevertheless it's better to always catch
142: * all exceptions in a more regulated way.
143: */
144: void fatal(Object m);
145:
146: /**
147: * @since MMBase-1.8
148: */
149: void fatal(Object m, Throwable t);
150:
151: /**
152: * Returns true if for this category (Logger), a call to trace
153: * would do something.
154: */
155: public boolean isTraceEnabled();
156:
157: /**
158: * Returns true if for this category (Logger), a call to debug (or
159: * trace) would do something.
160: */
161: public boolean isDebugEnabled();
162:
163: // public boolean isInfoEnabled();
164:
165: /**
166: * Returns true if for this category (Logger), a call to service
167: * (or debug or trace) would do something.
168: */
169: public boolean isServiceEnabled();
170:
171: /**
172: * If you want to override the level in the configuration file
173: * fixed for this category, you can do it with this method. This
174: * could be usefull for example to switch on all debug logging
175: * when something has gone wrong.
176: * @param p The level of the priority. One of the constants
177: * Level.TRACE, Level.DEBUG, Level.SERVICE, Level.INFO,
178: * Level.WARN, Level.ERROR or Level.FATAL.
179: */
180:
181: public void setLevel(Level p);
182:
183: }
|