Home » apache-log4j-1.2.16 » com.klopotek.utils » log » [javadoc | source]
com.klopotek.utils.log
public class: JDBCAppender [javadoc | source]
java.lang.Object
   org.apache.log4j.AppenderSkeleton
      com.klopotek.utils.log.JDBCAppender

All Implemented Interfaces:
    OptionHandler, Appender

The JDBCAppender, writes messages into a database

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

1. Use a configuration-file

Define the options in a file (example) and call a PropertyConfigurator.configure(filename) in your code.

2. Use the methods of JDBCAppender to do it

Call JDBCAppender::setOption(JDBCAppender.xxx_OPTION, String value) to do it analogically without a configuration-file (example)

All available options are defined as static String-constants in JDBCAppender named xxx_OPTION.

Here is a description of all available options :

1. Database-options to connect to the database

- URL_OPTION : a database url of the form jdbc:subprotocol:subname

- USERNAME_OPTION : the database user on whose behalf the connection is being made

- PASSWORD_OPTION : the user's password

2. Connector-option to specify your own JDBCConnectionHandler

- CONNECTOR_OPTION : a classname which is implementing the JDBCConnectionHandler-interface

This interface is used to get a customized connection.

If in addition the database-options are given, these options will be used as arguments for the JDBCConnectionHandler-interface to get a connection.

Else if no database-options are given, the JDBCConnectionHandler-interface is called without them.

Else if this option is not defined, the database-options are required to open a connection by the JDBCAppender.

3. SQL-option to specify a static sql-statement which will be performed with every occuring message-event

- SQL_OPTION : a sql-statement which will be used to write to the database

Use the variable @MSG@ on a location in the statement, which has to be dynamically replaced by the message-text.

If you give this option, the table-option and columns-option will be ignored !

4. Table-option to specify a table contained by the database

- TABLE_OPTION : the table in which the logging will be done

5. Columns-option to describe the important columns of the table (Not nullable columns are mandatory to describe!)

- COLUMNS_OPTION : a formatted list of column-descriptions

Each column description consists of

- the name of the column (required)

- a logtype which is a static constant of class LogType (required)

- and a value which depends by the LogType (optional/required, depending by logtype)

Here is a description of the available logtypes of class LogType and how to handle the value:

o MSG = a value will be ignored, the column will get the message. (One columns need to be of this type!)

o STATIC = the value will be filled into the column with every logged message. (Ensure that the type of value can be casted into the sql-type of the column!)

o ID = value must be a classname, which implements the JDBCIDHandler-interface.

o TIMESTAMP = a value will be ignored, the column will be filled with a actually timestamp with every logged message.

o EMPTY = a value will be ignored, the column will be ignored when writing to the database (Ensure to fill not nullable columns by a database trigger!)

If there are more than one column to describe, the columns must be separated by a Tabulator-delimiter (unicode0008) !

The arguments of a column-description must be separated by the delimiter '~' !

(Example : name1~logtype1~value1 name2~logtype2~value2...)

6. Layout-options to define the layout of the messages (optional)

- _ : the layout wont be set by a xxx_OPTION

See the configuration-file and code examples below...

The default is a layout of the class org.apache.log4j.PatternLayout with the pattern=%m which representate only the message.

7. Buffer-option to define the size of the message-event-buffer (optional)

- BUFFER_OPTION : define how many messages will be buffered until they will be updated to the database.

The default is buffer=1, which will do a update with every happened message-event.

8. Commit-option to define a auto-commitment

- COMMIT_OPTION : define whether updated messages should be committed to the database (Y) or not (N).

The default is commit=Y.

The sequence of some options is important :

1. Connector-option OR/AND Database-options

Any database connection is required !

2. (Table-option AND Columns-option) OR SQL-option

Anything of that is required ! Whether where to write something OR what to write somewhere...;-)

3. All other options can be set at any time...

The other options are optional and have a default initialization, which can be customized.

Here is a configuration-file example, which can be used as argument for the PropertyConfigurator : configfile_example.txt

Here is a code-example to configure the JDBCAppender with a configuration-file : code_example1.java

Here is a another code-example to configure the JDBCAppender without a configuration-file : code_example2.java

Author : Thomas Fenner

Field Summary
public static final  String URL_OPTION    A database-option to to set a database url of the form jdbc:subprotocol:subname. 
public static final  String USERNAME_OPTION    A database-option to set the database user on whose behalf the connection is being made. 
public static final  String PASSWORD_OPTION    A database-option to set the user's password. 
public static final  String TABLE_OPTION    A table-option to specify a table contained by the database 
public static final  String CONNECTOR_OPTION    A connector-option to specify your own JDBCConnectionHandler 
public static final  String COLUMNS_OPTION    A columns-option to describe the important columns of the table 
public static final  String SQL_OPTION    A sql-option to specify a static sql-statement which will be performed with every occuring message-event 
public static final  String BUFFER_OPTION    A buffer-option to define the size of the message-event-buffer 
public static final  String COMMIT_OPTION    A commit-option to define a auto-commitment 
Fields inherited from org.apache.log4j.AppenderSkeleton:
layout,  name,  threshold,  errorHandler,  headFilter,  tailFilter,  closed
Method from com.klopotek.utils.log.JDBCAppender Summary:
append,   close,   configure,   connect,   finalize,   flush_buffer,   getOptionStrings,   ready,   requiresLayout,   setLogType,   setOption
Methods from org.apache.log4j.AppenderSkeleton:
activateOptions,   addFilter,   append,   clearFilters,   doAppend,   finalize,   getErrorHandler,   getFilter,   getFirstFilter,   getLayout,   getName,   getThreshold,   isAsSevereAsThreshold,   setErrorHandler,   setLayout,   setName,   setThreshold
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from com.klopotek.utils.log.JDBCAppender Detail:
 public  void append(LoggingEvent event) 
    Internal method. Appends the message to the database table.
 public  void close() 
    Internal method. Close the database connection & flush the buffer.
 protected boolean configure() 
    Internal method. Configures for appending...
 protected  void connect() throws Exception 
    Internal method. Connect to the database.
 public  void finalize() 
    If program terminates close the database-connection and flush the buffer
 public  void flush_buffer() 
    Internal method. Flushes the buffer.
 public String[] getOptionStrings() 
    Internal method. Returns a array of strings containing the available options which can be set with method setOption()
 public boolean ready() 
    Internal method. Returns true, when the JDBCAppender is ready to append messages to the database, else false.
 public boolean requiresLayout() 
    Internal method. Returns true, you may define your own layout...
 public boolean setLogType(String _name,
    int _logtype,
    Object _value) 
    You have to call this function for all provided columns of your log-table !
 public  void setOption(String _option,
    String _value) 
    Sets all necessary options