AccessLogValve (Apache Tomcat 10.1.2 API Documentation)

Package org.apache.catalina.valves

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

      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 org.apache.catalina.valves.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.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 org.apache.catalina.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 org.apache.catalina.valves.AbstractAccessLogValve

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

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

      `asyncSupported, container, containerLog, next, sm`

    - ### 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 | Description
    --- | ---
    `AccessLogValve()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `backgroundProcess()` | Execute a periodic task, such as reloading, etc.
    `String` | `getDirectory()` |
    `String` | `getEncoding()` | Return the character set name that is used to write the log file.
    `String` | `getFileDateFormat()` |
    `int` | `getMaxDays()` |
    `String` | `getPrefix()` |
    `String` | `getSuffix()` |
    `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 to the log file, switching files if the date has changed since the previous log call.
    `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)` |
    `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 org.apache.catalina.valves.AbstractAccessLogValve

      `createAccessLogElement, createAccessLogElement, createLogElements, 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 org.apache.catalina.valves.ValveBase

      `getContainer, getDomainInternal, 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, 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`

- - ### Field Detail

    - #### 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`, the system default character set will be used. An empty string will be treated as `null` when this property is assigned.

  - ### Constructor Detail

    - #### AccessLogValve

          public AccessLogValve()

  - ### Method Detail

    - #### getMaxDays

          public int getMaxDays()

    - #### setMaxDays

          public void setMaxDays​(int maxDays)

    - #### getDirectory

          public String getDirectory()

      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.

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

    - #### 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 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 system 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()

      Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.
      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)

      Log the specified message to the log file, switching files if the date has changed since the previous log call.
      Specified by:
        `log` in class `AbstractAccessLogValve`
      Parameters:
        `message` - Message to be logged

    - #### 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 `AbstractAccessLogValve`
      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 `AbstractAccessLogValve`
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used