org.apache.commons.io.input

Class Tailer

java.lang.Object

org.apache.commons.io.input.Tailer

All Implemented Interfaces:

java.lang.AutoCloseable, java.lang.Runnable

public class Tailer
extends java.lang.Object
implements java.lang.Runnable, java.lang.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.
private static class	Tailer.RandomAccessFileBridge Bridges random access to a RandomAccessFile.
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.
private static class	Tailer.TailablePath A tailable for a file Path.

Field Summary

Fields

Modifier and Type	Field and Description
private java.nio.charset.Charset	charset The character set that will be used to read the file.
private static java.nio.charset.Charset	DEFAULT_CHARSET
private static int	DEFAULT_DELAY_MILLIS
private java.time.Duration	delayDuration The amount of time to wait for the file to be updated.
private byte[]	inbuf Buffer on top of RandomAccessResourceBridge.
private TailerListener	listener The listener to notify of events when tailing.
private static java.lang.String	RAF_READ_ONLY_MODE
private boolean	reOpen Whether to close and reopen the file whilst waiting for more input.
private boolean	run The tailer will run as long as this value is true.
private Tailer.Tailable	tailable The file which will be tailed.
private boolean	tailAtEnd Whether to tail from the end or start of file

Constructor Summary

Constructors

Modifier	Constructor and Description
	Tailer(java.io.File file, java.nio.charset.Charset charset, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufSize) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
	Tailer(java.io.File file, TailerListener listener) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
	Tailer(java.io.File file, TailerListener listener, long delayMillis) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
	Tailer(java.io.File file, TailerListener listener, long delayMillis, boolean end) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
	Tailer(java.io.File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
	Tailer(java.io.File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufferSize) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
	Tailer(java.io.File file, TailerListener listener, long delayMillis, boolean end, int bufferSize) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
private	Tailer(Tailer.Tailable tailable, java.nio.charset.Charset charset, TailerListener listener, java.time.Duration delayDuration, boolean end, boolean reOpen, int bufferSize) Creates a Tailer for the given file, with a specified buffer size.

Method Summary

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(java.io.File file, java.nio.charset.Charset charset, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufferSize) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
static Tailer	create(java.io.File file, TailerListener listener) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
static Tailer	create(java.io.File file, TailerListener listener, long delayMillis) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
static Tailer	create(java.io.File file, TailerListener listener, long delayMillis, boolean end) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
static Tailer	create(java.io.File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
static Tailer	create(java.io.File file, TailerListener listener, long delayMillis, boolean end, boolean reOpen, int bufferSize) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
static Tailer	create(java.io.File file, TailerListener listener, long delayMillis, boolean end, int bufferSize) Deprecated. Use builder(), Tailer.Builder, and Tailer.Builder.get().
long	getDelay() Deprecated. Use getDelayDuration().
java.time.Duration	getDelayDuration() Gets the delay Duration.
java.io.File	getFile() Gets the file.
protected boolean	getRun() Gets whether to keep on running.
Tailer.Tailable	getTailable() Gets the Tailable.
private long	readLines(Tailer.RandomAccessResourceBridge reader) Reads new lines.
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

Field Detail

DEFAULT_DELAY_MILLIS

private static final int DEFAULT_DELAY_MILLIS

See Also:

Constant Field Values

RAF_READ_ONLY_MODE

private static final java.lang.String RAF_READ_ONLY_MODE

See Also:

Constant Field Values

DEFAULT_CHARSET

private static final java.nio.charset.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 java.nio.charset.Charset charset

The character set that will be used to read the file.

delayDuration

private final java.time.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 Detail

Tailer

@Deprecated
public Tailer(java.io.File file,
                          java.nio.charset.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(java.io.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(java.io.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(java.io.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(java.io.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(java.io.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(java.io.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,
               java.nio.charset.Charset charset,
               TailerListener listener,
               java.time.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 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(java.io.File file,
                                        java.nio.charset.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(java.io.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(java.io.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(java.io.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(java.io.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(java.io.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(java.io.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 java.lang.AutoCloseable

getDelay

@Deprecated
public long getDelay()

Deprecated. Use getDelayDuration().

Gets the delay in milliseconds.

Returns:

the delay in milliseconds.

getDelayDuration

public java.time.Duration getDelayDuration()

Gets the delay Duration.

Returns:

the delay Duration.

Since:

2.12.0

getFile

public java.io.File getFile()

Gets the file.

Returns:

the file

Throws:

java.lang.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 java.io.IOException

Reads new lines.

Parameters:

reader - The file to read

Returns:

The new position after the lines have been read

Throws:

java.io.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 java.lang.Runnable

stop

@Deprecated
public void stop()

Deprecated. Use close().

Requests the tailer to complete its current loop and return.