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

# Class AccessLogValve

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.valves.ValveBase
org.apache.catalina.valves.AbstractAccessLogValve
org.apache.catalina.valves.AccessLogValve

All Implemented Interfaces:
  `MBeanRegistration, AccessLog, Contained, JmxEnabled, Lifecycle, Valve`

Direct Known Subclasses:
  `ExtendedAccessLogValve, JsonAccessLogValve`

public class AccessLogValve extends AbstractAccessLogValve
This is a concrete implementation of `AbstractAccessLogValve` that outputs the access log to a file. The features of this implementation include:

- Automatic date-based rollover of log files
- Optional log file rotation

For UNIX users, another field called `checkExists` is also available. If set to true, the log file's existence will be checked before each logging. This way an external log rotator can move the file somewhere and Tomcat will start with a new file.

For JMX junkies, a public method called `rotate` has been made available to allow you to tell this instance to move the existing log file to somewhere else and start writing a new log file.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class AbstractAccessLogValve

  `AbstractAccessLogValve.AccessLogElement, AbstractAccessLogValve.ByteSentElement, AbstractAccessLogValve.CachedElement, AbstractAccessLogValve.ConnectionStatusElement, AbstractAccessLogValve.CookieElement, AbstractAccessLogValve.DateAndTimeElement, AbstractAccessLogValve.DateFormatCache, AbstractAccessLogValve.ElapsedTimeElement, AbstractAccessLogValve.FirstByteTimeElement, AbstractAccessLogValve.HeaderElement, AbstractAccessLogValve.HostElement, AbstractAccessLogValve.HttpStatusCodeElement, AbstractAccessLogValve.IdentifierElement, AbstractAccessLogValve.LocalAddrElement, AbstractAccessLogValve.LocalServerNameElement, AbstractAccessLogValve.LogicalUserNameElement, AbstractAccessLogValve.MethodElement, AbstractAccessLogValve.PortElement, AbstractAccessLogValve.ProtocolElement, AbstractAccessLogValve.QueryElement, AbstractAccessLogValve.RemoteAddrElement, AbstractAccessLogValve.RequestAttributeElement, AbstractAccessLogValve.RequestElement, AbstractAccessLogValve.RequestURIElement, AbstractAccessLogValve.ResponseHeaderElement, AbstractAccessLogValve.SessionAttributeElement, AbstractAccessLogValve.SessionIdElement, AbstractAccessLogValve.StringElement, AbstractAccessLogValve.ThreadNameElement, AbstractAccessLogValve.UserElement`

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected File`
  `currentLogFile`
  The current log file we are writing to.
  `protected String`
  `encoding`
  Character set used by the log file.
  `protected String`
  `fileDateFormat`
  Date format to place in log file name.
  `protected SimpleDateFormat`
  `fileDateFormatter`
  A date formatter to format a Date using the format given by `fileDateFormat`.
  `protected String`
  `prefix`
  The prefix that is added to log file filenames.
  `protected boolean`
  `renameOnRotate`
  Should we defer inclusion of the date stamp in the file name until rotate time?
  `protected boolean`
  `rotatable`
  Should we rotate our log file?
  `protected String`
  `suffix`
  The suffix that is added to log file filenames.
  `protected PrintWriter`
  `writer`
  The PrintWriter to which we are currently logging, if any.

  ### Fields inherited from class AbstractAccessLogValve

  `cachedElements, condition, conditionIf, enabled, locale, localeName, logElements, pattern, requestAttributesEnabled`

  ### Fields inherited from class ValveBase

  `asyncSupported, container, containerLog, next, sm`

  ### 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
  `AccessLogValve()`
  Constructs a new AccessLogValve.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `backgroundProcess()`
  Provides support for access log rotation.
  `String`
  `getDirectory()`
  Returns the directory in which log files are created.
  `String`
  `getEncoding()`
  Return the character set name that is used to write the log file.
  `String`
  `getFileDateFormat()`
  Returns the date format used for date-based log rotation.
  `int`
  `getMaxDays()`
  Returns the maximum number of days to retain log files.
  `String`
  `getPrefix()`
  Returns the log file prefix.
  `String`
  `getSuffix()`
  Returns the log file suffix.
  `boolean`
  `isBuffered()`
  Is the logging buffered.
  `boolean`
  `isCheckExists()`
  Check for file existence before logging.
  `boolean`
  `isRenameOnRotate()`
  Should we defer inclusion of the date stamp in the file name until rotate time.
  `boolean`
  `isRotatable()`
  Should we rotate the access log.
  `void`
  `log(CharArrayWriter message)`
  Log the specified message.
  `protected void`
  `open()`
  Open the new log file for the date specified by `dateStamp`.
  `void`
  `rotate()`
  Rotate the log file if necessary.
  `boolean`
  `rotate(String newFileName)`
  Rename the existing log file to something else.
  `void`
  `setBuffered(boolean buffered)`
  Set the value if the logging should be buffered
  `void`
  `setCheckExists(boolean checkExists)`
  Set whether to check for log file existence before logging.
  `void`
  `setDirectory(String directory)`
  Set the directory in which we create log files.
  `void`
  `setEncoding(String encoding)`
  Set the character set that is used to write the log file.
  `void`
  `setFileDateFormat(String fileDateFormat)`
  Set the date format date based log rotation.
  `void`
  `setMaxDays(int maxDays)`
  Set the maximum number of days to retain log files.
  `void`
  `setPrefix(String prefix)`
  Set the log file prefix.
  `void`
  `setRenameOnRotate(boolean renameOnRotate)`
  Set the value if we should defer inclusion of the date stamp in the file name until rotate time
  `void`
  `setRotatable(boolean rotatable)`
  Configure whether the access log should be rotated.
  `void`
  `setSuffix(String suffix)`
  Set the log file suffix.
  `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 AbstractAccessLogValve

  `appendQueryString, createAccessLogElement, createAccessLogElement, createLogElements, escapeAndAppend, escapeAndAppend, findLocale, getCondition, getConditionIf, getConditionUnless, getEnabled, getIpv6Canonical, getLocale, getMaxLogMessageBufferSize, getPattern, getRequestAttributesEnabled, invoke, log, setCondition, setConditionIf, setConditionUnless, setEnabled, setIpv6Canonical, setLocale, setMaxLogMessageBufferSize, setPattern, setRequestAttributesEnabled`

  ### Methods inherited from class ValveBase

  `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

  - ### prefix

    protected volatile String prefix
    The prefix that is added to log file filenames.

  - ### rotatable

    protected boolean rotatable
    Should we rotate our log file? Default is true (like old behavior)

  - ### renameOnRotate

    protected boolean renameOnRotate
    Should we defer inclusion of the date stamp in the file name until rotate time? Default is false.

  - ### suffix

    protected volatile String suffix
    The suffix that is added to log file filenames.

  - ### writer

    protected PrintWriter writer
    The PrintWriter to which we are currently logging, if any.

  - ### fileDateFormatter

    protected SimpleDateFormat fileDateFormatter
    A date formatter to format a Date using the format given by `fileDateFormat`.

  - ### currentLogFile

    protected File currentLogFile
    The current log file we are writing to. Helpful when checkExists is true.

  - ### fileDateFormat

    protected String fileDateFormat
    Date format to place in log file name.

  - ### encoding

    protected volatile String encoding
    Character set used by the log file. If it is `null`, UTF-8 will be used. An empty string will be treated as `null` when this property is assigned.

- ## Constructor Details

  - ### AccessLogValve

    public AccessLogValve()
    Constructs a new AccessLogValve.

- ## Method Details

  - ### getMaxDays

    public int getMaxDays()
    Returns the maximum number of days to retain log files.
    Returns:
      the maximum number of days to retain log files

  - ### setMaxDays

    public void setMaxDays(int maxDays)
    Set the maximum number of days to retain log files.
    Parameters:
      `maxDays` - the maximum number of days

  - ### getDirectory

    public String getDirectory()
    Returns the directory in which log files are created.
    Returns:
      the directory in which we create log files.

  - ### setDirectory

    public void setDirectory(String directory)
    Set the directory in which we create log files.
    Parameters:
      `directory` - The new log file directory

  - ### isCheckExists

    public boolean isCheckExists()
    Check for file existence before logging.
    Returns:
      `true` if file existence is checked first

  - ### setCheckExists

    public void setCheckExists(boolean checkExists)
    Set whether to check for log file existence before logging.
    Parameters:
      `checkExists` - true meaning to check for file existence.

  - ### getPrefix

    public String getPrefix()
    Returns the log file prefix.
    Returns:
      the log file prefix.

  - ### setPrefix

    public void setPrefix(String prefix)
    Set the log file prefix.
    Parameters:
      `prefix` - The new log file prefix

  - ### isRotatable

    public boolean isRotatable()
    Should we rotate the access log.
    Returns:
      `true` if the access log should be rotated

  - ### setRotatable

    public void setRotatable(boolean rotatable)
    Configure whether the access log should be rotated.
    Parameters:
      `rotatable` - true if the log should be rotated

  - ### isRenameOnRotate

    public boolean isRenameOnRotate()
    Should we defer inclusion of the date stamp in the file name until rotate time.
    Returns:
      `true` if the logs file names are time stamped only when they are rotated

  - ### setRenameOnRotate

    public void setRenameOnRotate(boolean renameOnRotate)
    Set the value if we should defer inclusion of the date stamp in the file name until rotate time
    Parameters:
      `renameOnRotate` - true if defer inclusion of date stamp

  - ### isBuffered

    public boolean isBuffered()
    Is the logging buffered. Usually buffering can increase performance.
    Returns:
      `true` if the logging uses a buffer

  - ### setBuffered

    public void setBuffered(boolean buffered)
    Set the value if the logging should be buffered
    Parameters:
      `buffered` - `true` if buffered.

  - ### getSuffix

    public String getSuffix()
    Returns the log file suffix.
    Returns:
      the log file suffix.

  - ### setSuffix

    public void setSuffix(String suffix)
    Set the log file suffix.
    Parameters:
      `suffix` - The new log file suffix

  - ### getFileDateFormat

    public String getFileDateFormat()
    Returns the date format used for date-based log rotation.
    Returns:
      the date format date based log rotation.

  - ### setFileDateFormat

    public void setFileDateFormat(String fileDateFormat)
    Set the date format date based log rotation.
    Parameters:
      `fileDateFormat` - The format for the file timestamp

  - ### getEncoding

    public String getEncoding()
    Return the character set name that is used to write the log file.
    Returns:
      Character set name, or `null` if the default character set is used.

  - ### setEncoding

    public void setEncoding(String encoding)
    Set the character set that is used to write the log file.
    Parameters:
      `encoding` - The name of the character set.

  - ### backgroundProcess

    public void backgroundProcess()
    Provides support for access log rotation.
    Specified by:
      `backgroundProcess` in interface `Valve`
    Overrides:
      `backgroundProcess` in class `ValveBase`

  - ### rotate

    public void rotate()
    Rotate the log file if necessary.

  - ### rotate

    public boolean rotate(String newFileName)
    Rename the existing log file to something else. Then open the old log file name up once again. Intended to be called by a JMX agent.
    Parameters:
      `newFileName` - The file name to move the log file entry to
    Returns:
      true if a file was rotated with no error

  - ### log

    public void log(CharArrayWriter message)
    Description copied from class: `AbstractAccessLogValve`
    Log the specified message.
    Specified by:
      `log` in class `AbstractAccessLogValve`
    Parameters:
      `message` - Message to be logged. This object will be recycled by the calling method.

  - ### open

    protected void open()
    Open the new log file for the date specified by `dateStamp`.

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