JDBCAccessLogValve (Apache Tomcat 9.0.111 API Documentation)
Description: declaration: package: org.apache.catalina.valves, class: JDBCAccessLogValve

# Class JDBCAccessLogValve

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`

@Deprecated public class JDBCAccessLogValve extends ValveBase implements AccessLog
Deprecated.
Non scalable design, and not documented. Will be removed in Tomcat 12.

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 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,
    query VARCHAR(255) NOT NULL,
    status SMALLINT UNSIGNED NOT NULL,
    bytes INT UNSIGNED NOT NULL,
    virtualHost VARCHAR(64) NOT NULL,
    method VARCHAR(8) 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`

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected String`
  `bytesField`
  Deprecated.
  `protected Connection`
  `conn`
  Deprecated.
  `protected String`
  `connectionName`
  Deprecated.
  The connection username to use when trying to connect to the database.
  `protected String`
  `connectionPassword`
  Deprecated.
  The connection URL to use when trying to connect to the database.
  `protected String`
  `connectionURL`
  Deprecated.
  `protected long`
  `currentTimeMillis`
  Deprecated.
  `protected Driver`
  `driver`
  Deprecated.
  Instance of the JDBC Driver class we use as a connection factory.
  `protected String`
  `driverName`
  Deprecated.
  `protected String`
  `methodField`
  Deprecated.
  `protected String`
  `pattern`
  Deprecated.
  `protected PreparedStatement`
  `ps`
  Deprecated.
  `protected String`
  `queryField`
  Deprecated.
  `protected String`
  `refererField`
  Deprecated.
  `protected String`
  `remoteHostField`
  Deprecated.
  `protected boolean`
  `requestAttributesEnabled`
  Deprecated.
  Should this valve set request attributes for IP address, hostname, protocol and port used for the request.
  `protected boolean`
  `resolveHosts`
  Deprecated.
  `protected String`
  `statusField`
  Deprecated.
  `protected String`
  `tableName`
  Deprecated.
  `protected String`
  `timestampField`
  Deprecated.
  `protected boolean`
  `useLongContentLength`
  Deprecated.
  Use long contentLength as you have more 4 GB output.
  `protected String`
  `userAgentField`
  Deprecated.
  `protected String`
  `userField`
  Deprecated.
  `protected String`
  `virtualHostField`
  Deprecated.

  ### Fields inherited from class ValveBase

  `asyncSupported, container, containerLog, next, sm`

  ### Fields inherited from class LifecycleMBeanBase

  `mserver`

  ### Fields inherited from interface AccessLog

  `PROTOCOL_ATTRIBUTE, REMOTE_ADDR_ATTRIBUTE, REMOTE_HOST_ATTRIBUTE, SERVER_NAME_ATTRIBUTE, SERVER_PORT_ATTRIBUTE`

  ### Fields inherited from interface 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
  Description
  `JDBCAccessLogValve()`
  Deprecated.
  Class constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `close()`
  Deprecated.
  Close the specified database connection.
  `String`
  `getConnectionName()`
  Deprecated.
  `String`
  `getConnectionPassword()`
  Deprecated.
  `long`
  `getCurrentTimeMillis()`
  Deprecated.
  `boolean`
  `getRequestAttributesEnabled()`
  Deprecated.
  `boolean`
  `getUseLongContentLength()`
  Deprecated.
  `void`
  `invoke(Request request, Response response)`
  Deprecated.
  Perform request processing as required by this Valve.
  `void`
  `log(Request request, Response response, long time)`
  Deprecated.
  Add the request/response to the access log using the specified processing time.
  `protected void`
  `open()`
  Deprecated.
  Open (if necessary) and return a database connection for use by this AccessLogValve.
  `protected void`
  `prepare()`
  Deprecated.
  Prepare tables for processing.
  `void`
  `setBytesField(String bytesField)`
  Deprecated.
  Sets the name of the field containing the number of bytes returned.
  `void`
  `setConnectionName(String connectionName)`
  Deprecated.
  Set the username to use to connect to the database.
  `void`
  `setConnectionPassword(String connectionPassword)`
  Deprecated.
  Set the password to use to connect to the database.
  `void`
  `setConnectionURL(String connectionURL)`
  Deprecated.
  Sets the JDBC URL for the database where the log is stored.
  `void`
  `setDriverName(String driverName)`
  Deprecated.
  Sets the database driver name.
  `void`
  `setMethodField(String methodField)`
  Deprecated.
  Sets the name of the field containing the HTTP request method.
  `void`
  `setPattern(String pattern)`
  Deprecated.
  Sets the logging pattern.
  `void`
  `setQueryField(String queryField)`
  Deprecated.
  Sets the name of the field containing the URL part of the HTTP query.
  `void`
  `setRefererField(String refererField)`
  Deprecated.
  Sets the name of the field containing the referer.
  `void`
  `setRemoteHostField(String remoteHostField)`
  Deprecated.
  Sets the name of the field containing the remote host.
  `void`
  `setRequestAttributesEnabled(boolean requestAttributesEnabled)`
  Deprecated.
  Should this valve use request attributes for IP address, hostname, protocol and port used for the request?
  `void`
  `setResolveHosts(String resolveHosts)`
  Deprecated.
  Determines whether IP host name resolution is done.
  `void`
  `setStatusField(String statusField)`
  Deprecated.
  Sets the name of the field containing the HTTP response status code.
  `void`
  `setTableName(String tableName)`
  Deprecated.
  Sets the name of the table where the logs are stored.
  `void`
  `setTimestampField(String timestampField)`
  Deprecated.
  Sets the name of the field containing the server-determined timestamp.
  `void`
  `setUseLongContentLength(boolean useLongContentLength)`
  Deprecated.
  `void`
  `setUserAgentField(String userAgentField)`
  Deprecated.
  Sets the name of the field containing the user agent.
  `void`
  `setUserField(String userField)`
  Deprecated.
  Sets the name of the field containing the remote user name.
  `void`
  `setVirtualHostField(String virtualHostField)`
  Deprecated.
  Sets the name of the field containing the virtual host information (this is in fact the server name).
  `protected void`
  `startInternal()`
  Deprecated.
  Start this component and implement the requirements of `LifecycleBase.startInternal()`.
  `protected void`
  `stopInternal()`
  Deprecated.
  Stop this component and implement the requirements of `LifecycleBase.stopInternal()`.

  ### Methods inherited from class ValveBase

  `backgroundProcess, getContainer, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setContainer, setNext, toString`

  ### Methods inherited from class LifecycleMBeanBase

  `destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister`

  ### Methods inherited from class LifecycleBase

  `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### useLongContentLength

    protected boolean useLongContentLength
    Deprecated.
    Use long contentLength as you have more 4 GB output.
    Since:
      6.0.15

  - ### connectionName

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

  - ### connectionPassword

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

  - ### driver

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

  - ### driverName

    protected String driverName
    Deprecated.

  - ### connectionURL

    protected String connectionURL
    Deprecated.

  - ### tableName

    protected String tableName
    Deprecated.

  - ### remoteHostField

    protected String remoteHostField
    Deprecated.

  - ### userField

    protected String userField
    Deprecated.

  - ### timestampField

    protected String timestampField
    Deprecated.

  - ### virtualHostField

    protected String virtualHostField
    Deprecated.

  - ### methodField

    protected String methodField
    Deprecated.

  - ### queryField

    protected String queryField
    Deprecated.

  - ### statusField

    protected String statusField
    Deprecated.

  - ### bytesField

    protected String bytesField
    Deprecated.

  - ### refererField

    protected String refererField
    Deprecated.

  - ### userAgentField

    protected String userAgentField
    Deprecated.

  - ### pattern

    protected String pattern
    Deprecated.

  - ### resolveHosts

    protected boolean resolveHosts
    Deprecated.

  - ### conn

    protected Connection conn
    Deprecated.

  - ### ps

    protected PreparedStatement ps
    Deprecated.

  - ### currentTimeMillis

    protected long currentTimeMillis
    Deprecated.

  - ### requestAttributesEnabled

    protected boolean requestAttributesEnabled
    Deprecated.
    Should this valve set request attributes for IP address, hostname, protocol and port used for the request. Default is `true`.
    See Also:
      - `setRequestAttributesEnabled(boolean)`

- ## Constructor Details

  - ### JDBCAccessLogValve

    public JDBCAccessLogValve()
    Deprecated.
    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 Details

  - ### setRequestAttributesEnabled

    public void setRequestAttributesEnabled(boolean requestAttributesEnabled)
    Deprecated.
    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()
    Deprecated.
    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()
    Deprecated.
    Returns:
      the username to use to connect to the database.

  - ### setConnectionName

    public void setConnectionName(String connectionName)
    Deprecated.
    Set the username to use to connect to the database.
    Parameters:
      `connectionName` - Username

  - ### setDriverName

    public void setDriverName(String driverName)
    Deprecated.
    Sets the database driver name.
    Parameters:
      `driverName` - The complete name of the database driver class.

  - ### getConnectionPassword

    public String getConnectionPassword()
    Deprecated.
    Returns:
      the password to use to connect to the database.

  - ### setConnectionPassword

    public void setConnectionPassword(String connectionPassword)
    Deprecated.
    Set the password to use to connect to the database.
    Parameters:
      `connectionPassword` - User password

  - ### setConnectionURL

    public void setConnectionURL(String connectionURL)
    Deprecated.
    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)
    Deprecated.
    Sets the name of the table where the logs are stored.
    Parameters:
      `tableName` - The name of the table.

  - ### setRemoteHostField

    public void setRemoteHostField(String remoteHostField)
    Deprecated.
    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)
    Deprecated.
    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)
    Deprecated.
    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)
    Deprecated.
    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)
    Deprecated.
    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)
    Deprecated.
    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)
    Deprecated.
    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)
    Deprecated.
    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)
    Deprecated.
    Sets the name of the field containing the referer.
    Parameters:
      `refererField` - The referer field name.

  - ### setUserAgentField

    public void setUserAgentField(String userAgentField)
    Deprecated.
    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)
    Deprecated.
    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)
    Deprecated.
    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()
    Deprecated.
    Returns:
      `true` if content length should be considered a long rather than an int, defaults to `false`

  - ### setUseLongContentLength

    public void setUseLongContentLength(boolean useLongContentLength)
    Deprecated.
    Parameters:
      `useLongContentLength` - the useLongContentLength to set

  - ### invoke

    public void invoke(Request request, Response response) throws IOException, ServletException
    Deprecated.
    Description copied from interface: `Valve`

    Perform request processing as required by this Valve.

    An individual Valve MAY perform the following actions, in the specified order:

    - Examine and/or modify the properties of the specified Request and Response.
    - Examine the properties of the specified Request, completely generate the corresponding Response, and return control to the caller.
    - Examine the properties of the specified Request and Response, wrap either or both of these objects to supplement their functionality, and pass them on.
    - If the corresponding Response was not generated (and control was not returned), call the next Valve in the pipeline (if there is one) by executing `getNext().invoke()`.
    - Examine, but not modify, the properties of the resulting Response (which was created by a subsequently invoked Valve or Container).

    A Valve MUST NOT do any of the following things:

    - Change request properties that have already been used to direct the flow of processing control for this request (for instance, trying to change the virtual host to which a Request should be sent from a pipeline attached to a Host or Context in the standard implementation).
    - Create a completed Response AND pass this Request and Response on to the next Valve in the pipeline.
    - Consume bytes from the input stream associated with the Request, unless it is completely generating the response, or wrapping the request before passing it on.
    - Modify the HTTP headers included with the Response after the `getNext().invoke()` method has returned.
    - Perform any actions on the output stream associated with the specified Response after the `getNext().invoke()` method has returned.
    Specified by:
      `invoke` in interface `Valve`
    Parameters:
      `request` - The servlet request to be processed
      `response` - The servlet response to be created
    Throws:
      `IOException` - if an input/output error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet
      `ServletException` - if a servlet error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet

  - ### log

    public void log(Request request, Response response, long time)
    Deprecated.
    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
    Deprecated.
    Open (if necessary) and return a database connection for use by this AccessLogValve.
    Throws:
      `SQLException` - if a database error occurs

  - ### prepare

    protected void prepare() throws SQLException
    Deprecated.
    Prepare tables for processing. Used by subclasses for testing.
    Throws:
      `SQLException` - if an exception occurs

  - ### close

    protected void close()
    Deprecated.
    Close the specified database connection.

  - ### startInternal

    protected void startInternal() throws LifecycleException
    Deprecated.
    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
    Deprecated.
    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()
    Deprecated.