org.apache.commons.io.input

## Class Tailer

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

- All Implemented Interfaces:
    AutoCloseable, Runnable

      public class Tailer
      extends Object
      implements Runnable, AutoCloseable

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

  To build an instance, see `Tailer.Builder`.

  ## 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 a `Tailer.Builder`
  - Using an `Executor`
  - Using a `Thread`

  An example of each is shown below.

  ### 2.1 Using a Builder

       TailerListener listener = new MyTailerListener();
       Tailer tailer = Tailer.builder()
         .setFile(file)
         .setTailerListener(listener)
         .setDelayDuration(delay)
         .get();

  ### 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 overridden if necessary.

  Since:
    2.0, 2.5 Updated behavior and documentation for `Thread.interrupt()`., 2.12.0 Add `Tailer.Tailable` and `Tailer.RandomAccessResourceBridge` interfaces to tail of files accessed using alternative libraries such as jCIFS or Apache Commons VFS.
  See Also:
    `TailerListener`, `TailerListenerAdapter`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Tailer.Builder` Builds a `Tailer` with default values.
    `static interface` | `Tailer.RandomAccessResourceBridge` Bridges access to a resource for random access, normally a file.
    `static interface` | `Tailer.Tailable` A tailable resource like a file.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Tailer(File file, Charset charset, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufSize)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `Tailer(File file, TailerListener listener)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `Tailer(File file, TailerListener listener, long delayMillis)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `Tailer(File file, TailerListener listener, long delayMillis, boolean end)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `Tailer(File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `Tailer(File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufferSize)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `Tailer(File file, TailerListener listener, long delayMillis, boolean end, int bufferSize)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Tailer.Builder` | `builder()` Constructs a new `Tailer.Builder`.
    `void` | `close()` Requests the tailer to complete its current loop and return.
    `static Tailer` | `create(File file, Charset charset, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufferSize)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `static Tailer` | `create(File file, TailerListener listener)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `static Tailer` | `create(File file, TailerListener listener, long delayMillis)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `static Tailer` | `create(File file, TailerListener listener, long delayMillis, boolean end)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `static Tailer` | `create(File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `static Tailer` | `create(File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufferSize)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `static Tailer` | `create(File file, TailerListener listener, long delayMillis, boolean end, int bufferSize)` Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
    `long` | `getDelay()` Deprecated. Use `getDelayDuration()`.
    `Duration` | `getDelayDuration()` Gets the delay Duration.
    `File` | `getFile()` Gets the file.
    `protected boolean` | `getRun()` Gets whether to keep on running.
    `Tailer.Tailable` | `getTailable()` Gets the Tailable.
    `void` | `run()` Follows changes in the file, calling `TailerListener.handle(String)` with each new line.
    `void` | `stop()` Deprecated. Use `close()`.

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

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

- - ### Constructor Detail

    - #### Tailer

          @Deprecated
          public Tailer(File file,
                                    Charset charset,
                                    TailerListener listener,
                                    long delayMillis,
                                    boolean end,
                                    boolean reOpen,
                                    int bufSize)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      Creates a Tailer for the given file, with a specified buffer size.
      Parameters:
        `file` - the file to follow.
        `charset` - 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

    - #### Tailer

          @Deprecated
          public Tailer(File file,
                                    TailerListener listener)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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

          @Deprecated
          public Tailer(File file,
                                    TailerListener listener,
                                    long delayMillis)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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

          @Deprecated
          public Tailer(File file,
                                    TailerListener listener,
                                    long delayMillis,
                                    boolean end)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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

          @Deprecated
          public Tailer(File file,
                                    TailerListener listener,
                                    long delayMillis,
                                    boolean end,
                                    boolean reOpen)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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

          @Deprecated
          public Tailer(File file,
                                    TailerListener listener,
                                    long delayMillis,
                                    boolean end,
                                    boolean reOpen,
                                    int bufferSize)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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
        `bufferSize` - Buffer size

    - #### Tailer

          @Deprecated
          public Tailer(File file,
                                    TailerListener listener,
                                    long delayMillis,
                                    boolean end,
                                    int bufferSize)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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.
        `bufferSize` - Buffer size

  - ### Method Detail

    - #### builder

          public static Tailer.Builder builder()

      Constructs a new `Tailer.Builder`.
      Returns:
        Creates a new `Tailer.Builder`.
      Since:
        2.12.0

    - #### create

          @Deprecated
          public static Tailer create(File file,
                                                  Charset charset,
                                                  TailerListener listener,
                                                  long delayMillis,
                                                  boolean end,
                                                  boolean reOpen,
                                                  int bufferSize)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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.
        `bufferSize` - buffer size.
      Returns:
        The new tailer.

    - #### create

          @Deprecated
          public static Tailer create(File file,
                                                  TailerListener listener)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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.

    - #### create

          @Deprecated
          public static Tailer create(File file,
                                                  TailerListener listener,
                                                  long delayMillis)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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

          @Deprecated
          public static Tailer create(File file,
                                                  TailerListener listener,
                                                  long delayMillis,
                                                  boolean end)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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

          @Deprecated
          public static Tailer create(File file,
                                                  TailerListener listener,
                                                  long delayMillis,
                                                  boolean end,
                                                  boolean reOpen)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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

          @Deprecated
          public static Tailer create(File file,
                                                  TailerListener listener,
                                                  long delayMillis,
                                                  boolean end,
                                                  boolean reOpen,
                                                  int bufferSize)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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.
        `bufferSize` - buffer size.
      Returns:
        The new tailer.

    - #### create

          @Deprecated
          public static Tailer create(File file,
                                                  TailerListener listener,
                                                  long delayMillis,
                                                  boolean end,
                                                  int bufferSize)

      Deprecated. Use `builder()`, `Tailer.Builder`, and `Tailer.Builder.get()`.
      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.
        `bufferSize` - buffer size.
      Returns:
        The new tailer.

    - #### close

          public void close()

      Requests the tailer to complete its current loop and return.
      Specified by:
        `close` in interface `AutoCloseable`

    - #### getDelay

          @Deprecated
          public long getDelay()

      Deprecated. Use `getDelayDuration()`.
      Gets the delay in milliseconds.
      Returns:
        the delay in milliseconds.

    - #### getDelayDuration

          public Duration getDelayDuration()

      Gets the delay Duration.
      Returns:
        the delay Duration.
      Since:
        2.12.0

    - #### getFile

          public File getFile()

      Gets the file.
      Returns:
        the file
      Throws:
        `IllegalStateException` - if constructed using a user provided `Tailer.Tailable` implementation

    - #### getRun

          protected boolean getRun()

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

    - #### getTailable

          public Tailer.Tailable getTailable()

      Gets the Tailable.
      Returns:
        the Tailable
      Since:
        2.12.0

    - #### run

          public void run()

      Follows changes in the file, calling `TailerListener.handle(String)` with each new line.
      Specified by:
        `run` in interface `Runnable`

    - #### stop

          @Deprecated
          public void stop()

      Deprecated. Use `close()`.
      Requests the tailer to complete its current loop and return.

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