JDBCAccessLogValve (Apache Tomcat 7.0.109 API Documentation)

java.lang.Object
- org.apache.catalina.util.LifecycleBase
- - org.apache.catalina.util.LifecycleMBeanBase
  - - org.apache.catalina.valves.ValveBase
    - - org.apache.catalina.valves.JDBCAccessLogValve

All Implemented Interfaces:

MBeanRegistration, AccessLog, Contained, JmxEnabled, Lifecycle, Valve
```
public final class JDBCAccessLogValve
extends ValveBase
implements AccessLog
```
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="org.apache.catalina.valves.JDBCAccessLogValve"
          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,
 remoteHost CHAR(15) NOT NULL,
 userName 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 (timestamp),
 INDEX (remoteHost),
 INDEX (virtualHost),
 INDEX (query),
 INDEX (userAgent)
 );
 
```
Set JDBCAccessLogValve attribute useLongContentLength="true" as you have more then 4GB outputs. Please, use long SQL datatype at access.bytes attribute. The datatype of bytes at oracle is number and other databases use bytes BIGINT NOT NULL.

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

Nested Class Summary
- Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle
  Lifecycle.SingleUse

Field Summary
- Fields inherited from class org.apache.catalina.valves.ValveBase
  asyncSupported, container, containerLog, next, sm
- Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase
  mserver
- Fields inherited from interface org.apache.catalina.AccessLog
  PROTOCOL_ATTRIBUTE, REMOTE_ADDR_ATTRIBUTE, REMOTE_HOST_ATTRIBUTE, SERVER_NAME_ATTRIBUTE, SERVER_PORT_ATTRIBUTE
- Fields inherited from interface org.apache.catalina.Lifecycle
  AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

Constructors
Constructor and Description

JDBCAccessLogValve()
Class constructor.

Constructors
Constructor and Description
`JDBCAccessLogValve()` Class constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`close()` Close the specified database connection.
`String`	`getConnectionName()`
`String`	`getConnectionPassword()`
`long`	`getCurrentTimeMillis()`
`boolean`	`getRequestAttributesEnabled()`
`boolean`	`getUseLongContentLength()`
`void`	`invoke(Request request, Response response)` This method is invoked by Tomcat on each query.
`void`	`log(Request request, Response response, long time)` Add the request/response to the access log using the specified processing time.
`protected void`	`open()` Open (if necessary) and return a database connection for use by this AccessLogValve.
`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`	`setRequestAttributesEnabled(boolean requestAttributesEnabled)` Should this valve use request attributes for IP address, hostname, protocol and port used for the request?
`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`	`setUseLongContentLength(boolean useLongContentLength)`
`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).
`protected void`	`startInternal()` Start this component and implement the requirements of `LifecycleBase.startInternal()`.
`protected void`	`stopInternal()` Stop this component and implement the requirements of `LifecycleBase.stopInternal()`.

Methods inherited from class org.apache.catalina.valves.ValveBase
backgroundProcess, event, getContainer, getDomainInternal, getInfo, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setContainer, setNext, toString

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase
destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase
addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop

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

- 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 = "userName";
      timestampField = "timestamp";
      virtualHostField = "virtualHost";
      methodField = "method";
      queryField = "query";
      statusField = "status";
      bytesField = "bytes";
      refererField = "referer";
      userAgentField = "userAgent";
      pattern = "common";
      resolveHosts = false;
 
```
- Method Detail
  - setRequestAttributesEnabled
```
public void setRequestAttributesEnabled(boolean requestAttributesEnabled)
```
    Should this valve use request attributes for IP address, hostname, protocol and port used for the request? The attributes used are:
    - org.apache.catalina.RemoteAddr
    - org.apache.catalina.RemoteHost
    - org.apache.catalina.Protocol
    - org.apache.catalina.ServerName
    - org.apache.catalina.ServerPost
    Default is true.
    Specified by:
    
    setRequestAttributesEnabled in interface AccessLog
    
    Parameters:
    requestAttributesEnabled - true causes the attributes to be used, false causes the original values to be used.
  - getRequestAttributesEnabled
```
public boolean getRequestAttributesEnabled()
```
    Specified by:
    
    getRequestAttributesEnabled in interface AccessLog
    
    Returns:
    true if the attributes will be logged, otherwise false
    See Also:
    AccessLog.setRequestAttributesEnabled(boolean)
  - getConnectionName
```
public String getConnectionName()
```
    Returns:
    the username to use to connect to the database.
  - setConnectionName
```
public void setConnectionName(String connectionName)
```
    Set the username to use to connect to the database.
    
    Parameters:
    connectionName - Username
  - setDriverName
```
public void setDriverName(String driverName)
```
    Sets the database driver name.
    
    Parameters:
    driverName - The complete name of the database driver class.
  - getConnectionPassword
```
public String getConnectionPassword()
```
    Returns:
    the password to use to connect to the database.
  - 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.
  - setTableName
```
public void setTableName(String tableName)
```
    Sets the name of the table where the logs are stored.
    
    Parameters:
    tableName - The name of the table.
  - 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.
  - 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.
  - 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.
  - 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.
  - 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.
  - 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.
  - 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.
  - 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.
  - setRefererField
```
public void setRefererField(String refererField)
```
    Sets the name of the field containing the referer.
    
    Parameters:
    refererField - The referer field name.
  - 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.
  - 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.
  - 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.
  - getUseLongContentLength
```
public boolean getUseLongContentLength()
```
    Returns:
    true if content length should be considered a long rather than an int, defaults to false
  - setUseLongContentLength
```
public void setUseLongContentLength(boolean useLongContentLength)
```
    Parameters:
    useLongContentLength - the useLongContentLength to set
  - invoke
```
public void invoke(Request request,
          Response response)
            throws IOException,
                   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.
    
    Throws:
    
    IOException - Should not be thrown.
    
    ServletException - Database SQLException is wrapped in a ServletException.
  - log
```
public void log(Request request,
       Response response,
       long time)
```
    Description copied from interface: AccessLog
    
    Add the request/response to the access log using the specified processing time.
    
    Specified by:
    
    log in interface AccessLog
    
    Parameters:
    request - Request (associated with the response) to log
    response - Response (associated with the request) to log
    time - Time taken to process the request/response in milliseconds (use 0 if not known)
  - open
```
protected void open()
             throws SQLException
```
    Open (if necessary) and return a database connection for use by this AccessLogValve.
    
    Throws:
    
    SQLException - if a database error occurs
  - close
```
protected void close()
```
    Close the specified database connection.
  - startInternal
```
protected void startInternal()
                      throws LifecycleException
```
    Start this component and implement the requirements of LifecycleBase.startInternal().
    
    Overrides:
    
    startInternal in class ValveBase
    
    Throws:
    
    LifecycleException - if this component detects a fatal error that prevents this component from being used
  - stopInternal
```
protected void stopInternal()
                     throws LifecycleException
```
    Stop this component and implement the requirements of LifecycleBase.stopInternal().
    
    Overrides:
    
    stopInternal in class ValveBase
    
    Throws:
    
    LifecycleException - if this component detects a fatal error that prevents this component from being used
  - getCurrentTimeMillis
```
public long getCurrentTimeMillis()
```

Class JDBCAccessLogValve

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

Field Summary

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

Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

Fields inherited from interface org.apache.catalina.AccessLog

Fields inherited from interface org.apache.catalina.Lifecycle

Constructor Summary

Method Summary

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

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

Methods inherited from class org.apache.catalina.util.LifecycleBase

Methods inherited from class java.lang.Object

Constructor Detail

JDBCAccessLogValve

Method Detail

setRequestAttributesEnabled

getRequestAttributesEnabled

getConnectionName

setConnectionName

setDriverName

getConnectionPassword

setConnectionPassword

setConnectionURL

setTableName

setRemoteHostField

setUserField

setTimestampField

setVirtualHostField

setMethodField

setQueryField

setStatusField

setBytesField

setRefererField

setUserAgentField

setPattern

setResolveHosts

getUseLongContentLength

setUseLongContentLength

invoke

log

open

close

startInternal

stopInternal

getCurrentTimeMillis