org.apache.oodt.commons.io.Log Maven / Gradle / Ivy
Show all versions of oodt-commons Show documentation
// Licensed to the Apache Software Foundation (ASF) under one or more contributor
// license agreements. See the NOTICE.txt file distributed with this work for
// additional information regarding copyright ownership. The ASF licenses this
// file to you under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
package org.apache.oodt.commons.io;
import java.util.Date;
import java.util.Enumeration;
import java.util.StringTokenizer;
import java.util.Vector;
/** The log.
*
* This class represents the application- or applet-wide logging facility. If your
* application needs to log messages, here's your class.
*
* To log a message, you call one of the get methods of this class to
* yield a {@link LogWriter} object. You can then call methods like {@link
* LogWriter#println(String)} to log a line of text. A typical invocation is
*
*
Log.get().println("Buffer of length " + length + " allocated.");
*
* This logs the given text using the default source string, and under the default
* category, and timestamped with the current time. You can reuse the
* LogWriter, but the timestamp, source, and category won't change. You
* should get a fresh LogWriter.
*
*
Sources identify independent origins of log messages, such as
* independent threads in a program, or independent programs. Sources are just strings.
* If you don't specify a source, you get a default source. You can set the default
* source with {@link #setDefaultSource}. You always get a source with every
* message, even if it's a default source. If you don't otherwise set a default source
* string, the source is "app".
*
*
Categories identify different classes or priorites of messages.
* Categories can be simple strings like "warning" or "debug", or they can be complex
* objects. You get to define your categories. Your group ought to agree on categories,
* though. If you don't specify a category, you get a default category. You can set the
* default category with {@link #setDefaultCategory}. If you don't call that method, the
* default category is the String object "message".
*
*
Streams identify independent activities within a program, which
* often have transient lifespans. They're not separate output streams, but
* instead are separate, named entities representing separate activities (although a
* {@link LogListener} may put messages into separate output streams identified by each
* stream). Activity streams are identified by strings. To indicate the start and stop
* of streams, call {@link #startStream} and {@link #stopStream}. These send
* stream-started and stream-stopped events to the log listeners, who may choose to pay
* attention to them or ignore them. You can use streams to indicate to the log the start
* and the stop of activities such as an analyst examining the system, or a server
* handling a particular client.
*
*
All messages logged with this class go to one or more {@link LogListener} objects.
* A LogListener accepts logging events, such as a message being logged, and does
* something with it, such as writing the message to a file. Call {@link #addLogListener}
* to add a log listener. Logging of a message, starting a stream, and stopping a stream
* all get turned into {@link LogEvent}s and are multicasted to every registered listener.
*
*
The logging facility bootstraps itself with one or more log listeners specified by
* the system property org.apache.oodt.commons.io.Log.loggers. This property must be a
* space-separated list of complete class names. The logging facility will create an
* object of each class listed and add it as if you had called
* addLogListener. (You can specify system properties on the command line or
* in the applet tag.)
*
* @see LogListener
* @see LogWriter
* @author Kelly
*/
public class Log {
/** Currently registered LogListeners.
*/
private static Vector listeners;
static {
listeners = new Vector();
String loggers = System.getProperty("org.apache.oodt.commons.io.Log.loggers", "");
StringTokenizer tokenizer = new StringTokenizer(loggers);
while (tokenizer.hasMoreTokens()) {
String className = tokenizer.nextToken();
try {
Class clazz = Class.forName(className);
LogListener listener = (LogListener) clazz.newInstance();
addLogListener(listener);
} catch (Exception e) {
System.err.println("Can't create log listener object from class " + className + ": " + e);
System.exit(1);
}
}
}
/** Get a writer to log messages.
*
* The writer will log messages with the current time, default category, and
* default source. Messages will go into the general log.
*
* @return A writer with which you can log messages.
*/
public static LogWriter get() {
if (lastWriter != null && !lastWriter.isFlushed()) {
return lastWriter;
} else {
return get(new Date(), getDefaultSource(), getDefaultCategory());
}
}
/** Get a writer to log messages.
*
* The writer will log messages with the current time, specified category, and
* default source. Messages will go into the general log.
*
* @param category The messages' category.
* @return A writer with which you can log messages.
*/
public static LogWriter get(Object category) {
return get(new Date(), getDefaultSource(), category);
}
/** Get a writer to log messages.
*
* The writer will log messages with the specified time, specified category, and
* specified source.
*
* @param timestamp The time for messages logged with the returned writer.
* @param source The source of the log message.
* @param category The messages' category.
* @return A writer with which you can log messages.
*/
public static synchronized LogWriter get(Date timestamp, String source, Object category) {
lastWriter = new LogWriter(timestamp, source, category);
return lastWriter;
}
/** Start a new log stream.
*
* This method notifies the {@link LogListener}s that a new logging stream has
* started.
*
* @param stream The name of the stream.
* @param timestamp The time the stream started. To use the current time, pass a new {@link Date} object.
* @param source A string identifying who or what started the stream.
*/
public static void startStream(String stream, Date timestamp, String source) {
LogEvent event = null;
for (Enumeration e = listeners.elements(); e.hasMoreElements();) {
// Lazily create the event.
if (event == null) {
event = new LogEvent(stream, timestamp, source);
}
((LogListener) e.nextElement()).streamStarted(event);
}
}
/** Stop a stream.
*
* This method notifies the {@link LogListener}s that a logging stream has stopped.
*
* @param stream The name of the stream that stopped.
*/
public static void stopStream(String stream) {
LogEvent event = null;
for (Enumeration e = listeners.elements(); e.hasMoreElements();) {
// Lazily create the event.
if (event == null) {
event = new LogEvent(stream);
}
((LogListener) e.nextElement()).streamStopped(event);
}
}
/** Log a message.
*
* The {@link LogWriter}s call this when they've built up a complete message and
* want it multicasted to the {@link LogListener}s.
*
* @param timestamp The message's timestamp.
* @param source The source label of the message.
* @param category The message's category.
* @param message The message.
*/
static void logMessage(Date timestamp, String source, Object category, String message) {
LogEvent event = null;
for (Enumeration e = listeners.elements(); e.hasMoreElements();) {
// Lazily create the event.
if (event == null) {
event = new LogEvent(timestamp, source, category, message);
}
((LogListener) e.nextElement()).messageLogged(event);
}
}
/** Set the default source.
*
* This sets the default source label used for logging.
*
* @param source The new default source label.
*/
public static void setDefaultSource(String source) {
if (source == null) {
throw new IllegalArgumentException("Can't set a null default source");
}
defaultSource = source;
}
/** Get the default source.
*
* @return The default source label.
*/
public static String getDefaultSource() {
return defaultSource;
}
/** Set the default category.
*
* This sets the category object that's used by default for logging.
*
* @param category The new default category object.
*/
public static void setDefaultCategory(Object category) {
if (category == null) {
throw new IllegalArgumentException("Can't set a null default category");
}
defaultCategory = category;
}
/** Get the default category.
*
* @return The default category object.
*/
public static Object getDefaultCategory() {
return defaultCategory;
}
/** Add a log listener.
*
* The listener will be notified whenever a message is logged, a stream started,
* or a stream stopped.
*
* @param listener The listener to add.
*/
public static void addLogListener(LogListener listener) {
if (listener == null) {
throw new IllegalArgumentException("Can't add a null log listener");
}
listeners.addElement(listener);
}
/** Remove a log listener.
*
* The listener won't receive anymore events unless it's added back.
*
* @param listener The listener to remove.
*/
public static void removeLogListener(LogListener listener) {
if (listener == null) {
throw new IllegalArgumentException("Can't remove a null log listener");
}
listeners.removeElement(listener);
}
/** The default source label.
*/
private static String defaultSource = "app";
/** The default category object.
*/
private static Object defaultCategory = "message";
/** Last log writer created so it can be reused. */
private static LogWriter lastWriter;
/** Don't allow instantiation.
*
* When we convert to Java 2, this should throw UnsupportedOperationException.
*/
private Log() {}
}