org.jscience.util.logging
Class Logger

java.lang.Object
  extended by org.jscience.util.logging.Logger

public class Logger
extends java.lang.Object

Logger somewhat leans on the functionality of the java.util.logging functionality of J2SE 1.4, but it's not quite the same (and was implemented before J2SE 1.4).

In addition to the J2SE functionality, it provides the full stack trace for the log. Whether or not the logging here is written synchronously or asynchronously, is left to the implementation for each LogWriter that is used with the Logger.

All logging methods may throw LogException - propagated from the LogWriter objects contained in the logger to the calling thread. The writing to the different LogWriters is always performed sequentially in the order the LogWriters were added to the Logger.

It is recommended to always use a log method with the origin parameter and pass the 'this' argument from the calling function; this will provide useful additional information for the log.

See Also:
LogWriter, LogEntry, LogException

Field Summary
protected  java.util.ArrayList<LogWriter> writers
          DOCUMENT ME!
 
Constructor Summary
Logger()
          creates an empty Logger that does not write to any log yet
Logger(Logger logger)
          uses the configuration from the given logger (including writers and filter)
Logger(LogWriter... handler)
          Creates a new Logger object.
 
Method Summary
 boolean accept(LogEntry entry)
          returns true only if the given entry will be logged by this logger and thus propagated to its handlers
 boolean addWriter(LogWriter writer)
          adds the given handler to the list of handlers this Logger writes to
 void addWritersFromLogger(Logger logger)
          adds all LogWriter handler from the given logger
 boolean containsWriter(LogWriter writer)
          DOCUMENT ME!
 LogExceptionHandler getExceptionHandler()
          if the LogExceptionHandler is null (which it is by default), any LogException during logging is propagated to the calling application.
 Filter<LogEntry> getFilter()
          returns null by default
 LogWriter[] getWriters()
          DOCUMENT ME!
 void ignoreLogExceptions()
          sets a LogExceptionHandler that simply ignores any given LogException, so no Exception will be propagated to the calling application if logging fails.
 boolean includesStack()
          returns true if a stack trace is produced when a Logger method creates a LogEntry (false by default)
 boolean isEnabled()
          the logger only logs if the return value is true (which it is by default)
 void log(Level level, java.lang.String message, long time, java.lang.String sourceClass, java.lang.String sourceString, java.lang.Throwable thrown, java.lang.String threadName, java.lang.StackTraceElement[] stack, java.lang.Object[] parameters)
          DOCUMENT ME!
 void log(Level level, java.lang.String message, java.lang.Object... parameters)
          DOCUMENT ME!
 void log(LogEntry entry)
          logs the entry providing the logger is enabled and the filter (if available) accepts the entry.
 void log(java.lang.Object origin, Level level, java.lang.String message, java.lang.Object... parameters)
          DOCUMENT ME!
 void log(java.lang.Object origin, Level level, java.lang.String message, java.lang.Throwable thrown, java.lang.Object... parameters)
          DOCUMENT ME!
 void log(java.lang.Object origin, java.lang.String message, java.lang.Object... parameters)
          DOCUMENT ME!
 void log(java.lang.Object origin, java.lang.Throwable thrown)
          DOCUMENT ME!
 void log(java.lang.String message, java.lang.Object... parameters)
          DOCUMENT ME!
 void log(java.lang.String message, java.lang.Throwable thrown, java.lang.Object... parameters)
          DOCUMENT ME!
 void log(java.lang.Throwable thrown)
          DOCUMENT ME!
 void removeAllWriters()
          DOCUMENT ME!
 boolean removeWriter(LogWriter writer)
          removes the given writer from the list of log writers
 void setEnabled(boolean flag)
          DOCUMENT ME!
 void setExceptionHandler(LogExceptionHandler handler)
          DOCUMENT ME!
 void setFilter(Filter<LogEntry> filter)
          DOCUMENT ME!
 void setIncludeStack(boolean on)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

writers

protected java.util.ArrayList<LogWriter> writers
DOCUMENT ME!

Constructor Detail

Logger

public Logger()
creates an empty Logger that does not write to any log yet


Logger

public Logger(LogWriter... handler)
Creates a new Logger object.


Logger

public Logger(Logger logger)
uses the configuration from the given logger (including writers and filter)

Method Detail

getWriters

public LogWriter[] getWriters()
DOCUMENT ME!

Returns:
DOCUMENT ME!

addWritersFromLogger

public void addWritersFromLogger(Logger logger)
adds all LogWriter handler from the given logger

Parameters:
logger - DOCUMENT ME!

includesStack

public boolean includesStack()
returns true if a stack trace is produced when a Logger method creates a LogEntry (false by default)

Returns:
DOCUMENT ME!

setIncludeStack

public void setIncludeStack(boolean on)

addWriter

public boolean addWriter(LogWriter writer)
adds the given handler to the list of handlers this Logger writes to

Parameters:
writer - DOCUMENT ME!
Returns:
true if the set did not already contain the writer

removeWriter

public boolean removeWriter(LogWriter writer)
removes the given writer from the list of log writers

Parameters:
writer - DOCUMENT ME!
Returns:
true if the set contained the handler

containsWriter

public boolean containsWriter(LogWriter writer)
DOCUMENT ME!

Parameters:
writer - DOCUMENT ME!
Returns:
DOCUMENT ME!

removeAllWriters

public void removeAllWriters()
DOCUMENT ME!


log

public void log(java.lang.String message,
                java.lang.Object... parameters)
         throws LogException
DOCUMENT ME!

Parameters:
message - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

log

public void log(Level level,
                java.lang.String message,
                java.lang.Object... parameters)
         throws LogException
DOCUMENT ME!

Parameters:
level - DOCUMENT ME!
message - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

log

public void log(java.lang.Throwable thrown)
         throws LogException
DOCUMENT ME!

Parameters:
thrown - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

log

public void log(java.lang.String message,
                java.lang.Throwable thrown,
                java.lang.Object... parameters)
         throws LogException
DOCUMENT ME!

Parameters:
message - DOCUMENT ME!
thrown - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

log

public void log(java.lang.Object origin,
                java.lang.String message,
                java.lang.Object... parameters)
         throws LogException
DOCUMENT ME!

Parameters:
origin - DOCUMENT ME!
message - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

log

public void log(java.lang.Object origin,
                Level level,
                java.lang.String message,
                java.lang.Object... parameters)
         throws LogException
DOCUMENT ME!

Parameters:
origin - DOCUMENT ME!
level - DOCUMENT ME!
message - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

log

public void log(java.lang.Object origin,
                java.lang.Throwable thrown)
         throws LogException
DOCUMENT ME!

Parameters:
origin - DOCUMENT ME!
thrown - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

log

public void log(java.lang.Object origin,
                Level level,
                java.lang.String message,
                java.lang.Throwable thrown,
                java.lang.Object... parameters)
         throws LogException
DOCUMENT ME!

Parameters:
origin - DOCUMENT ME!
level - DOCUMENT ME!
message - DOCUMENT ME!
thrown - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

log

public void log(Level level,
                java.lang.String message,
                long time,
                java.lang.String sourceClass,
                java.lang.String sourceString,
                java.lang.Throwable thrown,
                java.lang.String threadName,
                java.lang.StackTraceElement[] stack,
                java.lang.Object[] parameters)
         throws LogException
DOCUMENT ME!

Parameters:
level - DOCUMENT ME!
message - DOCUMENT ME!
time - DOCUMENT ME!
sourceClass - DOCUMENT ME!
sourceString - DOCUMENT ME!
thrown - DOCUMENT ME!
threadName - DOCUMENT ME!
stack - DOCUMENT ME!
parameters - DOCUMENT ME!
Throws:
LogException - DOCUMENT ME!

isEnabled

public boolean isEnabled()
the logger only logs if the return value is true (which it is by default)

Returns:
DOCUMENT ME!

setEnabled

public void setEnabled(boolean flag)
DOCUMENT ME!

Parameters:
flag - DOCUMENT ME!

getFilter

public Filter<LogEntry> getFilter()
returns null by default

Returns:
DOCUMENT ME!

accept

public boolean accept(LogEntry entry)
returns true only if the given entry will be logged by this logger and thus propagated to its handlers

See Also:
getWriters()

setFilter

public void setFilter(Filter<LogEntry> filter)
DOCUMENT ME!

Parameters:
filter - DOCUMENT ME!

setExceptionHandler

public void setExceptionHandler(LogExceptionHandler handler)
DOCUMENT ME!

Parameters:
handler - DOCUMENT ME!

getExceptionHandler

public LogExceptionHandler getExceptionHandler()
if the LogExceptionHandler is null (which it is by default), any LogException during logging is propagated to the calling application.

See Also:
ignoreLogExceptions()

ignoreLogExceptions

public void ignoreLogExceptions()
sets a LogExceptionHandler that simply ignores any given LogException, so no Exception will be propagated to the calling application if logging fails. To reverse the effect of calling this method, simply set the LogExceptionHandler back to a null value - or use any other customized LogExceptionHandler.

See Also:
setExceptionHandler(LogExceptionHandler)

log

public void log(LogEntry entry)
         throws LogException
logs the entry providing the logger is enabled and the filter (if available) accepts the entry.

Parameters:
entry - DOCUMENT ME!
Throws:
LogException - if a LogWriter throws a LogException during logging. The exception handling can be controlled by setting an LogExceptionHandler. If no LogExceptionHandler is configured, the Exception is simply propagated to the calling method.
See Also:
getFilter(), isEnabled(), ignoreLogExceptions(), setExceptionHandler(LogExceptionHandler)