Package org.apache.log4j.db

## Class CustomSQLDBReceiver

- java.lang.Object
- - org.apache.log4j.spi.ComponentBase
  - - org.apache.log4j.plugins.PluginSkeleton
    - - org.apache.log4j.plugins.Receiver
      - - org.apache.log4j.db.CustomSQLDBReceiver

- All Implemented Interfaces:
    `Pauseable`, `Plugin`, `Component`, `org.apache.log4j.spi.OptionHandler`, `Thresholdable`, `org.apache.log4j.xml.UnrecognizedElementHandler`

      public class CustomSQLDBReceiver
      extends Receiver
      implements Pauseable, org.apache.log4j.xml.UnrecognizedElementHandler

  Converts log data stored in a database into LoggingEvents.

  NOTE: This receiver cannot yet be created through Chainsaw's receiver panel. It must be created through an XML configuration file.

  This receiver supports database configuration via ConnectionSource, in the org.apache.log4j.db package: DriverManagerConnectionSource, DataSourceConnectionSource, JNDIConnectionSource

  This database receiver differs from DBReceiver in that this receiver relies on custom SQL to retrieve logging event data, where DBReceiver requires the use of a log4j-defined schema.

  A 'refreshMillis' int parameter controls SQL execution. If 'refreshMillis' is zero (the default), the receiver will run only one time. If it is set to any other numeric value, the SQL will be executed on a recurring basis every 'refreshMillis' milliseconds.

  The receiver closes the connection and acquires a new connection on each execution of the SQL (use pooled connections if possible).

  If the SQL will be executing on a recurring basis, specify the IDField param - the column name holding the unique identifier (int) representing the logging event.

  As events are retrieved, the column represented by IDField is examined and the largest value is held and used by the next execution of the SQL statement to avoid retrieving previously processed events.

  As an example, the IDField references a 'COUNTER' (int, auto-increment, unique) column. The first execution of the SQL statement returns 500 rows, with a final value in the COUNTER field of 500.

  The SQL statement is manipulated prior to the next execution, adding ' WHERE COUNTER > 500' to the statement to avoid retrieval of previously processed events.

  The select statement must provide ALL fields which define a LoggingEvent.

  The SQL statement MUST include the columns: LOGGER, TIMESTAMP, LEVEL, THREAD, MESSAGE, NDC, MDC, CLASS, METHOD, FILE, LINE, PROPERTIES, THROWABLE

  Use ' AS ' in the SQL statement to alias the SQL's column names to match your database schema. (see example below).

  Include all fields in the SQL statement, even if you don't have data for the field (specify an empty string as the value for columns which you don't have data).

  The TIMESTAMP column must be a datetime.

  Both a PROPERTIES column and an MDC column are supported. These fields represent Maps on the logging event, but require the use of string concatenation database functions to hold the (possibly multiple) name/value pairs in the column.

  For example, to include both 'userid' and 'lastname' properties in the logging event (from either the PROPERTIES or MDC columns), the name/value pairs must be concatenated together by your database.

  The resulting PROPERTIES or MDC column must have data in this format: {{name, value, name2, value2}}

  The resulting PROPERTIES column would contain this text: {{userid, someone, lastname, mylastname}}

  Here is an example of concatenating a PROPERTIES or MDC column using MySQL's concat function, where the 'application' and 'hostname' parameters were fixed text, but the 'log4jid' key's value is the value of the COUNTER column:

  concat("{{application,databaselogs,hostname,mymachine,log4jid,", COUNTER, "}}") as PROPERTIES

  log4jid is a special property that is used by Chainsaw to represent an 'ID' field. Specify this property to ensure you can map events in Chainsaw to events in the database if you need to go back and view events at a later time or save the events to XML for later analysis.

  Here is a complete MySQL SQL statement which can be used to provide events to Chainsaw (note how in the example below, there is no column in logtable representing the throwable, so an empty string is passed in and an ALIAS is still defined):

  select myloggercolumn as LOGGER, mytimestampcolumn as TIMESTAMP, mylevelcolumn as LEVEL, mythreadcolumn as THREAD, mymessagecolumn as MESSAGE, myndccolumn as NDC, mymdccolumn as MDC, myclasscolumn as CLASS, mymethodcolumn as METHOD, myfilecolumn as FILE, mylinecolumn as LINE, concat("{{application,databaselogs,hostname,mymachine, log4jid,", COUNTER,"}}") as PROPERTIES, "" as THROWABLE from logtable

  Author:
    Scott Deboy <sdeboy@apache.org>

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Connection` | `connection` |
    `protected String` | `idField` |
    `static String` | `LOG4J_ID_KEY` |
    `protected String` | `sqlStatement` |

    - ### Fields inherited from class org.apache.log4j.plugins.Receiver

      `thresholdLevel`

    - ### Fields inherited from class org.apache.log4j.plugins.PluginSkeleton

      `active, name`

    - ### Fields inherited from class org.apache.log4j.spi.ComponentBase

      `repository`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CustomSQLDBReceiver()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `activateOptions()` |
    `void` | `close()` |
    `void` | `finalize()` |
    `ConnectionSource` | `getConnectionSource()` |
    `String` | `getIDField()` |
    `int` | `getRefreshMillis()` |
    `String` | `getSql()` |
    `boolean` | `isPaused()` | Get paused state.
    `boolean` | `parseUnrecognizedElement​(Element element, Properties props)`
    `void` | `setConnectionSource​(ConnectionSource connectionSource)` |
    `void` | `setIDField​(String id)` |
    `void` | `setPaused​(boolean p)` | Set paused state.
    `void` | `setRefreshMillis​(int refreshMillis)` |
    `void` | `setSql​(String s)` |
    `void` | `shutdown()` | Call when the plugin should be stopped.

    - ### Methods inherited from class org.apache.log4j.plugins.Receiver

      `doPost, getThreshold, isAsSevereAsThreshold, setThreshold`

    - ### Methods inherited from class org.apache.log4j.plugins.PluginSkeleton

      `addPropertyChangeListener, addPropertyChangeListener, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getLoggerRepository, getName, isActive, isEquivalent, removePropertyChangeListener, removePropertyChangeListener, setLoggerRepository, setName`

    - ### Methods inherited from class org.apache.log4j.spi.ComponentBase

      `getLogger, getNonFloodingLogger, resetErrorCount`

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

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

- - ### Field Detail

    - #### connection

          protected volatile Connection connection

    - #### sqlStatement

          protected String sqlStatement

    - #### idField

          protected String idField

    - #### LOG4J_ID_KEY

          public static final String LOG4J_ID_KEY

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### CustomSQLDBReceiver

          public CustomSQLDBReceiver()

  - ### Method Detail

    - #### activateOptions

          public void activateOptions()

      Specified by:
        `activateOptions` in interface `org.apache.log4j.spi.OptionHandler`

    - #### setRefreshMillis

          public void setRefreshMillis​(int refreshMillis)

    - #### getRefreshMillis

          public int getRefreshMillis()

    - #### getConnectionSource

          public ConnectionSource getConnectionSource()

      Returns:
        Returns the connectionSource.

    - #### setConnectionSource

          public void setConnectionSource​(ConnectionSource connectionSource)

      Parameters:
        `connectionSource` - The connectionSource to set.

    - #### close

          public void close()

    - #### finalize

          public void finalize()
                        throws Throwable

      Overrides:
        `finalize` in class `Object`
      Throws:
        `Throwable`

    - #### shutdown

          public void shutdown()

      Description copied from interface: `Plugin`
      Call when the plugin should be stopped.
      Specified by:
        `shutdown` in interface `Plugin`

    - #### setSql

          public void setSql​(String s)

    - #### getSql

          public String getSql()

    - #### setIDField

          public void setIDField​(String id)

    - #### getIDField

          public String getIDField()

    - #### setPaused

          public void setPaused​(boolean p)

      Description copied from interface: `Pauseable`
      Set paused state.
      Specified by:
        `setPaused` in interface `Pauseable`
      Parameters:
        `p` - new value

    - #### isPaused

          public boolean isPaused()

      Description copied from interface: `Pauseable`
      Get paused state.
      Specified by:
        `isPaused` in interface `Pauseable`
      Returns:
        paused state.

    - #### parseUnrecognizedElement

          public boolean parseUnrecognizedElement​(Element element,
                                                  Properties props)
                                           throws Exception

      Specified by:
        `parseUnrecognizedElement` in interface `org.apache.log4j.xml.UnrecognizedElementHandler`
      Throws:
        `Exception`