org.apache.catalina.valves

Class JDBCAccessLogValve

Implemented Interfaces:
Contained, Lifecycle, MBeanRegistration, Valve

public final class JDBCAccessLogValve
extends ValveBase
implements Lifecycle

This Tomcat extension logs server access directly to a database, and can be used instead of the regular file-based access log implemented in AccessLogValve. To use, copy into the server/classes directory of the Tomcat installation and configure in server.xml as:
 		<Valve className="AccessLogDBValve"
        	driverName="your_jdbc_driver"
        	connectionURL="your_jdbc_url"
        	pattern="combined" resolveHosts="false"
 		/>
 

Many parameters can be configured, such as the database connection (with driverName and connectionURL), the table name (tableName) and the field names (corresponding to the get/set method names). The same options as AccessLogValve are supported, such as resolveHosts and pattern ("common" or "combined" only).

When Tomcat is started, a database connection (with autoReconnect option) is created and used for all the log activity. When Tomcat is shutdown, the database connection is closed. This logger can be used at the level of the Engine context (being shared by all the defined hosts) or the Host context (one instance of the logger per host, possibly using different databases).

The database table can be created with the following command:

 CREATE TABLE access (
 id INT UNSIGNED AUTO_INCREMENT NOT NULL,
 ts TIMESTAMP NOT NULL,
 remoteHost CHAR(15) NOT NULL,
 user CHAR(15),
 timestamp TIMESTAMP NOT NULL,
 virtualHost VARCHAR(64) NOT NULL,
 method VARCHAR(8) NOT NULL,
 query VARCHAR(255) NOT NULL,
 status SMALLINT UNSIGNED NOT NULL,
 bytes INT UNSIGNED NOT NULL,
 referer VARCHAR(128),
 userAgent VARCHAR(128),
 PRIMARY KEY (id),
 INDEX (ts),
 INDEX (remoteHost),
 INDEX (virtualHost),
 INDEX (query),
 INDEX (userAgent)
 );
 

If the table is created as above, its name and the field names don't need to be defined.

If the request method is "common", only these fields are used: remoteHost, user, timeStamp, query, status, bytes

TO DO: provide option for excluding logging of certain MIME types.

Authors:
Andre de Jesus
Peter Rossbach

Field Summary

protected String
connectionName
The connection username to use when trying to connect to the database.
protected String
connectionPassword
The connection URL to use when trying to connect to the database.
protected Driver
driver
Instance of the JDBC Driver class we use as a connection factory.
protected static String
info
The descriptive information about this implementation.
protected LifecycleSupport
lifecycle
The lifecycle event support for this component.

Fields inherited from class org.apache.catalina.valves.ValveBase

container, controller, debug, domain, info, mserver, oname, sm

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

JDBCAccessLogValve()
Class constructor.

Method Summary

void
addLifecycleListener(LifecycleListener listener)
Adds a Lifecycle listener.
protected void
close()
Close the specified database connection.
LifecycleListener[]
findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle.
String
getConnectionName()
Return the username to use to connect to the database.
String
getConnectionPassword()
Return the password to use to connect to the database.
long
getCurrentTimeMillis()
void
invoke(Request request, Response response, ValveContext context)
This method is invoked by Tomcat on each query.
protected void
log(String message)
Log a message on the Logger associated with our Container (if any)
protected void
log(String message, Throwable throwable)
Log a message on the Logger associated with our Container (if any)
protected void
open()
Open (if necessary) and return a database connection for use by this AccessLogValve.
void
removeLifecycleListener(LifecycleListener listener)
Removes a Lifecycle listener.
void
setBytesField(String bytesField)
Sets the name of the field containing the number of bytes returned.
void
setConnectionName(String connectionName)
Set the username to use to connect to the database.
void
setConnectionPassword(String connectionPassword)
Set the password to use to connect to the database.
void
setConnectionURL(String connectionURL)
Sets the JDBC URL for the database where the log is stored.
void
setDriverName(String driverName)
Sets the database driver name.
void
setMethodField(String methodField)
Sets the name of the field containing the HTTP request method.
void
setPattern(String pattern)
Sets the logging pattern.
void
setQueryField(String queryField)
Sets the name of the field containing the URL part of the HTTP query.
void
setRefererField(String refererField)
Sets the name of the field containing the referer.
void
setRemoteHostField(String remoteHostField)
Sets the name of the field containing the remote host.
void
setResolveHosts(String resolveHosts)
Determines whether IP host name resolution is done.
void
setStatusField(String statusField)
Sets the name of the field containing the HTTP response status code.
void
setTableName(String tableName)
Sets the name of the table where the logs are stored.
void
setTimestampField(String timestampField)
Sets the name of the field containing the server-determined timestamp.
void
setUserAgentField(String userAgentField)
Sets the name of the field containing the user agent.
void
setUserField(String userField)
Sets the name of the field containing the remote user name.
void
setVirtualHostField(String virtualHostField)
Sets the name of the field containing the virtual host information (this is in fact the server name).
void
start()
Invoked by Tomcat on startup.
void
stop()
Invoked by tomcat on shutdown.

Methods inherited from class org.apache.catalina.valves.ValveBase

createObjectName, getContainer, getContainerName, getController, getDebug, getDomain, getInfo, getObjectName, getParentName, invoke, postDeregister, postRegister, preDeregister, preRegister, setContainer, setController, setDebug, setObjectName

Field Details

connectionName

protected String connectionName
The connection username to use when trying to connect to the database.


connectionPassword

protected String connectionPassword
The connection URL to use when trying to connect to the database.


driver

protected Driver driver
Instance of the JDBC Driver class we use as a connection factory.


info

protected static String info
The descriptive information about this implementation.


lifecycle

protected LifecycleSupport lifecycle
The lifecycle event support for this component.

Constructor Details

JDBCAccessLogValve

public JDBCAccessLogValve()
Class constructor. Initializes the fields with the default values. The defaults are:
 		driverName = null;
 		connectionURL = null;
 		tableName = "access";
 		remoteHostField = "remoteHost";
 		userField = "user";
 		timestampField = "timestamp";
 		virtualHostField = "virtualHost";
 		methodField = "method";
 		queryField = "query";
 		statusField = "status";
 		bytesField = "bytes";
 		refererField = "referer";
 		userAgentField = "userAgent";
 		pattern = "common";
 		resolveHosts = false;
 

Method Details

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)
Adds a Lifecycle listener.
Specified by:
addLifecycleListener in interface Lifecycle

Parameters:
listener - The listener to add.


close

protected void close()
Close the specified database connection.


findLifecycleListeners

public LifecycleListener[] findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.
Specified by:
findLifecycleListeners in interface Lifecycle


getConnectionName

public String getConnectionName()
Return the username to use to connect to the database.


getConnectionPassword

public String getConnectionPassword()
Return the password to use to connect to the database.


getCurrentTimeMillis

public long getCurrentTimeMillis()


invoke

public void invoke(Request request,
                   Response response,
                   ValveContext context)
            throws IOException,
                   ServletException
This method is invoked by Tomcat on each query.
Specified by:
invoke in interface Valve
Overrides:
invoke in interface ValveBase

Parameters:
request - The Request object.
response - The Response object.
context - The ValveContext object.


log

protected void log(String message)
Log a message on the Logger associated with our Container (if any)

Parameters:
message - Message to be logged


log

protected void log(String message,
                   Throwable throwable)
Log a message on the Logger associated with our Container (if any)

Parameters:
message - Message to be logged
throwable - Associated exception


open

protected void open()
            throws SQLException
Open (if necessary) and return a database connection for use by this AccessLogValve.


removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)
Removes a Lifecycle listener.
Specified by:
removeLifecycleListener in interface Lifecycle

Parameters:
listener - The listener to remove.


setBytesField

public void setBytesField(String bytesField)
Sets the name of the field containing the number of bytes returned.

Parameters:
bytesField - The name of the returned bytes field.


setConnectionName

public void setConnectionName(String connectionName)
Set the username to use to connect to the database.

Parameters:
connectionName - Username


setConnectionPassword

public void setConnectionPassword(String connectionPassword)
Set the password to use to connect to the database.

Parameters:
connectionPassword - User password


setConnectionURL

public void setConnectionURL(String connectionURL)
Sets the JDBC URL for the database where the log is stored.

Parameters:
connectionURL - The JDBC URL of the database.


setDriverName

public void setDriverName(String driverName)
Sets the database driver name.

Parameters:
driverName - The complete name of the database driver class.


setMethodField

public void setMethodField(String methodField)
Sets the name of the field containing the HTTP request method.

Parameters:
methodField - The name of the HTTP request method field.


setPattern

public void setPattern(String pattern)
Sets the logging pattern. The patterns supported correspond to the file-based "common" and "combined". These are translated into the use of tables containing either set of fields.

TO DO: more flexible field choices.

Parameters:
pattern - The name of the logging pattern.


setQueryField

public void setQueryField(String queryField)
Sets the name of the field containing the URL part of the HTTP query.

Parameters:
queryField - The name of the field containing the URL part of the HTTP query.


setRefererField

public void setRefererField(String refererField)
Sets the name of the field containing the referer.

Parameters:
refererField - The referer field name.


setRemoteHostField

public void setRemoteHostField(String remoteHostField)
Sets the name of the field containing the remote host.

Parameters:
remoteHostField - The name of the remote host field.


setResolveHosts

public void setResolveHosts(String resolveHosts)
Determines whether IP host name resolution is done.

Parameters:
resolveHosts - "true" or "false", if host IP resolution is desired or not.


setStatusField

public void setStatusField(String statusField)
Sets the name of the field containing the HTTP response status code.

Parameters:
statusField - The name of the HTTP response status code field.


setTableName

public void setTableName(String tableName)
Sets the name of the table where the logs are stored.

Parameters:
tableName - The name of the table.


setTimestampField

public void setTimestampField(String timestampField)
Sets the name of the field containing the server-determined timestamp.

Parameters:
timestampField - The name of the server-determined timestamp field.


setUserAgentField

public void setUserAgentField(String userAgentField)
Sets the name of the field containing the user agent.

Parameters:
userAgentField - The name of the user agent field.


setUserField

public void setUserField(String userField)
Sets the name of the field containing the remote user name.

Parameters:
userField - The name of the remote user field.


setVirtualHostField

public void setVirtualHostField(String virtualHostField)
Sets the name of the field containing the virtual host information (this is in fact the server name).

Parameters:
virtualHostField - The name of the virtual host field.


start

public void start()
            throws LifecycleException
Invoked by Tomcat on startup. The database connection is set here.
Specified by:
start in interface Lifecycle

Throws:
LifecycleException - Can be thrown on lifecycle inconsistencies or on database errors (as a wrapped SQLException).


stop

public void stop()
            throws LifecycleException
Invoked by tomcat on shutdown. The database connection is closed here.
Specified by:
stop in interface Lifecycle

Throws:
LifecycleException - Can be thrown on lifecycle inconsistencies or on database errors (as a wrapped SQLException).


Copyright B) 2000-2003 Apache Software Foundation. All Rights Reserved.