Holger's Java API

## com.antelmann.util.logging
Class Logger

    java.lang.Object
      com.antelmann.util.logging.Logger

All Implemented Interfaces:
  Enabled, Filter<LogEntry>, Forgeable<Logger>, QueryMechanism

    public class Logger

extends Object
implements Filter<LogEntry>, Forgeable<Logger>, QueryMechanism, Enabled

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.

Author:
  Holger Antelmann
See Also:
  `LogWriter`, `LoggerCache`, `LogEntry`, `LogException`

Field Summary

Fields inherited from interface com.antelmann.util.Filter
`EXCLUDE_ALL_FILTER, INCLUDE_ALL_FILTER`

Fields inherited from interface com.antelmann.util.Enabled
`FILTER`

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... writer)`

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
`void` `clearLast()` sets the last logged entry to null
`void` `closeAllWriters()` convenience method: attempts to close all embedded writers - if applicable
`boolean` `containsWriter(LogWriter writer)`
`LogExceptionHandler` `getExceptionHandler()` if the LogExceptionHandler is null (which it is by default), any LogException during logging is propagated to the calling application.
`Filter<? super LogEntry>` `getFilter()` returns null by default
`LogEntry` `getLast()` returns the last entry logged with this logger (while enabled and filter passed).
`LogWriter[]` `getWriters()`
`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)
`boolean` `isResolveOriginIfMissing()`
`void` `log(Level level, String message, long time, String sourceClass, String sourceString, Throwable thrown, String threadName, StackTraceElement[] stack, Object[] parameters)`
`void` `log(Level level, String message, Object... parameters)`
`void` `log(LogEntry entry)` logs the entry by writing to the writers after checking whether the logger is enabled and the filter (if available) accepts the entry.
`void` `log(Object origin, Level level, String message, Object... parameters)`
`void` `log(Object origin, Level level, Throwable thrown, String message, Object... parameters)`
`void` `log(Object origin, String message, Object... parameters)`
`void` `log(Object origin, Throwable thrown)`
`void` `log(String message, Object... parameters)`
`void` `log(Throwable thrown)`
`void` `log(Throwable thrown, String message, Object... parameters)`

`

`<T> T`

`

`query(Class<T> requiredReturnType, Object context)`
returns the first embedded LogWriter that is also an instance of the given requiredReturnType or null

`void` `removeAllWriters()`
`boolean` `removeWriter(LogWriter writer)` removes the given writer from the list of log writers
`void` `setAllFrom(Logger logger)` copies the properties of the given object and applies them to this instance, so that its behavior in regards to the given object can be matched to the extend that the implementing class supports that behavior.
`void` `setEnabled(boolean flag)` allows to enable/disable this instance
`void` `setExceptionHandler(LogExceptionHandler handler)`
`void` `setFilter(Filter<? super LogEntry> filter)`
`void` `setIncludeStack(boolean on)`
`void` `setResolveOriginIfMissing(boolean flag)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### Logger

    public Logger()

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

### Logger

    public Logger(LogWriter... writer)

### Logger

    public Logger(Logger logger)

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

Method Detail

### query

    public <T> T query(Class<T> requiredReturnType,
                       Object context)
            throws IllegalArgumentException

  returns the first embedded LogWriter that is also an instance of the given requiredReturnType or null

  Specified by:
    `query` in interface `QueryMechanism`
  Type Parameters:
    `T` - the required return type
  Parameters:
    `requiredReturnType` - specifies the return type that is needed for this operation; if Object.class is given, any returned object is admissible
    `context` - provides a context parameter for which the desired instance is to be returned. Often (if no other meaningful context is required or applicable), it makes sense to pass a reference to the calling object source; null may also be allowed
  Returns:
    an instance of the required return type that matches the given context; null may be returned if no instance is available for the given context
  Throws:
    `IllegalArgumentException` - if the given requiredReturnType doesn't implement LogWriter

### setAllFrom

    public void setAllFrom(Logger logger)

  Description copied from interface: `Forgeable`
  copies the properties of the given object and applies them to this instance, so that its behavior in regards to the given object can be matched to the extend that the implementing class supports that behavior.

  Specified by:
    `setAllFrom` in interface `Forgeable<Logger>`
  Parameters:
    `logger` - the object whose behavior is to be copied to this instance

### getWriters

    public LogWriter[] getWriters()

### addWritersFromLogger

    public void addWritersFromLogger(Logger logger)

  adds all LogWriter handler from the given logger

### includesStack

    public boolean includesStack()

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

### setIncludeStack

    public void setIncludeStack(boolean on)

### isResolveOriginIfMissing

    public boolean isResolveOriginIfMissing()

### setResolveOriginIfMissing

    public void setResolveOriginIfMissing(boolean flag)

### addWriter

    public boolean addWriter(LogWriter writer)

  adds the given handler to the list of handlers this Logger writes to

  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

  Returns:
    true if the set contained the handler

### containsWriter

    public boolean containsWriter(LogWriter writer)

### removeAllWriters

    public void removeAllWriters()

### closeAllWriters

    public void closeAllWriters()

  convenience method: attempts to close all embedded writers - if applicable

### log

    public void log(String message,
                    Object... parameters)
             throws LogException

  Throws:
    `LogException`

### log

    public void log(Level level,
                    String message,
                    Object... parameters)
             throws LogException

  Throws:
    `LogException`

### log

    public void log(Throwable thrown)
             throws LogException

  Throws:
    `LogException`

### log

    public void log(Throwable thrown,
                    String message,
                    Object... parameters)
             throws LogException

  Throws:
    `LogException`

### log

    public void log(Object origin,
                    String message,
                    Object... parameters)
             throws LogException

  Throws:
    `LogException`

### log

    public void log(Object origin,
                    Level level,
                    String message,
                    Object... parameters)
             throws LogException

  Throws:
    `LogException`

### log

    public void log(Object origin,
                    Throwable thrown)
             throws LogException

  Throws:
    `LogException`

### log

    public void log(Object origin,
                    Level level,
                    Throwable thrown,
                    String message,
                    Object... parameters)
             throws LogException

  Throws:
    `LogException`

### log

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

  Throws:
    `LogException`

### isEnabled

    public boolean isEnabled()

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

  Specified by:
    `isEnabled` in interface `Enabled`

### setEnabled

    public void setEnabled(boolean flag)

  Description copied from interface: `Enabled`
  allows to enable/disable this instance

  Specified by:
    `setEnabled` in interface `Enabled`

### getFilter

    public Filter<? super LogEntry> getFilter()

  returns null by default

### 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

  Specified by:
    `accept` in interface `Filter<LogEntry>`
  See Also:
    `getWriters()`

### setFilter

    public void setFilter(Filter<? super LogEntry> filter)

### setExceptionHandler

    public void setExceptionHandler(LogExceptionHandler handler)

### 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)`, `LogExceptionHandler.EXCEPTION_IGNORER`

### log

    public void log(LogEntry entry)
             throws LogException

  logs the entry by writing to the writers after checking whether the logger is enabled and the filter (if available) accepts the entry. This is the method that ultimately called by all other logging methods. Only after all writers have been called, the last logging entry is set, i.e. if a writer would call `getLast()` while writing the entry, a previous entry would be returned.

  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)`

### getLast

    public LogEntry getLast()

  returns the last entry logged with this logger (while enabled and filter passed).

  See Also:
    `LoggerCache`

### clearLast

    public void clearLast()

  sets the last logged entry to null

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads