Top Description Fields Constructors Methods
org.apache.catalina.valves

public final Class JDBCAccessLogValve

extends ValveBase
implements AccessLog
Class Inheritance
All Implemented Interfaces
org.apache.catalina.AccessLog
Imports
java.io.IOException, java.sql.Connection, .Driver, .PreparedStatement, .SQLException, .Timestamp, java.util.Properties, jakarta.servlet.ServletException, org.apache.catalina.AccessLog, .LifecycleException, org.apache.catalina.connector.Request, .Response, org.apache.tomcat.util.ExceptionUtils

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,
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.

Authors
Andre de Jesus, Peter Rossbach

Field Summary

Modifier and TypeField and Description
private String
bytesField

private Connection
conn

pack-priv String
connectionName

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

pack-priv String
connectionPassword

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

private String
connectionURL

private long
currentTimeMillis

pack-priv Driver
driver

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

private String
driverName

private String
methodField

private String
pattern

private PreparedStatement
ps

private String
queryField

private String
refererField

private String
remoteHostField

pack-priv boolean
requestAttributesEnabled

Should this valve set request attributes for IP address, hostname, protocol and port used for the request.

private boolean
resolveHosts

private String
statusField

private String
tableName

private String
timestampField

pack-priv boolean
useLongContentLength

Use long contentLength as you have more 4 GB output.

private String
userAgentField

private String
userField

private String
virtualHostField

Inherited from org.apache.catalina.valves.ValveBase:
asyncSupportedcontainercontainerLognextsm

Constructor Summary

AccessConstructor and Description
public
JDBCAccessLogValve()

Class constructor.

Method Summary

Modifier and TypeMethod and Description
protected void
close()

Close the specified database connection.

public String

Returns:

the username to use to connect to the database.
getConnectionName()

public String

Returns:

the password to use to connect to the database.
getConnectionPassword()

public long
getCurrentTimeMillis()

public boolean
getRequestAttributesEnabled()

Implements org.apache.catalina.AccessLog.getRequestAttributesEnabled.

public boolean

Returns:

true if content length should be considered a long rather than an int, defaults to false
getUseLongContentLength()

public void
invoke(Request
The Request object.
request, Response
The Response object.
response)

Implements org.apache.catalina.Valve.invoke.

This method is invoked by Tomcat on each query.

public void
log(Request
Request (associated with the response) to log
request, Response
Response (associated with the request) to log
response, long
Time taken to process the request/response in nanoseconds (use 0 if not known); in Tomcat versions prior to 10, the time unit was milliseconds
time)

Implements org.apache.catalina.AccessLog.log.

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.

public void
setBytesField(String
The name of the returned bytes field.
bytesField)

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

public void
setConnectionName(String
Username
connectionName)

Set the username to use to connect to the database.

public void
setConnectionPassword(String
User password
connectionPassword)

Set the password to use to connect to the database.

public void
setConnectionURL(String
The JDBC URL of the database.
connectionURL)

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

public void
setDriverName(String
The complete name of the database driver class.
driverName)

Sets the database driver name.

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

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

public void
setPattern(String
The name of the logging pattern.
pattern)

Sets the logging pattern.

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

Sets the name of the field containing the URL part of the HTTP query.

public void
setRefererField(String
The referer field name.
refererField)

Sets the name of the field containing the referer.

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

Sets the name of the field containing the remote host.

public void
setRequestAttributesEnabled(boolean
true causes the attributes to be used, false causes the original values to be used.
requestAttributesEnabled)

Implements org.apache.catalina.AccessLog.setRequestAttributesEnabled.

Should this valve use request attributes for IP address, hostname, protocol and port used for the request?

public void
setResolveHosts(String
"true" or "false", if host IP resolution is desired or not.
resolveHosts)

Determines whether IP host name resolution is done.

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

Sets the name of the field containing the HTTP response status code.

public void
setTableName(String
The name of the table.
tableName)

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

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

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

public void
setUseLongContentLength(boolean
the useLongContentLength to set
useLongContentLength)

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

Sets the name of the field containing the user agent.

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

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

public void
setVirtualHostField(String
The name of the virtual host field.
virtualHostField)

Sets the name of the field containing the virtual host information (this is in fact the server name).

protected void
startInternal()

Overrides org.apache.catalina.valves.ValveBase.startInternal.

Start this component and implement the requirements of org.apache.catalina.util.LifecycleBase#startInternal().

protected void
stopInternal()

Overrides org.apache.catalina.valves.ValveBase.stopInternal.

Stop this component and implement the requirements of org.apache.catalina.util.LifecycleBase#stopInternal().

Inherited from org.apache.catalina.valves.ValveBase:
backgroundProcessgetContainergetDomainInternalgetNextgetObjectNameKeyPropertiesinitInternalisAsyncSupportedsetAsyncSupportedsetContainersetNexttoString

Field Detail

bytesFieldback to summary
private String bytesField
connback to summary
private Connection conn
connectionNameback to summary
pack-priv String connectionName

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

connectionPasswordback to summary
pack-priv String connectionPassword

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

connectionURLback to summary
private String connectionURL
currentTimeMillisback to summary
private long currentTimeMillis
driverback to summary
pack-priv Driver driver

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

driverNameback to summary
private String driverName
methodFieldback to summary
private String methodField
patternback to summary
private String pattern
psback to summary
private PreparedStatement ps
queryFieldback to summary
private String queryField
refererFieldback to summary
private String refererField
remoteHostFieldback to summary
private String remoteHostField
requestAttributesEnabledback to summary
pack-priv boolean requestAttributesEnabled

Should this valve set request attributes for IP address, hostname, protocol and port used for the request. Default is true.

See Also
setRequestAttributesEnabled(boolean)
resolveHostsback to summary
private boolean resolveHosts
statusFieldback to summary
private String statusField
tableNameback to summary
private String tableName
timestampFieldback to summary
private String timestampField
useLongContentLengthback to summary
pack-priv boolean useLongContentLength

Use long contentLength as you have more 4 GB output.

Since
6.0.15
userAgentFieldback to summary
private String userAgentField
userFieldback to summary
private String userField
virtualHostFieldback to summary
private String virtualHostField

Constructor Detail

JDBCAccessLogValveback to summary
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

closeback to summary
protected void close()

Close the specified database connection.

getConnectionNameback to summary
public String getConnectionName()
Returns:String

the username to use to connect to the database.

getConnectionPasswordback to summary
public String getConnectionPassword()
Returns:String

the password to use to connect to the database.

getCurrentTimeMillisback to summary
public long getCurrentTimeMillis()
getRequestAttributesEnabledback to summary
public boolean getRequestAttributesEnabled()

Implements org.apache.catalina.AccessLog.getRequestAttributesEnabled.

Returns:boolean

Doc from org.apache.catalina.AccessLog.getRequestAttributesEnabled.

true if the attributes will be logged, otherwise false

Annotations
@Override
getUseLongContentLengthback to summary
public boolean getUseLongContentLength()
Returns:boolean

true if content length should be considered a long rather than an int, defaults to false

invokeback to summary
public void invoke(Request request, Response response) throws IOException, ServletException

Implements org.apache.catalina.Valve.invoke.

This method is invoked by Tomcat on each query.

Parameters
request:Request

The Request object.

response:Response

The Response object.

Annotations
@Override
Exceptions
IOException:
Should not be thrown.
ServletException:
Database SQLException is wrapped in a ServletException.
logback to summary
public void log(Request request, Response response, long time)

Implements org.apache.catalina.AccessLog.log.

Doc from org.apache.catalina.AccessLog.log.

Add the request/response to the access log using the specified processing time.

Parameters
request:Request

Request (associated with the response) to log

response:Response

Response (associated with the request) to log

time:long

Time taken to process the request/response in nanoseconds (use 0 if not known); in Tomcat versions prior to 10, the time unit was milliseconds

Annotations
@Override
openback to summary
protected void open() throws SQLException

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

Exceptions
SQLException:
if a database error occurs
setBytesFieldback to summary
public void setBytesField(String bytesField)

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

Parameters
bytesField:String

The name of the returned bytes field.

setConnectionNameback to summary
public void setConnectionName(String connectionName)

Set the username to use to connect to the database.

Parameters
connectionName:String

Username

setConnectionPasswordback to summary
public void setConnectionPassword(String connectionPassword)

Set the password to use to connect to the database.

Parameters
connectionPassword:String

User password

setConnectionURLback to summary
public void setConnectionURL(String connectionURL)

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

Parameters
connectionURL:String

The JDBC URL of the database.

setDriverNameback to summary
public void setDriverName(String driverName)

Sets the database driver name.

Parameters
driverName:String

The complete name of the database driver class.

setMethodFieldback to summary
public void setMethodField(String methodField)

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

Parameters
methodField:String

The name of the HTTP request method field.

setPatternback to summary
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:String

The name of the logging pattern.

setQueryFieldback to summary
public void setQueryField(String queryField)

Sets the name of the field containing the URL part of the HTTP query.

Parameters
queryField:String

The name of the field containing the URL part of the HTTP query.

setRefererFieldback to summary
public void setRefererField(String refererField)

Sets the name of the field containing the referer.

Parameters
refererField:String

The referer field name.

setRemoteHostFieldback to summary
public void setRemoteHostField(String remoteHostField)

Sets the name of the field containing the remote host.

Parameters
remoteHostField:String

The name of the remote host field.

setRequestAttributesEnabledback to summary
public void setRequestAttributesEnabled(boolean requestAttributesEnabled)

Implements org.apache.catalina.AccessLog.setRequestAttributesEnabled.

Doc from org.apache.catalina.AccessLog.setRequestAttributesEnabled.

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.
Parameters
requestAttributesEnabled:boolean

true causes the attributes to be used, false causes the original values to be used.

Annotations
@Override
setResolveHostsback to summary
public void setResolveHosts(String resolveHosts)

Determines whether IP host name resolution is done.

Parameters
resolveHosts:String

"true" or "false", if host IP resolution is desired or not.

setStatusFieldback to summary
public void setStatusField(String statusField)

Sets the name of the field containing the HTTP response status code.

Parameters
statusField:String

The name of the HTTP response status code field.

setTableNameback to summary
public void setTableName(String tableName)

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

Parameters
tableName:String

The name of the table.

setTimestampFieldback to summary
public void setTimestampField(String timestampField)

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

Parameters
timestampField:String

The name of the server-determined timestamp field.

setUseLongContentLengthback to summary
public void setUseLongContentLength(boolean useLongContentLength)
Parameters
useLongContentLength:boolean

the useLongContentLength to set

setUserAgentFieldback to summary
public void setUserAgentField(String userAgentField)

Sets the name of the field containing the user agent.

Parameters
userAgentField:String

The name of the user agent field.

setUserFieldback to summary
public void setUserField(String userField)

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

Parameters
userField:String

The name of the remote user field.

setVirtualHostFieldback to summary
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:String

The name of the virtual host field.

startInternalback to summary
protected void startInternal() throws LifecycleException

Overrides org.apache.catalina.valves.ValveBase.startInternal.

Start this component and implement the requirements of org.apache.catalina.util.LifecycleBase#startInternal().

Annotations
@Override
Exceptions
LifecycleException:
if this component detects a fatal error that prevents this component from being used
stopInternalback to summary
protected void stopInternal() throws LifecycleException

Overrides org.apache.catalina.valves.ValveBase.stopInternal.

Stop this component and implement the requirements of org.apache.catalina.util.LifecycleBase#stopInternal().

Annotations
@Override
Exceptions
LifecycleException:
if this component detects a fatal error that prevents this component from being used