de.esprit.common.log

## Class LogChannel

- java.lang.Object
- - de.esprit.common.log.LogChannel

- All Implemented Interfaces:
    CloseableComponent, LogLevelEvent.Source, LogMessageEvent.Source, LogSupport, java.lang.AutoCloseable

      public final class LogChannel
      extends java.lang.Object
      implements LogSupport, CloseableComponent, LogMessageEvent.Source, LogLevelEvent.Source

  A `LogChannel` represents a named channel where you can print out log messages (errors, infos, warnings, etc). It serves as a message dispatcher who passes the incoming message to all registered `LogPrinter` objects.

  #### Default LogPrinters

  This class maintains three default `LogPrinter`s which are:
  - Console output
    An internal `LogPrinterConsole` which can be activated/deactivated with the `openLogConsolePrinter()`/`closeLogConsolePrinter()` methods.
  - Log file output
    An internal `LogPrinterFile` which can be activated with the `openLogFilePrinter(File)`/`closeLogFilePrinter()` methods.
  - Log frame output
    An internal `LogPrinterFrame` which can be activated/deactivated with the `openLogFramePrinter(String)`/`closeLogFramePrinter()`methods.
  Note that a LogPrinterConsole is created by default - thus any output will be printed to the system console. If this is not desired, you should call `closeLogConsolePrinter()` explicitly after construction.
  Author:
    Rainer Buesch
  See Also:
    `LogPrinter`, `LogMessageEvent`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT_LOG_CHANNEL_NAME`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addLogLevelListener(LogLevelEvent.Listener l)`
    `void` | `addLogMessageListener(LogMessageEvent.Listener l)`
    `void` | `awaitLogsDelivered()`
    `void` | `close()` Closes all attached LogPrinters.
    `static void` | `closeAll()`
    `void` | `closeLogConsolePrinter()` Stops output to the system console.
    `void` | `closeLogFilePrinter()` Closes the log-file.
    `void` | `closeLogFramePrinter()` Closes the LogFrame window and releases it's resources.
    `static boolean` | `existsLogChannel(java.lang.String channelName)`
    `protected void` | `finalize()`
    `static LogChannel` | `getDefault()`
    `static LogChannel` | `getLogChannel(java.lang.String channelName)` Returns a named LogChannel.
    `static java.util.List<LogChannel>` | `getLogChannels()`
    `LogPrinterConsole` | `getLogConsolePrinter()` Returns a reference to the LogPrinterConsole or `null` if none has been opened yet with `openLogConsole()`.
    `LogPrinterFile` | `getLogFilePrinter()` Returns a reference to the LogPrinterFile or `null` if none has been opened yet with `openLogFile()`.
    `LogPrinterFrame` | `getLogFramePrinter()` Returns a reference to the LogPrinterFrame or `null` if none has been opened yet with `openLogFrame(String)`.
    `LogLevel` | `getLogLevel()` Returns the current LogLevel of this LogChannel.
    `java.lang.String` | `getName()` Returns the unique name of this logChannel.
    `boolean` | `isClosed()`
    `boolean` | `isLogDebug()` Returns true if a DEBUG log message should be printed.
    `boolean` | `isLogVerbose()` Returns true if a VERBOSE log message should be printed.
    `LogMessageEvent` | `log(java.lang.Object caller, LogLevel level, java.lang.String message, java.lang.Throwable e)` Creates a message from the given parameters and delivers it to all currently registered LogPrinter objects.
    `void` | `logDebug(java.lang.Object caller, java.lang.String message)`
    `void` | `logDump(java.lang.Object caller, java.lang.String message)`
    `void` | `logError(java.lang.Object caller, java.lang.Exception e)`
    `void` | `logError(java.lang.Object caller, java.lang.String message)`
    `void` | `logError(java.lang.Object caller, java.lang.String message, java.lang.Exception e)`
    `void` | `logFatal(java.lang.Object caller, java.lang.String message, java.lang.Exception e)`
    `void` | `logInfo(java.lang.Object caller, java.lang.String message)`
    `void` | `logVerbose(java.lang.Object caller, java.lang.String message)`
    `void` | `logWarning(java.lang.Object caller, java.lang.String message)`
    `static LogChannel` | `newLogChannel(java.lang.String channelName)` Same as `getLogChannel(String)` but ensures that the LogChannel did not yet exist.
    `LogPrinterConsole` | `openLogConsolePrinter()` Leads the tracing output to the system console (is true by default).
    `LogPrinterFile` | `openLogFilePrinter(java.io.File logDir)` Same as openLogFile(File, boolean).
    `LogPrinterFile` | `openLogFilePrinter(java.io.File logDir, boolean toFileOnly)` Same as openLogFile(File, boolean, boolean).
    `LogPrinterFile` | `openLogFilePrinter(java.io.File logDir, boolean useLastLogfile, boolean toFileOnly)` Requests the LogChannel to open a log file for logging all received messages into.
    `LogPrinterFrame` | `openLogFramePrinter(java.lang.String title)` Opens a GUI LogFrame that receives the messages.
    `void` | `removeLogLevelListener(LogLevelEvent.Listener l)`
    `void` | `removeLogMessageListener(LogMessageEvent.Listener l)`
    `void` | `setLogLevel(LogLevel level)` Sets the default `LogLevel` for `LogPrinter`s (the default is LogLevel.LOG_INFO.
    `java.lang.String` | `toString()` Returns the unique name of this logChannel.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_LOG_CHANNEL_NAME

          public static final java.lang.String DEFAULT_LOG_CHANNEL_NAME

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getDefault

          public static LogChannel getDefault()

    - #### getLogChannels

          public static java.util.List<LogChannel> getLogChannels()

    - #### existsLogChannel

          public static boolean existsLogChannel(java.lang.String channelName)

    - #### closeAll

          public static void closeAll()

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

      Overrides:
        `finalize` in class `java.lang.Object`
      Throws:
        `java.lang.Throwable`

    - #### getLogChannel

          public static LogChannel getLogChannel(java.lang.String channelName)

      Returns a named LogChannel. If the channel doesn't exist yet it will be created and cached in an internal list for reusage.

    - #### newLogChannel

          public static LogChannel newLogChannel(java.lang.String channelName)

      Same as `getLogChannel(String)` but ensures that the LogChannel did not yet exist. So you get a new one in any case.

    - #### getName

          public java.lang.String getName()

      Returns the unique name of this logChannel.

    - #### toString

          public java.lang.String toString()

      Returns the unique name of this logChannel.
      Overrides:
        `toString` in class `java.lang.Object`

    - #### openLogFilePrinter

          public LogPrinterFile openLogFilePrinter(java.io.File logDir)
                                            throws java.lang.Exception

      Same as openLogFile(File, boolean). Creates always a new logfile and continues logging to the system console.
      Throws:
        `java.lang.Exception`

    - #### openLogFilePrinter

          public LogPrinterFile openLogFilePrinter(java.io.File logDir,
                                          boolean toFileOnly)
                                            throws java.lang.Exception

      Same as openLogFile(File, boolean, boolean). Creates always a new logfile.
      Throws:
        `java.lang.Exception`

    - #### openLogFilePrinter

          public LogPrinterFile openLogFilePrinter(java.io.File logDir,
                                          boolean useLastLogfile,
                                          boolean toFileOnly)
                                            throws java.lang.Exception

      Requests the LogChannel to open a log file for logging all received messages into. The filename is automatically created within the given logDir. Note that the filename is assembled like this '/_.log'.
      Parameters:
        `logDir` - the target directory for logging (must exist).
        `useLastLogfile` - reopens the last logfile and continues writing there.
        `toFileOnly` - closes the system console (if any) and logs to the file only.
      Throws:
        `java.lang.Exception`

    - #### getLogFilePrinter

          public LogPrinterFile getLogFilePrinter()

      Returns a reference to the LogPrinterFile or `null` if none has been opened yet with `openLogFile()`.

    - #### closeLogFilePrinter

          public void closeLogFilePrinter()

      Closes the log-file.

    - #### openLogConsolePrinter

          public LogPrinterConsole openLogConsolePrinter()

      Leads the tracing output to the system console (is true by default).

    - #### getLogConsolePrinter

          public LogPrinterConsole getLogConsolePrinter()

      Returns a reference to the LogPrinterConsole or `null` if none has been opened yet with `openLogConsole()`.

    - #### closeLogConsolePrinter

          public void closeLogConsolePrinter()

      Stops output to the system console.

    - #### openLogFramePrinter

          public LogPrinterFrame openLogFramePrinter(java.lang.String title)

      Opens a GUI LogFrame that receives the messages. The LogFrame provides widgets to control the tracing level and message formatting.

    - #### getLogFramePrinter

          public LogPrinterFrame getLogFramePrinter()

      Returns a reference to the LogPrinterFrame or `null` if none has been opened yet with `openLogFrame(String)`.

    - #### closeLogFramePrinter

          public void closeLogFramePrinter()

      Closes the LogFrame window and releases it's resources.

    - #### close

          public void close()

      Closes all attached LogPrinters.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### isClosed

          public boolean isClosed()

    - #### isLogDebug

          public boolean isLogDebug()

      Returns true if a DEBUG log message should be printed. This is case, when the `LogChannel` or any of the `LogPrinter`s has the `LogLevel` set to DEBUG or higher (DUMP).
      Note: checking for this flag is useful to prevent the creation of lengthy DEBUG messages, which would not be printable due to the current logLevel.
      Specified by:
        `isLogDebug` in interface `LogSupport`

    - #### isLogVerbose

          public boolean isLogVerbose()

      Returns true if a VERBOSE log message should be printed. This is case, when the `LogChannel` or any of the `LogPrinter`s has the `LogLevel` set to VERBOSE or higher (DEBUG, DUMP).
      Note: checking for this flag is useful to prevent the creation of lengthy VERBOSE messages, which would not be printable due to the current logLevel.
      Specified by:
        `isLogVerbose` in interface `LogSupport`

    - #### setLogLevel

          public void setLogLevel(LogLevel level)

      Sets the default `LogLevel` for `LogPrinter`s (the default is LogLevel.LOG_INFO. Setting the level to null actually resets to LogLevel.LOG_INFO and resets all current `LogPrinter`s to use the level of their parent `LogChannel`.
      Specified by:
        `setLogLevel` in interface `LogSupport`
      See Also:
        `LogPrinter`

    - #### getLogLevel

          public LogLevel getLogLevel()

      Returns the current LogLevel of this LogChannel. Note that the LogLevels of the individual LogPrinters may be set differently.
      Specified by:
        `getLogLevel` in interface `LogSupport`

    - #### awaitLogsDelivered

          public void awaitLogsDelivered()

    - #### logFatal

          public void logFatal(java.lang.Object caller,
                      java.lang.String message,
                      java.lang.Exception e)

      Specified by:
        `logFatal` in interface `LogSupport`

    - #### logError

          public void logError(java.lang.Object caller,
                      java.lang.String message,
                      java.lang.Exception e)

      Specified by:
        `logError` in interface `LogSupport`

    - #### logError

          public void logError(java.lang.Object caller,
                      java.lang.Exception e)

    - #### logError

          public void logError(java.lang.Object caller,
                      java.lang.String message)

      Specified by:
        `logError` in interface `LogSupport`

    - #### logWarning

          public void logWarning(java.lang.Object caller,
                        java.lang.String message)

      Specified by:
        `logWarning` in interface `LogSupport`

    - #### logInfo

          public void logInfo(java.lang.Object caller,
                     java.lang.String message)

      Specified by:
        `logInfo` in interface `LogSupport`

    - #### logVerbose

          public void logVerbose(java.lang.Object caller,
                        java.lang.String message)

      Specified by:
        `logVerbose` in interface `LogSupport`

    - #### logDebug

          public void logDebug(java.lang.Object caller,
                      java.lang.String message)

      Specified by:
        `logDebug` in interface `LogSupport`

    - #### logDump

          public void logDump(java.lang.Object caller,
                     java.lang.String message)

      Specified by:
        `logDump` in interface `LogSupport`

    - #### log

          public LogMessageEvent log(java.lang.Object caller,
                            LogLevel level,
                            java.lang.String message,
                            java.lang.Throwable e)

      Creates a message from the given parameters and delivers it to all currently registered LogPrinter objects. Returns the MessageEvent if one was delivered according to the current LogLevel, null if no message was created.

    - #### addLogMessageListener

          public void addLogMessageListener(LogMessageEvent.Listener l)

      Specified by:
        `addLogMessageListener` in interface `LogMessageEvent.Source`

    - #### removeLogMessageListener

          public void removeLogMessageListener(LogMessageEvent.Listener l)

      Specified by:
        `removeLogMessageListener` in interface `LogMessageEvent.Source`

    - #### addLogLevelListener

          public void addLogLevelListener(LogLevelEvent.Listener l)

      Specified by:
        `addLogLevelListener` in interface `LogLevelEvent.Source`

    - #### removeLogLevelListener

          public void removeLogLevelListener(LogLevelEvent.Listener l)

      Specified by:
        `removeLogLevelListener` in interface `LogLevelEvent.Source`

Copyright © 2014 EsprIT-Systems. All Rights Reserved.