001: /**
002:
003: Copyright (C) 2002-2003 Together
004:
005: This library is free software; you can redistribute it and/or
006: modify it under the terms of the GNU Lesser General Public
007: License as published by the Free Software Foundation; either
008: version 2.1 of the License, or (at your option) any later version.
009:
010: This library is distributed in the hope that it will be useful,
011: but WITHOUT ANY WARRANTY; without even the implied warranty of
012: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: Lesser General Public License for more details.
014:
015: You should have received a copy of the GNU Lesser General Public
016: License along with this library; if not, write to the Free Software
017: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018:
019: Logger.java
020: Date: 02.12.2003.
021: @version 1.0.0
022: @authors:
023: Milosevic Sinisa sinisa@prozone.co.yu
024: Radoslav Dutina rale@prozone.co.yu
025: Zoran Milakovic zoran@prozone.co.yu
026: */package org.webdocwf.util.loader.logging;
027:
028: import java.io.IOException;
029:
030: /**
031: * A general-purpose logging facility. It is modeled after
032: * <CODE>syslogd</CODE>. This is a base class from which an actual
033: * implementation is derived. It only defines how log message are written
034: * by a client. Where the log message is written and the mechanism for
035: * controlling logging is left up to the implementation. This class does
036: * not define any of these mechanism and their definition is not necessary
037: * for understand how to use this class. <P>
038: *
039: * Each log message is associate with a facility and has a level assigned
040: * to it. A facility is a symbolic (String) name that defines a class of
041: * log messages. A level is used to indicate the
042: *
043: It is expected that the implementation can enable, disable and
044: * direct log messages based on these attributes. Facilities and levels
045: * are defined symbolicly, with no restriction on the name, and form a tuple.
046: * Several standard levels are defined as integer constants and their use
047: * is expected to be higher performing than symbolic levels..<P>
048: *
049: *
050: *Normally, a single,
051: global instance of the object
052: * is exists and is obtainable by a static method in this class.<P>
053: *
054: * Log messages are written via an object implementing <CODE>LogChannel</CODE>.
055: * A channel is associated with a single facility, with the level being
056: * specified when a message is written. Normally, a <CODE>LogChannel</CODE>
057: * is obtained once at initialization time and use repeatedly. It is
058: * permissible to obtain multiple references to the log channel for a facility,
059: * but this is discouraged for performance reasons.<P>
060: *
061: * Log messages, even debugging ones, should be defined with care. They
062: * should be terse, but clear to someone who isn't intimately familiar with
063: * the code. Permanent debugging messages should be designed with the idea
064: * of use when supportting a deployed product.<P>
065: *
066: * The central logging object needs to be configured very early in the startup
067: * process. If logging can't be configured, then the startup should be aborted
068: * or a object created that does some simple form of logging, such as write
069: * to <CODE>stderr<CODE>. A client should never have to check if the global
070: * logger object exists.<P>
071: *
072: */
073: public abstract class Logger {
074:
075: /**
076: * Standard level.
077: */
078: public static final int LOGMODE_NORMAL = 1;
079:
080: /**
081: * A condition that should be corrected immediately
082: */
083: public static final int LOGMODE_NONE = 0;
084:
085: /**
086: * Critical conditions.
087: */
088: public static final int LOGMODE_FULL = 2;
089:
090: public static final String strLOGMODE_NONE = "NONE";
091: public static final String strLOGMODE_NORMAL = "NORMAL";
092: public static final String strLOGMODE_FULL = "FULL";
093:
094: public boolean[] enbledLogLevels;
095:
096: /**
097: * Global <CODE>Logger</CODE> object.
098: */
099: protected static Logger centralLogger;
100:
101: /**
102: * Table of standard level names
103: */
104: protected static final String[] standardLevelNames = {
105: strLOGMODE_NORMAL, // 0
106: strLOGMODE_NONE, // 1
107: strLOGMODE_FULL // 2
108: };
109:
110: /**
111: * Get the central (global) logging object.
112: *
113: * @return A reference the object. If the facility has not been
114: * initialized <CODE>null</CODE> is returned. However, this is
115: * considered a bug in the design of the initialization. Clients
116: * do not need to check for <CODE>null</CODE>.
117: */
118: public static Logger getCentralLogger() {
119: return centralLogger;
120: }
121:
122: /**
123: * Configure Logger with given config file, interpreting of config file is
124: * logger implementation specific.
125: *
126: * @param confFilePath Path to configuration file.
127: * @throws Exception
128: */
129: abstract public void configure(String confFilePath)
130: throws Exception;
131:
132: /**
133: * Determine if logging is enabled for the specified level. This
134: * is useful to prevent a series of unnecessary logging calls,
135: * as often encountered with debug logging, or a call where generating
136: * the message is expensive.
137: *
138: * @param level Numeric level that is to be checked.
139: * @return <CODE>true</CODE> if enabled, <CODE>false</CODE> if not
140: * enabled.
141: */
142: abstract public boolean isEnabled(int level);
143:
144: /**
145: * Determine if logging is enabled for the specified level. This
146: * is useful to prevent a series of unnecessary logging calls,
147: * as often encountered with debug logging, or a call where generating
148: * the message is expensive.
149: *
150: * @param level Symbolic level that is to be checked.
151: * @return <CODE>true</CODE> if enabled, <CODE>false</CODE> if not
152: * enabled.
153: */
154: abstract public boolean isEnabled(String level);
155:
156: /**
157: * Convert a symbolic level to an integer identifier.
158: *
159: * @param level Symbolic level to convert
160: * @return The numeric level identifier
161: */
162: abstract public int getLevel(String level);
163:
164: /**
165: * Write a string to the log file.
166: *
167: * @param level Numeric level the message is associated with.
168: * @param msg The message to log.
169: */
170: abstract public void write(int level, String msg);
171:
172: /**
173: * Write a string to the log file.
174: *
175: * @param level Symbolic level the message is associated with.
176: * @param msg The message to log.
177: */
178: abstract public void write(String level, String msg);
179:
180: /**
181: * Write a string and exception to the log file.
182: *
183: * @param level Numeric level the message is associated with.
184: * @param msg The message to log.
185: * @param throwable Exception or error to log.
186: */
187: abstract public void write(int level, String msg,
188: Throwable throwable);
189:
190: /**
191: * Write a string and exception to the log file.
192: *
193: * @param level Symbolic level the message is associated with.
194: * @param msg The message to log.
195: * @param throwable Exception or error to log.
196: */
197: abstract public void write(String level, String msg,
198: Throwable throwable);
199:
200: abstract public boolean[] getEnabledLogLevels();
201:
202: abstract public void setEnabledLogLevels(String logMode);
203:
204: abstract public boolean setMessage(String key, String value);
205:
206: abstract public String getMessage(String key);
207:
208: abstract public boolean writeEcho(String strLogTxt);
209:
210: abstract public void close();
211: }
|