Package com.tibco.patterns.qbp

## Class AQBPLogger

- java.lang.Object
- - com.tibco.patterns.qbp.AQBPLogger

- Direct Known Subclasses:
    `QBPFileLogger`

      public abstract class AQBPLogger
      extends java.lang.Object

  An Abstract base for loggers used in the query builder. This defines a base class for loggers used in the query builder tool. The class provides for logging of configuration object errors along with standard errors. The recording of configuration errors into the configuration is provided by this base. The logger routines must be provided by the implementation.

  There are two types of errors:

  - User Configuration Errors. These are errors in the content of the configuration file.
  - Other Errors. These are all errors not associated with the configuration file.
  The logger can be set to log an error and then throw an exception - this is called exception mode, or to just log an error and return. The error types can be controlled independently.

  Configuration errors can be added to the configuration object as notes in addition to being logged. This can be turned on and off.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `AQBPLogger.LogLevel` | The different logging levels supported.
    `static class` | `AQBPLogger.QBPConfigException` | Exception thrown if in exception mode for configuration errors.
    `static class` | `AQBPLogger.QBPException` | Exception thrown if in exception mode for standard errors.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AQBPLogger()` | Default constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `getConfigNoteCount()` |
    `boolean` | `isConfigExceptionModeOn()` |
    `boolean` | `isStandardExceptionModeOn()` |
    `java.lang.String` | `logConfigError​(java.lang.String error_msg)` | Log a configuration error message.
    `java.lang.String` | `logConfigError​(java.lang.String error_msg, java.lang.Throwable reason)` | Log a configuration error message with an exception that caused the error.
    `void` | `logConfigFatal​(java.lang.String error_msg)` | Log a configuration fatal message.
    `void` | `logConfigFatal​(java.lang.String error_msg, java.lang.Throwable reason)` | Log a configuration fatal message with an exception that caused the error.
    `java.lang.String` | `logError​(java.lang.String error_msg)` | Log a standard error message.
    `java.lang.String` | `logError​(java.lang.String error_msg, java.lang.Throwable reason)` | Log a standard error message with an exception that caused the error.
    `void` | `logFatal​(java.lang.String error_msg)` | Log a standard fatal message.
    `void` | `logFatal​(java.lang.String error_msg, java.lang.Throwable reason)` | Log a standard fatal message with an exception that caused the error.
    `java.lang.String` | `logInfo​(java.lang.String info_msg)` | Log a general information message.
    `java.lang.String` | `logTrace​(java.lang.String trace_msg)` | Log a trace message.
    `java.lang.String` | `logWarning​(java.lang.String warning_msg)` | Log a warning message.
    `java.lang.String` | `logWarning​(java.lang.String warning_msg, java.lang.Throwable reason)` | Log a warning message with an exception that caused the warning.
    `AQBPLogger.QBPConfigException` | `newConfigFatal​(java.lang.String error_msg)` | Same as `logConfigFatal(String)`, but returns the exception instead of throwing it.
    `AQBPLogger.QBPConfigException` | `newConfigFatal​(java.lang.String error_msg, java.lang.Throwable reason)` | Same as `logConfigFatal(String, Throwable)`, but returns the exception instead of throwing it.
    `AQBPLogger.QBPException` | `newFatal​(java.lang.String error_msg)` | Same as `logFatal(String)`, but returns the exception instead of throwing it.
    `AQBPLogger.QBPException` | `newFatal​(java.lang.String error_msg, java.lang.Throwable reason)` | Same as `logFatal(String, Throwable)`, but returns the exception instead of throwing it.
    `boolean` | `popConfig()` | Pop a configuration item off the stack of configuration items.
    `void` | `pushConfig​(com.tibco.patterns.qbp.jaxb.ConfigItem new_config)` | Push a new current configuration item onto the config item stack.
    `protected abstract java.lang.String` | `sendConfigError​(java.lang.String raw_msg)` | Format a configuration error message and send it to the log.
    `protected abstract java.lang.String` | `sendConfigError​(java.lang.String raw_msg, java.lang.Throwable reason)` | Format a configuration error message and send it to the log with a reason.
    `protected abstract java.lang.String` | `sendError​(java.lang.String raw_msg)` | Format an error message and send it to the log.
    `protected abstract java.lang.String` | `sendError​(java.lang.String raw_msg, java.lang.Throwable reason)` | Format an error message and send it to the log with a reason.
    `protected abstract java.lang.String` | `sendInfo​(java.lang.String raw_msg)` | Format an information message and send it to the log.
    `protected abstract java.lang.String` | `sendTrace​(java.lang.String raw_msg)` | Format a Trace message and send it to the log.
    `protected abstract java.lang.String` | `sendWarning​(java.lang.String raw_msg)` | Format a warning message and send it to the log.
    `protected abstract java.lang.String` | `sendWarning​(java.lang.String raw_msg, java.lang.Throwable reason)` | Format a warning message with a reason and send it to the log.
    `void` | `setConfig​(com.tibco.patterns.qbp.jaxb.ConfigItem new_config)` | Set the top level configuration item.
    `void` | `setEnabledLevels​(AQBPLogger.LogLevel... enabled_levels)` | Set the log levels that are enabled.
    `void` | `turnOffConfigExceptionMode()` | Turn off configuration error exception mode.
    `void` | `turnOffConfigNotes()` | Turn off the adding of configuration errors to config object.
    `void` | `turnOffStandardExceptionMode()` | Turn off standard error exception mode.
    `void` | `turnOnConfigExceptionMode()` | Turn on configuration error exception mode.
    `void` | `turnOnConfigNotes()` | Turn on the adding of configuration errors to config object.
    `void` | `turnOnStandardExceptionMode()` | Turn on standard error exception mode.

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

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

- - ### Constructor Detail

    - #### AQBPLogger

          public AQBPLogger()

      Default constructor. This establishes the default settings.
      - Add Configuration notes is ON.
      - Throw configuration error exceptions is OFF.
      - Throw standard error exceptions is OFF.
      - All levels are enabled except trace level.

  - ### Method Detail

    - #### turnOnConfigNotes

          public void turnOnConfigNotes()

      Turn on the adding of configuration errors to config object. This is the default setting.

    - #### turnOffConfigNotes

          public void turnOffConfigNotes()

      Turn off the adding of configuration errors to config object.

    - #### getConfigNoteCount

          public int getConfigNoteCount()

      Returns:
        the count of configuration notes added.

    - #### turnOnConfigExceptionMode

          public void turnOnConfigExceptionMode()

      Turn on configuration error exception mode. All configuration errors will throw a QBPConfigException.

    - #### turnOffConfigExceptionMode

          public void turnOffConfigExceptionMode()

      Turn off configuration error exception mode. Configuration errors will not throw a QBPConfigException (default).

    - #### isConfigExceptionModeOn

          public boolean isConfigExceptionModeOn()

      Returns:
        true if configuration errors throw an exception.

    - #### turnOnStandardExceptionMode

          public void turnOnStandardExceptionMode()

      Turn on standard error exception mode. All standard errors will throw a QBPConfigException.

    - #### turnOffStandardExceptionMode

          public void turnOffStandardExceptionMode()

      Turn off standard error exception mode. Standard errors will not throw a QBPConfigException (default).

    - #### isStandardExceptionModeOn

          public boolean isStandardExceptionModeOn()

      Returns:
        true if standard errors throw an exception.

    - #### setEnabledLevels

          public void setEnabledLevels​(AQBPLogger.LogLevel... enabled_levels)

      Set the log levels that are enabled. This resets the enabled log levels to the levels given. This resets the entire list. Only those levels listed, plus the FATAL and CONFIG_FATAL levels, which are always enabled, are enabled after this call.
      Parameters:
        `enabled_levels` - the list of all log levels that are enabled. All other levels are ignored.

    - #### pushConfig

          public void pushConfig​(com.tibco.patterns.qbp.jaxb.ConfigItem new_config)

      Push a new current configuration item onto the config item stack. The logger keeps a stack of configuration items. Configuration errors are associated with the first non-null item on the stack. This operation pushes a new configuration onto the stack.
      Parameters:
        `new_config` - the new configuration item.

    - #### popConfig

          public boolean popConfig()

      Pop a configuration item off the stack of configuration items. The logger keeps a stack of configuration items. Configuration errors are associated with the first non-null item on the stack. This method pops the top configuration item off the stack.
      Returns:
        true if the stack, after the pop operation, is not empty, false if there are no more items on the stack.

    - #### setConfig

          public void setConfig​(com.tibco.patterns.qbp.jaxb.ConfigItem new_config)

      Set the top level configuration item. The logger keeps a stack of configuration items. Configuration errors are associated with the first non-null item on the stack. If the stack is empty this behaves just like pushConfig, if the stack is not empty it changes the top level item without either pushing or popping any item on the stack.
      Parameters:
        `new_config` - the configuration item that should become the top level item on the stack.

    - #### logFatal

          public void logFatal​(java.lang.String error_msg)
                        throws AQBPLogger.QBPException

      Log a standard fatal message. Fatal messages always throw an exception.
      Parameters:
        `error_msg` - the message to be logged.
      Throws:
        `AQBPLogger.QBPException` - always thrown.

    - #### newFatal

          public AQBPLogger.QBPException newFatal​(java.lang.String error_msg)

      Same as `logFatal(String)`, but returns the exception instead of throwing it.
      Returns:
        the new QBPConfigException with the formatted message (even if sending the error to the log failed).

    - #### logFatal

          public void logFatal​(java.lang.String error_msg,
                               java.lang.Throwable reason)
                        throws AQBPLogger.QBPException

      Log a standard fatal message with an exception that caused the error.
      Parameters:
        `error_msg` - the message to be logged.
        `reason` - an exception that triggered this error message.
      Throws:
        `AQBPLogger.QBPException` - always thrown.

    - #### newFatal

          public AQBPLogger.QBPException newFatal​(java.lang.String error_msg,
                                                  java.lang.Throwable reason)

      Same as `logFatal(String, Throwable)`, but returns the exception instead of throwing it.
      Returns:
        the new QBPConfigException with the formatted message (even if sending the error to the log failed).

    - #### logError

          public java.lang.String logError​(java.lang.String error_msg)
                                    throws AQBPLogger.QBPException

      Log a standard error message.
      Parameters:
        `error_msg` - the message to be logged.
      Returns:
        the formatted error message, null if errors are not enabled.
      Throws:
        `AQBPLogger.QBPException` - if exception mode is enabled.

    - #### logError

          public java.lang.String logError​(java.lang.String error_msg,
                                           java.lang.Throwable reason)
                                    throws AQBPLogger.QBPException

      Log a standard error message with an exception that caused the error.
      Parameters:
        `error_msg` - the message to be logged.
        `reason` - an exception that triggered this error message.
      Returns:
        the formatted error message.
      Throws:
        `AQBPLogger.QBPException` - if exception mode is enabled.

    - #### logConfigFatal

          public void logConfigFatal​(java.lang.String error_msg)
                              throws AQBPLogger.QBPConfigException

      Log a configuration fatal message. Fatal messages always throw an exception.
      Parameters:
        `error_msg` - the message to be logged.
      Throws:
        `AQBPLogger.QBPConfigException` - always thrown.

    - #### newConfigFatal

          public AQBPLogger.QBPConfigException newConfigFatal​(java.lang.String error_msg)
                                                       throws AQBPLogger.QBPConfigException

      Same as `logConfigFatal(String)`, but returns the exception instead of throwing it.
      Returns:
        the new QBPConfigException with the formatted message.
      Throws:
        `AQBPLogger.QBPConfigException` - if sending the error to the log failed.

    - #### logConfigFatal

          public void logConfigFatal​(java.lang.String error_msg,
                                     java.lang.Throwable reason)
                              throws AQBPLogger.QBPConfigException

      Log a configuration fatal message with an exception that caused the error.
      Parameters:
        `error_msg` - the message to be logged.
        `reason` - an exception that triggered this error message.
      Throws:
        `AQBPLogger.QBPConfigException` - always thrown.

    - #### newConfigFatal

          public AQBPLogger.QBPConfigException newConfigFatal​(java.lang.String error_msg,
                                                              java.lang.Throwable reason)
                                                       throws AQBPLogger.QBPConfigException

      Same as `logConfigFatal(String, Throwable)`, but returns the exception instead of throwing it.
      Returns:
        the new QBPConfigException with the formatted message.
      Throws:
        `AQBPLogger.QBPConfigException` - if sending the error to the log failed.

    - #### logConfigError

          public java.lang.String logConfigError​(java.lang.String error_msg)
                                          throws AQBPLogger.QBPConfigException

      Log a configuration error message.
      Parameters:
        `error_msg` - the message to be logged.
      Returns:
        the formatted error message.
      Throws:
        `AQBPLogger.QBPConfigException` - if exception mode is enabled.

    - #### logConfigError

          public java.lang.String logConfigError​(java.lang.String error_msg,
                                                 java.lang.Throwable reason)
                                          throws AQBPLogger.QBPConfigException

      Log a configuration error message with an exception that caused the error.
      Parameters:
        `error_msg` - the message to be logged.
        `reason` - an exception that triggered this error message.
      Returns:
        the formatted error message.
      Throws:
        `AQBPLogger.QBPConfigException` - if exception mode is enabled.

    - #### logWarning

          public java.lang.String logWarning​(java.lang.String warning_msg)

      Log a warning message.
      Parameters:
        `warning_msg` - the warning message to be logged.
      Returns:
        the formatted warning message.

    - #### logWarning

          public java.lang.String logWarning​(java.lang.String warning_msg,
                                             java.lang.Throwable reason)

      Log a warning message with an exception that caused the warning.
      Parameters:
        `warning_msg` - the message to be logged.
        `reason` - an exception that triggered this warning message.
      Returns:
        the formatted warning message.

    - #### logInfo

          public java.lang.String logInfo​(java.lang.String info_msg)

      Log a general information message.
      Parameters:
        `info_msg` - the message to be logged.
      Returns:
        the formatted info message.

    - #### logTrace

          public java.lang.String logTrace​(java.lang.String trace_msg)

      Log a trace message. Trace messages are generally used to provide a detailed trace of processing. They are equivalent to debug or details messages in other logging systems.
      Parameters:
        `trace_msg` - the message to be logged.
      Returns:
        the formatted trace message.

    - #### sendError

          protected abstract java.lang.String sendError​(java.lang.String raw_msg)

      Format an error message and send it to the log. This formats a raw error message and sends it to the error log. It returns the formatted message, as it should appear in any associated thrown exception or Configuration notation. This allows for the addition of tracking stamps used to tie together messages.
      Parameters:
        `raw_msg` - the error message.
      Returns:
        the formatted error message. If there is a failure sending the log message null should be returned, this will trigger a thrown exception.

    - #### sendError

          protected abstract java.lang.String sendError​(java.lang.String raw_msg,
                                                        java.lang.Throwable reason)

      Format an error message and send it to the log with a reason. This formats a raw error message and sends it to the error log. A throwable object that triggered the exception is included. It returns the formatted message, as it should appear in any associated thrown exception or Configuration notation. This allows for the addition of tracking stamps used to tie together messages.
      Parameters:
        `raw_msg` - the error message.
        `reason` - the thrown exception that triggered this call.
      Returns:
        the formatted error message. If there is a failure sending the log message null should be returned, this will trigger a thrown exception.

    - #### sendConfigError

          protected abstract java.lang.String sendConfigError​(java.lang.String raw_msg)

      Format a configuration error message and send it to the log. This formats a raw error message and sends it to the error log. It returns the formatted message, as it should appear in any associated thrown exception or Configuration notation. This allows for the addition of tracking stamps used to tie together messages.
      Parameters:
        `raw_msg` - the error message.
      Returns:
        the formatted error message. If there is a failure sending the log message null should be returned, this will trigger a thrown exception.

    - #### sendConfigError

          protected abstract java.lang.String sendConfigError​(java.lang.String raw_msg,
                                                              java.lang.Throwable reason)

      Format a configuration error message and send it to the log with a reason. This formats a raw error message and sends it to the error log. A throwable object that triggered the exception is included. It returns the formatted message, as it should appear in any associated thrown exception or Configuration notation. This allows for the addition of tracking stamps used to tie together messages.
      Parameters:
        `raw_msg` - the error message.
        `reason` - the thrown exception that triggered this call.
      Returns:
        the formatted error message. If there is a failure sending the log message null should be returned, this will trigger a thrown exception.

    - #### sendWarning

          protected abstract java.lang.String sendWarning​(java.lang.String raw_msg)

      Format a warning message and send it to the log. This formats a raw warning message and sends it to the warning log. It returns the formatted message, as it should appear in any associated thrown exception or Configuration notation. This allows for the addition of tracking stamps used to tie together messages. (Note: currently warnings do not trigger exceptions or notations, but may in the future.)
      Parameters:
        `raw_msg` - the error message.
      Returns:
        the formatted warning message. If there is a failure sending the log message null should be returned.

    - #### sendWarning

          protected abstract java.lang.String sendWarning​(java.lang.String raw_msg,
                                                          java.lang.Throwable reason)

      Format a warning message with a reason and send it to the log. This formats a raw warning message along with a throwable object that triggered the warning, and sends it to the warning log. It returns the formatted message, as it should appear in any associated thrown exception or Configuration notation. This allows for the addition of tracking stamps used to tie together messages. (Note: currently warnings do not trigger exceptions or notations, but may in the future.)
      Parameters:
        `raw_msg` - the error message.
        `reason` - the thrown exception that triggered this call.
      Returns:
        the formatted warning message. If there is a failure sending the log message null should be returned.

    - #### sendInfo

          protected abstract java.lang.String sendInfo​(java.lang.String raw_msg)

      Format an information message and send it to the log. This formats a raw information message and sends it to the info log. It returns the formatted message, as it should appear in any associated Configuration notation. This allows for the addition of tracking stamps used to tie together messages. (Note: currently information messages do not trigger notations, but they may in the future.)
      Parameters:
        `raw_msg` - the error message.
      Returns:
        the formatted error message. If there is a failure sending the log message null should be returned.

    - #### sendTrace

          protected abstract java.lang.String sendTrace​(java.lang.String raw_msg)

      Format a Trace message and send it to the log. This formats a raw trace message and sends it to the info log. It returns the formatted message.
      Parameters:
        `raw_msg` - the error message.
      Returns:
        the formatted error message. If there is a failure sending the log message null should be returned.