001: /*
002: * <copyright>
003: *
004: * Copyright 1997-2004 BBNT Solutions, LLC
005: * under sponsorship of the Defense Advanced Research Projects
006: * Agency (DARPA).
007: *
008: * You can redistribute this software and/or modify it under the
009: * terms of the Cougaar Open Source License as published on the
010: * Cougaar Open Source Website (www.cougaar.org).
011: *
012: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
013: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
014: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
015: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
016: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
017: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
018: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
022: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
023: *
024: * </copyright>
025: */
026:
027: package org.cougaar.util.log;
028:
029: /**
030: * The Logger provides a generic logging API.
031: * <p>
032: * This provides the basic: <pre>
033: * if (log.isDebugEnabled()) {
034: * log.debug("my message");
035: * }
036: * </pre> and related logging methods.
037: * <p>
038: * This API is a subset of the "log4j" API, but the underlying
039: * implementation may use a different logger, such as "jsr47".
040: * <p>
041: * Note that (currently) the Logger user is unable to alter the
042: * underlying logger's threshold level. A separate
043: * LoggerController must be used to make such modifications.
044: * <p>
045: * An enhancement idea is to allow a Logger user to alter this
046: * level -- for example, this could be used to increase logging
047: * detail when an error is deteted. For now the equivalent
048: * behavior can be obtained by using "log(level, ..)" and
049: * selecting the "level" value at runtime.
050: */
051: public interface Logger {
052:
053: /**
054: * Generic logging levels.
055: * <p>
056: * The value of these constants may be modified in the future
057: * without notice. For example, "DEBUG" may be changed from
058: * "1" to some other integer constant. However, the ordering
059: * of:<pre>
060: * DETAIL < DEBUG < INFO < WARN < ERROR < SHOUT < FATAL
061: * </pre><br> is guaranteed.
062: */
063: int DETAIL = 1;
064: int DEBUG = 2;
065: int INFO = 3;
066: int WARN = 4;
067: int ERROR = 5;
068: int SHOUT = 6;
069: int FATAL = 7;
070:
071: /**
072: * Logger users should check "isEnabledFor(..)" before requesting
073: * a log message, to prevent unnecessary string creation.
074: *
075: * <p>
076: * <pre>
077: * When the log message requires constructing a String (e.g.
078: * by using "+", or by calculating some value), then the
079: * "is*Enabled(..)" check is preferred. For example:
080: * if (isDebugEnabled()) {
081: * debug("good, this message will be logged, "+someArg);
082: * }
083: * is prefered to:
084: * debug("maybe this will be logged, maybe wasteful, "+someArg);
085: *
086: * The one exception is when the message is a constant string,
087: * in which case the "is*Enabled(..)" check is unnecessary.
088: * For example:
089: * debug("a constant string is okay");
090: * is just as good as:
091: * if (isDebugEnabled()) {
092: * debug("isDebug check not needed, but harmless");
093: * }
094: * However, developers often modify their logging statements,
095: * so it's best to always use the "is*Enabled(..)" pattern.
096: * </pre>
097: * <p>
098: *
099: * Although this seems like a minor point, these string allocations
100: * can add up to a potentially large (and needless) performance
101: * penalty when the logging level is turned down.
102: *
103: * @param level a logging level, such as DEBUG
104: */
105: boolean isEnabledFor(int level);
106:
107: /**
108: * Append the specified message to the log, but <i>only</i> if the
109: * logger includes the specified logging level.
110: *
111: * @param level the required logging level (DEBUG, WARN, etc)
112: * @param message the string to log
113: *
114: * @see #isEnabledFor(int)
115: */
116: void log(int level, String message);
117:
118: /**
119: * Append both specified message and throwable to the log, but
120: * <i>only</i> if the logger includes the specified logging level.
121: * <p>
122: * If the throwable is null then this is equivalent to:<pre>
123: * log(level, message).</pre>
124: *
125: * @param level the required logging level (DEBUG, WARN, etc)
126: * @param message the string to log
127: * @param t the throwable (e.g. RuntimeException) that is
128: * related to the message
129: *
130: * @see #isEnabledFor(int)
131: */
132: void log(int level, String message, Throwable t);
133:
134: //
135: // all methods after this point are all "shorthand" methods that
136: // either call "isEnabledFor(..)" or "log(..)". In some cases
137: // the shorthand is slightly more efficient than the equivalent
138: // (generic) "isEnabledFor(..)" and/or "log(..)" call.
139: //
140:
141: //
142: // specific "isEnabledFor(..)" shorthand methods:
143: //
144:
145: boolean isDetailEnabled();
146:
147: boolean isDebugEnabled();
148:
149: boolean isInfoEnabled();
150:
151: boolean isWarnEnabled();
152:
153: boolean isErrorEnabled();
154:
155: boolean isShoutEnabled();
156:
157: boolean isFatalEnabled();
158:
159: //
160: // specific "level" shorthand methods:
161: //
162:
163: /**
164: * Equivalent to "log(DETAIL, ..)".
165: */
166: void detail(String message);
167:
168: void detail(String message, Throwable t);
169:
170: /**
171: * Equivalent to "log(DEBUG, ..)".
172: */
173: void debug(String message);
174:
175: void debug(String message, Throwable t);
176:
177: /**
178: * Equivalent to "log(INFO, ..)".
179: */
180: void info(String message);
181:
182: void info(String message, Throwable t);
183:
184: /**
185: * Equivalent to "log(WARN, ..)".
186: */
187: void warn(String message);
188:
189: void warn(String message, Throwable t);
190:
191: /**
192: * Equivalent to "log(ERROR, ..)".
193: */
194: void error(String message);
195:
196: void error(String message, Throwable t);
197:
198: /**
199: * Equivalent to "log(SHOUT, ..)".
200: */
201: void shout(String message);
202:
203: void shout(String message, Throwable t);
204:
205: /**
206: * Equivalent to "log(FATAL, ..)".
207: */
208: void fatal(String message);
209:
210: void fatal(String message, Throwable t);
211:
212: void printDot(String dot);
213: }
|