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:

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:

  • Field Details

    • DEFAULT_DELAY_MILLIS

      private static final int DEFAULT_DELAY_MILLIS
      See Also:

    • RAF_READ_ONLY_MODE

      private static final String RAF_READ_ONLY_MODE
      See Also:

    • DEFAULT_CHARSET

      private static final Charset DEFAULT_CHARSET

    • inbuf

      private final byte[] inbuf
      Buffer on top of RandomAccessResourceBridge.

    • tailable

      private final Tailer.Tailable tailable
      The file which will be tailed.

    • charset

      private final Charset charset
      The character set that will be used to read the file.

    • delayDuration

      private final Duration delayDuration
      The amount of time to wait for the file to be updated.

    • tailAtEnd

      private final boolean tailAtEnd
      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 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

    • Tailer

      private Tailer(Tailer.Tailable tailable, Charset charset, TailerListener listener, Duration delayDuration, boolean end, boolean reOpen, int bufferSize)
      Creates a Tailer for the given file, with a specified buffer size.
      Parameters:
      tailable - the file to follow.
      charset - the Charset to be used for reading the file
      listener - the TailerListener to use.
      delayDuration - 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

  • 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

    • readLines

      private long readLines(Tailer.RandomAccessResourceBridge reader) throws IOException
      Reads new lines.
      Parameters:
      reader - The file to read
      Returns:
      The new position after the lines have been read
      Throws:
      IOException - if an I/O error occurs.

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