Tailer (Apache Commons IO 2.5 API)

org.apache.commons.io.input

## Class Tailer

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

- All Implemented Interfaces:
    Runnable

      public class Tailer
      extends Object
      implements 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`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Tailer(File file, 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(File file, TailerListener listener)` Creates a Tailer for the given file, starting from the beginning, with the default delay of 1.0s.
    `Tailer(File file, TailerListener listener, long delayMillis)` Creates a Tailer for the given file, starting from the beginning.
    `Tailer(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(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(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(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(File file, Charset charset, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufSize)` Creates and starts a Tailer for the given file.
    `static Tailer` | `create(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(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(File file, TailerListener listener, long delayMillis, boolean end)` Creates and starts a Tailer for the given file with default buffer size.
    `static Tailer` | `create(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(File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufSize)` Creates and starts a Tailer for the given file.
    `static Tailer` | `create(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.
    `File` | `getFile()` Return the file.
    `protected boolean` | `getRun()` Gets whether to keep on running.
    `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.

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

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

- - ### Constructor Detail

    - #### Tailer

          public Tailer(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(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(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(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(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(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(File file,
                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(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(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(File file,
                      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(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(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(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(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 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 `Runnable`

    - #### stop

          public void stop()

      Allows the tailer to complete its current loop and return.

Copyright © 2002–2016 The Apache Software Foundation. All rights reserved.