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

Since:
  2.0, 2.5 Updated behavior and documentation for `Thread.interrupt()`
Version:
  $Id$
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

All Methods Static Methods Instance Methods Concrete Methods
`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.