Package 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, use `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:
  - `Tailer.Builder`
  - `TailerListener`
  - `TailerListenerAdapter`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `Tailer.Builder`
  Builds a new `Tailer`.
  `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
  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

  Modifier and Type
  Method
  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 Details

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

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