org.apache.log4j.jdbcplus
Class JDBCAppender

java.lang.Object
  |
  +--org.apache.log4j.AppenderSkeleton
        |
        +--org.apache.log4j.jdbcplus.JDBCAppender
All Implemented Interfaces:
Appender, OptionHandler

public class JDBCAppender
extends AppenderSkeleton

The JDBCAppender writes messages into a database via JDBC. Multiple configuration options and parameters are supported.

Configuration by file/code

The JDBCAppender is configurable at runtime by setting options in two alternatives :

  1. Use a configuration-file
  2. Call the methods of JDBCAppender directly to do it

    Here is a another code-example ( SourceConfigOracleTest.java ) to configure the JDBCAppender without a configuration-file.

Configuration parameters

Generally there are just a few basic things to get the JDBCAppender running :

  1. We need a database connection anyway ! There are 3 ways to to this :

    a) Specify the URL, password and username (use the url-param, username-param and password-param or the setUrl(), setUsername() and setPassword()-methods) This will create a static connection by JDBCAppender.

    b) Specify a JDBCConnectionHandler (use the connector-param or the setConnector()-method) This handler will be called to return a connection. When its a JDBCPoolConnectionHandler, the connection is checked in and out everytime needing it.

    c) Specify URL, password and username AND a JDBCConnectionHandler, then the handler returns the desired connection.

  2. We need to know the statement which should be inserted into the database ! There are also 5 ways to to this :

    a) Specify a JDBCSqlHandler (use the sqlhandler-param or the setSqlhandler()-method) This handler will be invoked with every message which has to be logged and must return a SQL-statement. It may return null or empty string if nothing should be logged.

    b) Specify a static sql-statement (use the sql-param or the setSql()-method) This statement which will be performed with every occuring message-event. Use wildcards @INC@, @PRIO@, @IPRIO@, @CAT@, @THREAD@, @MSG@, @LAYOUT@, @LAYOUT:x@, @TIMESTAMP@, @THROWABLE@, @NDC@, @MDC:key@ for dynamic replacement. See further description below.

    c) Specify the table and describe the important columns. (use the table-param and column-param or the setTable() and setColumn()-methods) Not nullable columns are mandatory to describe ! The sql-statement will be created automatically. We need to know exactly the column-name, the logical columns-logtype and in dependency of that the value. The constants of JDBCLogType are described below. This is the most dynamic variant to build the sql-statement, because you can apply JDBCIDHandler and JDBCColumnHandler. Note: This configuration uses the "updatable ResultSets". This feature is not implemented for some databases/drivers. As of 2004, it causes errors on MySQL JDBC Connector ("Result Set not updateable"), Firebird JCA-JDBC Driver ("not yet implemented"), Postgres. Use other configuration options instead if any problems occur.

    d) Same as 2c) but using PreparedStatements. Example: log4j_test_prepstmt.xml

    e) Same as 2c) but using Stored Procedure (CallableStatement). Specify procedure name parameter instead of table name. Requires J2SDK 1.4+. Example: log4j_test_storedproc.xml

The class JDBCLogType provides you several possibilities to describe a columns logtype/wildcard :

Since:
1.0
Version:
see jdbcappender.jar/META-INF/MANIFEST.MF for version information
Author:
Thomas Fenner, Danko Mannhaupt, many contributions by the community

Field Summary
 
Fields inherited from class org.apache.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold
 
Constructor Summary
JDBCAppender()
          Constructor for the JDBCAppender object
JDBCAppender(Layout layout)
          Constructor for the JDBCAppender object
 
Method Summary
 void append(LoggingEvent event)
          Internal method.
 void close()
          Internal method.
protected  boolean configure()
          Internal method.
protected  void connect()
          Internal method.
 void finalize()
          If program terminates close the database-connection and flush the buffer
 void flush_buffer()
          Internal method.
 String getBuffer()
          Gets the Buffer attribute of the JDBCAppender object
 boolean getCommit()
          Gets the Commit attribute of the JDBCAppender object
 JDBCConnectionHandler getConnectionHandler()
          Gets the ConnectionHandler attribute of the JDBCAppender object
 String getConnector()
          Gets the Connector attribute of the JDBCAppender object
 String getDbclass()
          Gets the class loader string
 String getLayoutPartsDelimiter()
          character to separate parts of layout if more than one part is to be used
 String getPassword()
          Gets the Password attribute of the JDBCAppender object
 String getProcedure()
          Returns the procedure.
 String getSql()
          Gets the Sql attribute of the JDBCAppender object
 String getTable()
          Gets the Table attribute of the JDBCAppender object
 int getThrowableMaxChars()
          Returns the maximum number of characters in throwable/exception stack trace.
 String getUrl()
          Gets the Url attribute of the JDBCAppender object
 String getUsername()
          Gets the Username attribute of the JDBCAppender object
 boolean isQuoteReplace()
          Define whether to replace single quotes (') by 2 single quotes ('') in sql parameters.
 boolean isUsePreparedStatements()
           
 boolean ready()
          Internal method.
 boolean requiresLayout()
          Internal method.
 void setBuffer(String value)
          Defines how many messages will be buffered until they will be updated to the database.
 void setColumn(String value)
          Defines one colum in the format column~logtype~value~typeName~sqlType, e.g.
 void setColumn(String column, int logtype, Object value, String type, int sqlType)
          Sets the Column attribute of the JDBCAppender object.
 void setCommit(boolean value)
          Defines whether updated messages should be committed to the database.
 void setConnectionHandler(JDBCConnectionHandler connectionHandler)
          Specify your own JDBCConnectionHandler / JDBCPoolConnectionHandler for connecting to the database.
 void setConnector(String value)
          Specify your own JDBCConnectionHandler / JDBCPoolConnectionHandler for connecting to the database.
 void setDbclass(String value)
          Specify a database class loader string.
 void setLayout(Layout layout)
          Sets the Layout attribute of the JDBCAppender object
 void setLayoutPartsDelimiter(String c)
          character to separate parts of layout if more than one part is to be used
 void setPassword(String value)
          Sets the database password
 void setProcedure(String procedure)
          Stores the procedure which will be called.
 void setQuoteReplace(boolean b)
          Define whether to replace single quotes (') by 2 single quotes ('') in sql parameters.
 void setSql(String value)
          Specify an sql-statement.
 void setSqlHandler(JDBCSqlHandler sqlHandler)
          Specify your own JDBCSqlHandler to let him create dynamic sql-statements.
 void setSqlhandler(String value)
          Specify your own JDBCSqlHandler to let him create dynamic sql-statements.
 void setTable(String value)
          Specify the table, when you also describe all columns by setColumn()
 void setThrowableMaxChars(int throwableMaxChars)
          Sets the maximum number of characters in throwable/exception stack trace.
 void setUrl(String value)
          Sets database url of the form jdbc:subprotocol:subname
 void setUsePreparedStatements(boolean usePreparedStatements)
          Defines whether to use Prepared Statements instead of updateable result sets (default false).
 void setUsername(String value)
          Sets the database user
 
Methods inherited from class org.apache.log4j.AppenderSkeleton
activateOptions, addFilter, clearFilters, doAppend, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setErrorHandler, setName, setThreshold
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JDBCAppender

public JDBCAppender()
Constructor for the JDBCAppender object


JDBCAppender

public JDBCAppender(Layout layout)
Constructor for the JDBCAppender object

Parameters:
layout - Allows you to set your Layout-instance
Method Detail

setLayout

public void setLayout(Layout layout)
Sets the Layout attribute of the JDBCAppender object

Specified by:
setLayout in interface Appender
Overrides:
setLayout in class AppenderSkeleton
Parameters:
layout - The new Layout value

setConnector

public void setConnector(String value)
Specify your own JDBCConnectionHandler / JDBCPoolConnectionHandler for connecting to the database. If the Database-Options are given, the handler is called with the desired database-params. If you give a JDBCPoolConnectionHandler, the connection will be checked out only when needed and checked in after .

Parameters:
value - The new Connector value

setConnectionHandler

public void setConnectionHandler(JDBCConnectionHandler connectionHandler)
Specify your own JDBCConnectionHandler / JDBCPoolConnectionHandler for connecting to the database. If the Database-Options are given, the handler is called with the desired database-params. If you give a JDBCPoolConnectionHandler, the connection will be checked out only when needed and checked in after .


setSqlhandler

public void setSqlhandler(String value)
Specify your own JDBCSqlHandler to let him create dynamic sql-statements.

Parameters:
value - The new Sqlhandler value

setSqlHandler

public void setSqlHandler(JDBCSqlHandler sqlHandler)
                   throws Exception
Specify your own JDBCSqlHandler to let him create dynamic sql-statements.

Exception

setUrl

public void setUrl(String value)
Sets database url of the form jdbc:subprotocol:subname

Parameters:
value - The new Url value

setUsername

public void setUsername(String value)
Sets the database user

Parameters:
value - The new Username value

setPassword

public void setPassword(String value)
Sets the database password

Parameters:
value - The new Password value

setDbclass

public void setDbclass(String value)
Specify a database class loader string. E.g. oracle.jdbc.driver.OracleDriver

Parameters:
value - The new database driver class

setSql

public void setSql(String value)
Specify an sql-statement. Use wildcards @INC@, @PRIO@, @CAT@, @THREAD@, @MSG@, ... for dynamic replacement. See class JDBCLogType for further description.

Parameters:
value - The new Sql value

setTable

public void setTable(String value)
Specify the table, when you also describe all columns by setColumn()

Parameters:
value - The new Table value

setColumn

public void setColumn(String column,
                      int logtype,
                      Object value,
                      String type,
                      int sqlType)
Sets the Column attribute of the JDBCAppender object. Last two parameters only required for Stored Procedure configuration on Oracle.

Parameters:
column - The columns name
logtype - Constant of class JDBCLogType
value - The columns value depending by the logtype
type - Column type name
sqlType - Column SQL type

setColumn

public void setColumn(String value)
Defines one colum in the format column~logtype~value~typeName~sqlType, e.g. id~ID~org.apache.log4j.jdbcplus.examples.MyIDHandler or id~ID~org.apache.log4j.jdbcplus.examples.MyIDHandler~INTEGER~4. typeName and sqlType are required, if JDBC driver does not support Statement.getParamaterMetaData, e.g. Oracle.

Parameters:
value - Concatenated string column~logtype~value~typeName

setBuffer

public void setBuffer(String value)
Defines how many messages will be buffered until they will be updated to the database.

Parameters:
value - The new Buffer value

setCommit

public void setCommit(boolean value)
Defines whether updated messages should be committed to the database.

Parameters:
value - The new Commit value

getConnectionHandler

public JDBCConnectionHandler getConnectionHandler()
Gets the ConnectionHandler attribute of the JDBCAppender object

Returns:
The ConnectionHandler value

getConnector

public String getConnector()
Gets the Connector attribute of the JDBCAppender object

Returns:
The Connector value

getUrl

public String getUrl()
Gets the Url attribute of the JDBCAppender object

Returns:
The Url value

getUsername

public String getUsername()
Gets the Username attribute of the JDBCAppender object

Returns:
The Username value

getPassword

public String getPassword()
Gets the Password attribute of the JDBCAppender object

Returns:
The Password value

getSql

public String getSql()
Gets the Sql attribute of the JDBCAppender object

Returns:
The Sql value

getDbclass

public String getDbclass()
Gets the class loader string

Returns:
The db class loader string

getTable

public String getTable()
Gets the Table attribute of the JDBCAppender object

Returns:
The Table value

getBuffer

public String getBuffer()
Gets the Buffer attribute of the JDBCAppender object

Returns:
The Buffer value

getCommit

public boolean getCommit()
Gets the Commit attribute of the JDBCAppender object

Returns:
The Commit value

finalize

public void finalize()
If program terminates close the database-connection and flush the buffer

Overrides:
finalize in class AppenderSkeleton

requiresLayout

public boolean requiresLayout()
Internal method. Returns true, you may define your own layout...

Returns:
Description of the Returned Value

close

public void close()
Internal method. Close the database connection & flush the buffer.


append

public void append(LoggingEvent event)
Internal method. Appends the message to the database table.

Specified by:
append in class AppenderSkeleton
Parameters:
event - Description of Parameter

flush_buffer

public void flush_buffer()
Internal method. Flushes the buffer.


ready

public boolean ready()
Internal method. Returns true, when the JDBCAppender is ready to append messages to the database, else false.

Returns:
Description of the Returned Value

connect

protected void connect()
                throws Exception
Internal method. Connect to the database.

Throws:
Exception - Description of Exception

configure

protected boolean configure()
Internal method. Configures for appending...

Returns:
Description of the Returned Value

isQuoteReplace

public boolean isQuoteReplace()
Define whether to replace single quotes (') by 2 single quotes ('') in sql parameters.

Returns:
quoteReplace

setQuoteReplace

public void setQuoteReplace(boolean b)
Define whether to replace single quotes (') by 2 single quotes ('') in sql parameters.

Parameters:
b -

getLayoutPartsDelimiter

public String getLayoutPartsDelimiter()
character to separate parts of layout if more than one part is to be used

Returns:
layoutPartsDelimiter

setLayoutPartsDelimiter

public void setLayoutPartsDelimiter(String c)
character to separate parts of layout if more than one part is to be used

Parameters:
c -

isUsePreparedStatements

public boolean isUsePreparedStatements()
Returns:
Returns the usePreparedStatements.

setUsePreparedStatements

public void setUsePreparedStatements(boolean usePreparedStatements)
Defines whether to use Prepared Statements instead of updateable result sets (default false).

Parameters:
usePreparedStatements - The usePreparedStatements to set.

getProcedure

public String getProcedure()
Returns the procedure.

Returns:
Returns the procedure.

setProcedure

public void setProcedure(String procedure)
Stores the procedure which will be called.

Parameters:
procedure - The procedure to set.

getThrowableMaxChars

public int getThrowableMaxChars()
Returns the maximum number of characters in throwable/exception stack trace. Used to limit very long stack traces.

Returns:
Returns the throwableMaxChars.

setThrowableMaxChars

public void setThrowableMaxChars(int throwableMaxChars)
Sets the maximum number of characters in throwable/exception stack trace. Used to limit very long stack traces.

Parameters:
throwableMaxChars - The throwableMaxChars to set.


Copyright 2000-2004 Apache Software Foundation.