Tailer (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io.input

## Class Tailer

- java.lang.Object
- - org.apache.commons.io.input.Tailer

- All Implemented Interfaces:
    java.lang.Runnable

      public class Tailer
      extends java.lang.Object
      implements java.lang.Runnable

  Simple implementation of the unix "tail -f" functionality.

  ## 1. Create a TailerListener implementation

  First you need to create a `TailerListener` implementation (`TailerListenerAdapter` is provided for convenience so that you don't have to implement every method).

  For example:

        public class MyTailerListener extends TailerListenerAdapter {
            public void handle(String line) {
                System.out.println(line);
            }
        }

  ## 2. Using a Tailer

  You can create and use a Tailer in one of three ways:

  - Using one of the static helper methods:
    - `create(File, TailerListener)`
    - `create(File, TailerListener, long)`
    - `create(File, TailerListener, long, boolean)`
  - Using an `Executor`
  - Using an `Thread`

  An example of each of these is shown below.

  ### 2.1 Using the static helper method

            TailerListener listener = new MyTailerListener();
            Tailer tailer = Tailer.create(file, listener, delay);

  ### 2.2 Using an Executor

            TailerListener listener = new MyTailerListener();
            Tailer tailer = new Tailer(file, listener, delay);

            // stupid executor impl. for demo purposes
            Executor executor = new Executor() {
                public void execute(Runnable command) {
                    command.run();
                 }
            };

            executor.execute(tailer);

  ### 2.3 Using a Thread

            TailerListener listener = new MyTailerListener();
            Tailer tailer = new Tailer(file, listener, delay);
            Thread thread = new Thread(tailer);
            thread.setDaemon(true); // optional
            thread.start();

  ## 3. Stopping a Tailer

  Remember to stop the tailer when you have done with it:

            tailer.stop();

  ## 4. Interrupting a Tailer

  You can interrupt the thread a tailer is running on by calling `Thread.interrupt()`.

            thread.interrupt();

  If you interrupt a tailer, the tailer listener is called with the `InterruptedException`.

  The file is read using the default charset; this can be overriden if necessary

  Since:
    2.0, 2.5 Updated behavior and documentation for `Thread.interrupt()`
  Version:
    $Id: Tailer.java 1714076 2015-11-12 16:06:41Z krosenvold $
  See Also:
    `TailerListener`, `TailerListenerAdapter`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private java.nio.charset.Charset` | `cset` The character set that will be used to read the file.
    `private static int` | `DEFAULT_BUFSIZE`
    `private static java.nio.charset.Charset` | `DEFAULT_CHARSET`
    `private static int` | `DEFAULT_DELAY_MILLIS`
    `private long` | `delayMillis` The amount of time to wait for the file to be updated.
    `private boolean` | `end` Whether to tail from the end or start of file
    `private java.io.File` | `file` The file which will be tailed.
    `private byte[]` | `inbuf` Buffer on top of RandomAccessFile.
    `private TailerListener` | `listener` The listener to notify of events when tailing.
    `private static java.lang.String` | `RAF_MODE`
    `private boolean` | `reOpen` Whether to close and reopen the file whilst waiting for more input.
    `private boolean` | `run` The tailer will run as long as this value is true.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Tailer(java.io.File file, java.nio.charset.Charset cset, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufSize)` Creates a Tailer for the given file, with a specified buffer size.
    `Tailer(java.io.File file, TailerListener listener)` Creates a Tailer for the given file, starting from the beginning, with the default delay of 1.0s.
    `Tailer(java.io.File file, TailerListener listener, long delayMillis)` Creates a Tailer for the given file, starting from the beginning.
    `Tailer(java.io.File file, TailerListener listener, long delayMillis, boolean end)` Creates a Tailer for the given file, with a delay other than the default 1.0s.
    `Tailer(java.io.File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen)` Creates a Tailer for the given file, with a delay other than the default 1.0s.
    `Tailer(java.io.File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufSize)` Creates a Tailer for the given file, with a specified buffer size.
    `Tailer(java.io.File file, TailerListener listener, long delayMillis, boolean end, int bufSize)` Creates a Tailer for the given file, with a specified buffer size.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Tailer` | `create(java.io.File file, java.nio.charset.Charset charset, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufSize)` Creates and starts a Tailer for the given file.
    `static Tailer` | `create(java.io.File file, TailerListener listener)` Creates and starts a Tailer for the given file, starting at the beginning of the file with the default delay of 1.0s
    `static Tailer` | `create(java.io.File file, TailerListener listener, long delayMillis)` Creates and starts a Tailer for the given file, starting at the beginning of the file
    `static Tailer` | `create(java.io.File file, TailerListener listener, long delayMillis, boolean end)` Creates and starts a Tailer for the given file with default buffer size.
    `static Tailer` | `create(java.io.File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen)` Creates and starts a Tailer for the given file with default buffer size.
    `static Tailer` | `create(java.io.File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufSize)` Creates and starts a Tailer for the given file.
    `static Tailer` | `create(java.io.File file, TailerListener listener, long delayMillis, boolean end, int bufSize)` Creates and starts a Tailer for the given file.
    `long` | `getDelay()` Return the delay in milliseconds.
    `java.io.File` | `getFile()` Return the file.
    `protected boolean` | `getRun()` Gets whether to keep on running.
    `private long` | `readLines(java.io.RandomAccessFile reader)` Read new lines.
    `void` | `run()` Follows changes in the file, calling the TailerListener's handle method for each new line.
    `void` | `stop()` Allows the tailer to complete its current loop and return.
    `private void` | `stop(java.lang.Exception e)` Stops the tailer with an exception

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

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

- - ### Field Detail

    - #### DEFAULT_DELAY_MILLIS

          private static final int DEFAULT_DELAY_MILLIS

      See Also:
        Constant Field Values

    - #### RAF_MODE

          private static final java.lang.String RAF_MODE

      See Also:
        Constant Field Values

    - #### DEFAULT_BUFSIZE

          private static final int DEFAULT_BUFSIZE

      See Also:
        Constant Field Values

    - #### DEFAULT_CHARSET

          private static final java.nio.charset.Charset DEFAULT_CHARSET

    - #### inbuf

          private final byte[] inbuf

      Buffer on top of RandomAccessFile.

    - #### file

          private final java.io.File file

      The file which will be tailed.

    - #### cset

          private final java.nio.charset.Charset cset

      The character set that will be used to read the file.

    - #### delayMillis

          private final long delayMillis

      The amount of time to wait for the file to be updated.

    - #### end

          private final boolean end

      Whether to tail from the end or start of file

    - #### listener

          private final TailerListener listener

      The listener to notify of events when tailing.

    - #### reOpen

          private final boolean reOpen

      Whether to close and reopen the file whilst waiting for more input.

    - #### run

          private volatile boolean run

      The tailer will run as long as this value is true.

  - ### Constructor Detail

    - #### Tailer

          public Tailer(java.io.File file,
                TailerListener listener)

      Creates a Tailer for the given file, starting from the beginning, with the default delay of 1.0s.
      Parameters:
        `file` - The file to follow.
        `listener` - the TailerListener to use.

    - #### Tailer

          public Tailer(java.io.File file,
                TailerListener listener,
                long delayMillis)

      Creates a Tailer for the given file, starting from the beginning.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.

    - #### Tailer

          public Tailer(java.io.File file,
                TailerListener listener,
                long delayMillis,
                boolean end)

      Creates a Tailer for the given file, with a delay other than the default 1.0s.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.

    - #### Tailer

          public Tailer(java.io.File file,
                TailerListener listener,
                long delayMillis,
                boolean end,
                boolean reOpen)

      Creates a Tailer for the given file, with a delay other than the default 1.0s.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
        `reOpen` - if true, close and reopen the file between reading chunks

    - #### Tailer

          public Tailer(java.io.File file,
                TailerListener listener,
                long delayMillis,
                boolean end,
                int bufSize)

      Creates a Tailer for the given file, with a specified buffer size.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
        `bufSize` - Buffer size

    - #### Tailer

          public Tailer(java.io.File file,
                TailerListener listener,
                long delayMillis,
                boolean end,
                boolean reOpen,
                int bufSize)

      Creates a Tailer for the given file, with a specified buffer size.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
        `reOpen` - if true, close and reopen the file between reading chunks
        `bufSize` - Buffer size

    - #### Tailer

          public Tailer(java.io.File file,
                java.nio.charset.Charset cset,
                TailerListener listener,
                long delayMillis,
                boolean end,
                boolean reOpen,
                int bufSize)

      Creates a Tailer for the given file, with a specified buffer size.
      Parameters:
        `file` - the file to follow.
        `cset` - the Charset to be used for reading the file
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
        `reOpen` - if true, close and reopen the file between reading chunks
        `bufSize` - Buffer size

  - ### Method Detail

    - #### create

          public static Tailer create(java.io.File file,
                      TailerListener listener,
                      long delayMillis,
                      boolean end,
                      int bufSize)

      Creates and starts a Tailer for the given file.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
        `bufSize` - buffer size.
      Returns:
        The new tailer

    - #### create

          public static Tailer create(java.io.File file,
                      TailerListener listener,
                      long delayMillis,
                      boolean end,
                      boolean reOpen,
                      int bufSize)

      Creates and starts a Tailer for the given file.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
        `reOpen` - whether to close/reopen the file between chunks
        `bufSize` - buffer size.
      Returns:
        The new tailer

    - #### create

          public static Tailer create(java.io.File file,
                      java.nio.charset.Charset charset,
                      TailerListener listener,
                      long delayMillis,
                      boolean end,
                      boolean reOpen,
                      int bufSize)

      Creates and starts a Tailer for the given file.
      Parameters:
        `file` - the file to follow.
        `charset` - the character set to use for reading the file
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
        `reOpen` - whether to close/reopen the file between chunks
        `bufSize` - buffer size.
      Returns:
        The new tailer

    - #### create

          public static Tailer create(java.io.File file,
                      TailerListener listener,
                      long delayMillis,
                      boolean end)

      Creates and starts a Tailer for the given file with default buffer size.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
      Returns:
        The new tailer

    - #### create

          public static Tailer create(java.io.File file,
                      TailerListener listener,
                      long delayMillis,
                      boolean end,
                      boolean reOpen)

      Creates and starts a Tailer for the given file with default buffer size.
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
        `end` - Set to true to tail from the end of the file, false to tail from the beginning of the file.
        `reOpen` - whether to close/reopen the file between chunks
      Returns:
        The new tailer

    - #### create

          public static Tailer create(java.io.File file,
                      TailerListener listener,
                      long delayMillis)

      Creates and starts a Tailer for the given file, starting at the beginning of the file
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
        `delayMillis` - the delay between checks of the file for new content in milliseconds.
      Returns:
        The new tailer

    - #### create

          public static Tailer create(java.io.File file,
                      TailerListener listener)

      Creates and starts a Tailer for the given file, starting at the beginning of the file with the default delay of 1.0s
      Parameters:
        `file` - the file to follow.
        `listener` - the TailerListener to use.
      Returns:
        The new tailer

    - #### getFile

          public java.io.File getFile()

      Return the file.
      Returns:
        the file

    - #### getRun

          protected boolean getRun()

      Gets whether to keep on running.
      Returns:
        whether to keep on running.
      Since:
        2.5

    - #### getDelay

          public long getDelay()

      Return the delay in milliseconds.
      Returns:
        the delay in milliseconds.

    - #### run

          public void run()

      Follows changes in the file, calling the TailerListener's handle method for each new line.
      Specified by:
        `run` in interface `java.lang.Runnable`

    - #### stop

          private void stop(java.lang.Exception e)

      Stops the tailer with an exception
      Parameters:
        `e` - The exception to send to listener

    - #### stop

          public void stop()

      Allows the tailer to complete its current loop and return.

    - #### readLines

          private long readLines(java.io.RandomAccessFile reader)
                          throws java.io.IOException

      Read new lines.
      Parameters:
        `reader` - The file to read
      Returns:
        The new position after the lines have been read
      Throws:
        `java.io.IOException` - if an I/O error occurs.

Copyright (c) 2002-2016 Apache Software Foundation