Package org.apache.log4j.varia

## Class LogFilePatternReceiver

- java.lang.Object
- - org.apache.log4j.spi.ComponentBase
  - - org.apache.log4j.plugins.PluginSkeleton
    - - org.apache.log4j.plugins.Receiver
      - - org.apache.log4j.varia.LogFilePatternReceiver

- All Implemented Interfaces:
    `Plugin`, `Component`, `org.apache.log4j.spi.OptionHandler`, `Thresholdable`
  Direct Known Subclasses:
    `VFSLogFilePatternReceiver`

      public class LogFilePatternReceiver
      extends Receiver

  LogFilePatternReceiver can parse and tail log files, converting entries into LoggingEvents. If the file doesn't exist when the receiver is initialized, the receiver will look for the file once every 10 seconds.

  This receiver relies on java.util.regex features to perform the parsing of text in the log file, however the only regular expression field explicitly supported is a glob-style wildcard used to ignore fields in the log file if needed. All other fields are parsed by using the supplied keywords.

  Features:
  - specify the URL of the log file to be processed
  - specify the timestamp format in the file (if one exists, using patterns from `SimpleDateFormat`)
  - specify the pattern (logFormat) used in the log file using keywords, a wildcard character (*) and fixed text
  - 'tail' the file (allows the contents of the file to be continually read and new events processed)
  - supports the parsing of multi-line messages and exceptions - 'hostname' property set to URL host (or 'file' if not available) - 'application' property set to URL path (or value of fileURL if not available) - 'group' property can be set to associate multiple log file receivers

  Keywords:
  TIMESTAMP
  LOGGER
  LEVEL
  THREAD
  CLASS
  FILE
  LINE
  METHOD
  RELATIVETIME
  MESSAGE
  NDC
  PROP(key)
  (NL)

  (NL) represents a new line embedded in the log format, supporting log formats whose fields span multiple lines

  Use a * to ignore portions of the log format that should be ignored

  Example:
  If your file's patternlayout is this:
  %d %-5p [%t] %C{2} (%F:%L) - %m%n

  specify this as the log format:
  TIMESTAMP LEVEL [THREAD] CLASS (FILE:LINE) - MESSAGE

  To define a PROPERTY field, use PROP(key)

  Example:
  If you used the RELATIVETIME pattern layout character in the file, you can use PROP(RELATIVETIME) in the logFormat definition to assign the RELATIVETIME field as a property on the event.

  If your file's patternlayout is this:
  %r [%t] %-5p %c %x - %m%n

  specify this as the log format:
  PROP(RELATIVETIME) [THREAD] LEVEL LOGGER * - MESSAGE

  Note the * - it can be used to ignore a single word or sequence of words in the log file (in order for the wildcard to ignore a sequence of words, the text being ignored must be followed by some delimiter, like '-' or '[') - ndc is being ignored in the following example.

  Assign a filterExpression in order to only process events which match a filter. If a filterExpression is not assigned, all events are processed.

  Limitations:
  - no support for the single-line version of throwable supported by patternlayout
  (this version of throwable will be included as the last line of the message)
  - the relativetime patternLayout character must be set as a property: PROP(RELATIVETIME)
  - messages should appear as the last field of the logFormat because the variability in message content
  - exceptions are converted if the exception stack trace (other than the first line of the exception)
  is stored in the log file with a tab followed by the word 'at' as the first characters in the line
  - tailing may fail if the file rolls over.

  Example receiver configuration settings (add these as params, specifying a LogFilePatternReceiver 'plugin'):
  param: "timestampFormat" value="yyyy-MM-d HH:mm:ss,SSS"
  param: "logFormat" value="PROP(RELATIVETIME) [THREAD] LEVEL LOGGER * - MESSAGE"
  param: "fileURL" value="file:///c:/events.log"
  param: "tailing" value="true"

  This configuration will be able to process these sample events:
  710 [ Thread-0] DEBUG first.logger first - <test> <test2>something here</test2> <test3 blah=something/> <test4> <test5>something else</test5> </test4></test>
  880 [ Thread-2] DEBUG first.logger third - <test> <test2>something here</test2> <test3 blah=something/> <test4> <test5>something else</test5> </test4></test>
  880 [ Thread-0] INFO first.logger first - infomsg-0
  java.lang.Exception: someexception-first
  at Generator2.run(Generator2.java:102)

  Author:
    Scott Deboy

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `MISSING_FILE_RETRY_MILLIS` |

    - ### Fields inherited from class org.apache.log4j.plugins.Receiver

      `thresholdLevel`

    - ### Fields inherited from class org.apache.log4j.plugins.PluginSkeleton

      `active, name`

    - ### Fields inherited from class org.apache.log4j.spi.ComponentBase

      `repository`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `LogFilePatternReceiver()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `activateOptions()` | Read and process the log file.
    `protected void` | `createPattern()` |
    `String` | `getCustomLevelDefinitions()` |
    `String` | `getFileURL()` | Accessor
    `String` | `getFilterExpression()` | Accessor
    `String` | `getGroup()` | Accessor
    `String` | `getLogFormat()` | Accessor
    `String` | `getPath()` |
    `String` | `getTimestampFormat()` | Accessor
    `long` | `getWaitMillis()` | Accessor
    `protected void` | `initialize()` | Build the regular expression needed to parse log entries
    `boolean` | `isAppendNonMatches()` | Accessor
    `boolean` | `isTailing()` | Accessor
    `boolean` | `isUseCurrentThread()` | When true, this property uses the current Thread to perform the import, otherwise when false (the default), a new Thread is created and started to manage the import.
    `protected void` | `process​(BufferedReader bufferedReader)` | Read, parse and optionally tail the log file, converting entries into logging events.
    `void` | `setAppendNonMatches​(boolean appendNonMatches)` | Mutator
    `void` | `setCustomLevelDefinitions​(String customLevelDefinitions)` | If the log file contains non-log4j level strings, they can be mapped to log4j levels using the format (android example): V=TRACE,D=DEBUG,I=INFO,W=WARN,E=ERROR,F=FATAL,S=OFF
    `void` | `setFileURL​(String fileURL)` | Mutator
    `void` | `setFilterExpression​(String filterExpression)` | Mutator
    `void` | `setGroup​(String group)` | Mutator
    `protected void` | `setHost​(String host)` |
    `void` | `setLogFormat​(String logFormat)` | Mutator
    `protected void` | `setPath​(String path)` |
    `void` | `setTailing​(boolean tailing)` | Mutator
    `void` | `setTimestampFormat​(String timestampFormat)` | Mutator.
    `void` | `setUseCurrentThread​(boolean useCurrentThread)` | Sets whether the current Thread or a new Thread is created to perform the import, the default being false (new Thread created).
    `void` | `setWaitMillis​(long waitMillis)` | Mutator
    `void` | `shutdown()` | Close the reader.

    - ### Methods inherited from class org.apache.log4j.plugins.Receiver

      `doPost, getThreshold, isAsSevereAsThreshold, setThreshold`

    - ### Methods inherited from class org.apache.log4j.plugins.PluginSkeleton

      `addPropertyChangeListener, addPropertyChangeListener, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getLoggerRepository, getName, isActive, isEquivalent, removePropertyChangeListener, removePropertyChangeListener, setLoggerRepository, setName`

    - ### Methods inherited from class org.apache.log4j.spi.ComponentBase

      `getLogger, getNonFloodingLogger, resetErrorCount`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### MISSING_FILE_RETRY_MILLIS

          public static final int MISSING_FILE_RETRY_MILLIS

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### LogFilePatternReceiver

          public LogFilePatternReceiver()

  - ### Method Detail

    - #### getFileURL

          public String getFileURL()

      Accessor
      Returns:
        file URL

    - #### setFileURL

          public void setFileURL​(String fileURL)

      Mutator
      Parameters:
        `fileURL` -

    - #### setCustomLevelDefinitions

          public void setCustomLevelDefinitions​(String customLevelDefinitions)

      If the log file contains non-log4j level strings, they can be mapped to log4j levels using the format (android example): V=TRACE,D=DEBUG,I=INFO,W=WARN,E=ERROR,F=FATAL,S=OFF
      Parameters:
        `customLevelDefinitions` - the level definition string

    - #### getCustomLevelDefinitions

          public String getCustomLevelDefinitions()

    - #### isAppendNonMatches

          public boolean isAppendNonMatches()

      Accessor
      Returns:
        append non matches

    - #### setAppendNonMatches

          public void setAppendNonMatches​(boolean appendNonMatches)

      Mutator
      Parameters:
        `appendNonMatches` -

    - #### getFilterExpression

          public String getFilterExpression()

      Accessor
      Returns:
        filter expression

    - #### setFilterExpression

          public void setFilterExpression​(String filterExpression)

      Mutator
      Parameters:
        `filterExpression` -

    - #### isTailing

          public boolean isTailing()

      Accessor
      Returns:
        tailing

    - #### setTailing

          public void setTailing​(boolean tailing)

      Mutator
      Parameters:
        `tailing` -

    - #### isUseCurrentThread

          public final boolean isUseCurrentThread()

      When true, this property uses the current Thread to perform the import, otherwise when false (the default), a new Thread is created and started to manage the import.
      Returns:

    - #### setUseCurrentThread

          public final void setUseCurrentThread​(boolean useCurrentThread)

      Sets whether the current Thread or a new Thread is created to perform the import, the default being false (new Thread created).
      Parameters:
        `useCurrentThread` -

    - #### getLogFormat

          public String getLogFormat()

      Accessor
      Returns:
        log format

    - #### setLogFormat

          public void setLogFormat​(String logFormat)

      Mutator
      Parameters:
        `logFormat` - the format

    - #### setGroup

          public void setGroup​(String group)

      Mutator

    - #### getGroup

          public String getGroup()

      Accessor
      Returns:
        group

    - #### setTimestampFormat

          public void setTimestampFormat​(String timestampFormat)

      Mutator. Specify a pattern from `SimpleDateFormat`
      Parameters:
        `timestampFormat` -

    - #### getTimestampFormat

          public String getTimestampFormat()

      Accessor
      Returns:
        timestamp format

    - #### getWaitMillis

          public long getWaitMillis()

      Accessor
      Returns:
        millis between retrieves of content

    - #### setWaitMillis

          public void setWaitMillis​(long waitMillis)

      Mutator
      Parameters:
        `waitMillis` -

    - #### process

          protected void process​(BufferedReader bufferedReader)
                          throws IOException

      Read, parse and optionally tail the log file, converting entries into logging events.

      A runtimeException is thrown if the logFormat pattern is malformed.

      Parameters:
        `bufferedReader` -
      Throws:
        `IOException`

    - #### createPattern

          protected void createPattern()

    - #### setHost

          protected void setHost​(String host)

    - #### setPath

          protected void setPath​(String path)

    - #### getPath

          public String getPath()

    - #### initialize

          protected void initialize()

      Build the regular expression needed to parse log entries

    - #### shutdown

          public void shutdown()

      Close the reader.

    - #### activateOptions

          public void activateOptions()

      Read and process the log file.