## org.apache.catalina.valves
Class JDBCAccessLogValve

    java.lang.Object
      org.apache.catalina.valves.ValveBase
          org.apache.catalina.valves.JDBCAccessLogValve

All Implemented Interfaces:
  Contained, Lifecycle, javax.management.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.

Author:
  Andre de Jesus, Peter Rossbach

Field Summary
`protected java.lang.String` `connectionName` The connection username to use when trying to connect to the database.
`protected java.lang.String` `connectionPassword` The connection URL to use when trying to connect to the database.
`protected java.sql.Driver` `driver` Instance of the JDBC Driver class we use as a connection factory.
`protected static java.lang.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, mserver, oname`

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.
`java.lang.String` `getConnectionName()` Return the username to use to connect to the database.
`java.lang.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(java.lang.String message)` Log a message on the Logger associated with our Container (if any)
`protected void` `log(java.lang.String message, java.lang.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(java.lang.String bytesField)` Sets the name of the field containing the number of bytes returned.
`void` `setConnectionName(java.lang.String connectionName)` Set the username to use to connect to the database.
`void` `setConnectionPassword(java.lang.String connectionPassword)` Set the password to use to connect to the database.
`void` `setConnectionURL(java.lang.String connectionURL)` Sets the JDBC URL for the database where the log is stored.
`void` `setDriverName(java.lang.String driverName)` Sets the database driver name.
`void` `setMethodField(java.lang.String methodField)` Sets the name of the field containing the HTTP request method.
`void` `setPattern(java.lang.String pattern)` Sets the logging pattern.
`void` `setQueryField(java.lang.String queryField)` Sets the name of the field containing the URL part of the HTTP query.
`void` `setRefererField(java.lang.String refererField)` Sets the name of the field containing the referer.
`void` `setRemoteHostField(java.lang.String remoteHostField)` Sets the name of the field containing the remote host.
`void` `setResolveHosts(java.lang.String resolveHosts)` Determines whether IP host name resolution is done.
`void` `setStatusField(java.lang.String statusField)` Sets the name of the field containing the HTTP response status code.
`void` `setTableName(java.lang.String tableName)` Sets the name of the table where the logs are stored.
`void` `setTimestampField(java.lang.String timestampField)` Sets the name of the field containing the server-determined timestamp.
`void` `setUserAgentField(java.lang.String userAgentField)` Sets the name of the field containing the user agent.
`void` `setUserField(java.lang.String userField)` Sets the name of the field containing the remote user name.
`void` `setVirtualHostField(java.lang.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, postDeregister, postRegister, preDeregister, preRegister, setContainer, setController, setDebug, setObjectName`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### connectionName

    protected java.lang.String connectionName

  The connection username to use when trying to connect to the database.

### connectionPassword

    protected java.lang.String connectionPassword

  The connection URL to use when trying to connect to the database.

### driver

    protected java.sql.Driver driver

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

### info

    protected static java.lang.String info

  The descriptive information about this implementation.

### lifecycle

    protected LifecycleSupport lifecycle

  The lifecycle event support for this component.

Constructor Detail

### 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 Detail

### getConnectionName

    public java.lang.String getConnectionName()

  Return the username to use to connect to the database.

### setConnectionName

    public void setConnectionName(java.lang.String connectionName)

  Set the username to use to connect to the database.

  Parameters:
    `connectionName` - Username

### setDriverName

    public void setDriverName(java.lang.String driverName)

  Sets the database driver name.

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

### getConnectionPassword

    public java.lang.String getConnectionPassword()

  Return the password to use to connect to the database.

### setConnectionPassword

    public void setConnectionPassword(java.lang.String connectionPassword)

  Set the password to use to connect to the database.

  Parameters:
    `connectionPassword` - User password

### setConnectionURL

    public void setConnectionURL(java.lang.String connectionURL)

  Sets the JDBC URL for the database where the log is stored.

  Parameters:
    `connectionURL` - The JDBC URL of the database.

### setTableName

    public void setTableName(java.lang.String tableName)

  Sets the name of the table where the logs are stored.

  Parameters:
    `tableName` - The name of the table.

### setRemoteHostField

    public void setRemoteHostField(java.lang.String remoteHostField)

  Sets the name of the field containing the remote host.

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

### setUserField

    public void setUserField(java.lang.String userField)

  Sets the name of the field containing the remote user name.

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

### setTimestampField

    public void setTimestampField(java.lang.String timestampField)

  Sets the name of the field containing the server-determined timestamp.

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

### setVirtualHostField

    public void setVirtualHostField(java.lang.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.

### setMethodField

    public void setMethodField(java.lang.String methodField)

  Sets the name of the field containing the HTTP request method.

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

### setQueryField

    public void setQueryField(java.lang.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.

### setStatusField

    public void setStatusField(java.lang.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.

### setBytesField

    public void setBytesField(java.lang.String bytesField)

  Sets the name of the field containing the number of bytes returned.

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

### setRefererField

    public void setRefererField(java.lang.String refererField)

  Sets the name of the field containing the referer.

  Parameters:
    `refererField` - The referer field name.

### setUserAgentField

    public void setUserAgentField(java.lang.String userAgentField)

  Sets the name of the field containing the user agent.

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

### setPattern

    public void setPattern(java.lang.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.

### setResolveHosts

    public void setResolveHosts(java.lang.String resolveHosts)

  Determines whether IP host name resolution is done.

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

### invoke

    public void invoke(Request request,
                       Response response,
                       ValveContext context)
                throws java.io.IOException,
                       javax.servlet.ServletException

  This method is invoked by Tomcat on each query.

  Specified by:
    `invoke` in interface `Valve`
  Specified by:
    `invoke` in class `ValveBase`
  Parameters:
    `request` - The Request object.
    `response` - The Response object.
    `context` - The ValveContext object.
  Throws:
    `java.io.IOException` - Should not be thrown.
    `javax.servlet.ServletException` - Database SQLException is wrapped in a ServletException.

### addLifecycleListener

    public void addLifecycleListener(LifecycleListener listener)

  Adds a Lifecycle listener.

  Specified by:
    `addLifecycleListener` in interface `Lifecycle`
  Parameters:
    `listener` - The listener to add.

### 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`

### removeLifecycleListener

    public void removeLifecycleListener(LifecycleListener listener)

  Removes a Lifecycle listener.

  Specified by:
    `removeLifecycleListener` in interface `Lifecycle`
  Parameters:
    `listener` - The listener to remove.

### open

    protected void open()
                 throws java.sql.SQLException

  Open (if necessary) and return a database connection for use by this AccessLogValve.

  Throws:
    `java.sql.SQLException` - if a database error occurs

### close

    protected void close()

  Close the specified database connection.

### 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).

### getCurrentTimeMillis

    public long getCurrentTimeMillis()

### log

    protected void log(java.lang.String message)

  Log a message on the Logger associated with our Container (if any)

  Parameters:
    `message` - Message to be logged

### log

    protected void log(java.lang.String message,
                       java.lang.Throwable throwable)

  Log a message on the Logger associated with our Container (if any)

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

Copyright © 2000-2003 Apache Software Foundation. All Rights Reserved.