Tailer

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * TODO remove once https://issues.apache.org/jira/browse/IO-444 is fixed
 */
package org.apache.commons.io.input;

import java.io.File;
import java.nio.charset.Charset;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;

/**
 * Simple implementation of the unix "tail -f" functionality.
 *
 * <h2>1. Create a TailerListener implementation</h2>
 * <p>
 * First you need to create a {@link TailerListener} implementation (
 * {@link TailerListenerAdapter} is provided for convenience so that you don't
 * have to implement every method).
 * </p>
 *
 * <p>
 * For example:
 * </p>
 *
 * <pre>
 * public class MyTailerListener extends TailerListenerAdapter {
 *     public void handle(String line) {
 *         System.out.println(line);
 *     }
 * }
 * </pre>
 *
 * <h2>2. Using a Tailer</h2>
 *
 * <p>
 * You can create and use a Tailer in one of three ways:
 * </p>
 * <ul>
 * <li>Using one of the static helper methods:
 * <ul>
 * <li>{@link Tailer#create(File, TailerListener)}</li>
 * <li>{@link Tailer#create(File, TailerListener, long)}</li>
 * <li>{@link Tailer#create(File, TailerListener, long, boolean)}</li>
 * </ul>
 * </li>
 * <li>Using an {@link java.util.concurrent.Executor}</li>
 * <li>Using an {@link Thread}</li>
 * </ul>
 *
 * <p>
 * An example of each of these is shown below.
 * </p>
 *
 * <h3>2.1 Using the static helper method</h3>
 *
 * <pre>
 * TailerListener listener = new MyTailerListener();
 * Tailer tailer = Tailer.create(file, listener, delay);
 * </pre>
 *
 * <h3>2.2 Using an Executor</h3>
 *
 * <pre>
 * 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);
 * </pre>
 *
 *
 * <h3>2.3 Using a Thread</h3>
 *
 * <pre>
 * TailerListener listener = new MyTailerListener();
 * Tailer tailer = new Tailer(file, listener, delay);
 * Thread thread = new Thread(tailer);
 * thread.setDaemon(true); // optional
 * thread.start();
 * </pre>
 *
 * <h2>3. Stopping a Tailer</h2>
 * <p>
 * Remember to stop the tailer when you have done with it:
 * </p>
 *
 * <pre>
 * tailer.stop();
 * </pre>
 *
 * <h2>4. Interrupting a Tailer</h2>
 * <p>
 * You can interrupt the thread a tailer is running on by calling
 * {@link Thread#interrupt()}.
 * </p>
 *
 * <pre>
 * thread.interrupt();
 * </pre>
 * <p>
 * If you interrupt a tailer, the tailer listener is called with the
 * {@link InterruptedException}.
 * </p>
 *
 * <p>
 * The file is read using the default charset; this can be overriden if
 * necessary
 * </p>
 *
 * @see TailerListener
 * @see TailerListenerAdapter
 * @version $Id$
 * @since 2.0
 * @since 2.5 Updated behavior and documentation for {@link Thread#interrupt()}
 */
public class Tailer implements Runnable {

    private static final int DEFAULT_BUFSIZE = 4096;

    // The default charset used for reading files
    private static final Charset DEFAULT_CHARSET = Charset.defaultCharset();

    private static final int DEFAULT_DELAY_MILLIS = 1000;

    /**
     * Creates and starts a Tailer for the given file.
     *
     * @param file
     *            the file to follow.
     * @param charset
     *            the character set to use for reading the file
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @param reOpen
     *            whether to close/reopen the file between chunks
     * @param bufSize
     *            buffer size.
     * @return The new tailer
     */
    public static Tailer create(final File file, final Charset charset, final TailerListener listener,
        final long delayMillis, final boolean end, final boolean reOpen, final int bufSize) {
        final Tailer tailer = new Tailer(file, charset, listener, delayMillis, end, reOpen, bufSize);
        final Thread thread = new Thread(tailer);
        thread.setDaemon(true);
        thread.start();
        return tailer;
    }

    /**
     * Creates and starts a Tailer for the given file, starting at the beginning
     * of the file with the default delay of 1.0s
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @return The new tailer
     */
    public static Tailer create(final File file, final TailerListener listener) {
        return Tailer.create(file, listener, Tailer.DEFAULT_DELAY_MILLIS, false);
    }

    /**
     * Creates and starts a Tailer for the given file, starting at the beginning
     * of the file
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @return The new tailer
     */
    public static Tailer create(final File file, final TailerListener listener, final long delayMillis) {
        return Tailer.create(file, listener, delayMillis, false);
    }

    /**
     * Creates and starts a Tailer for the given file with default buffer size.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @return The new tailer
     */
    public static Tailer create(final File file, final TailerListener listener, final long delayMillis,
        final boolean end) {
        return Tailer.create(file, listener, delayMillis, end, Tailer.DEFAULT_BUFSIZE);
    }

    /**
     * Creates and starts a Tailer for the given file with default buffer size.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @param reOpen
     *            whether to close/reopen the file between chunks
     * @return The new tailer
     */
    public static Tailer create(final File file, final TailerListener listener, final long delayMillis,
        final boolean end, final boolean reOpen) {
        return Tailer.create(file, listener, delayMillis, end, reOpen, Tailer.DEFAULT_BUFSIZE);
    }

    /**
     * Creates and starts a Tailer for the given file.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @param reOpen
     *            whether to close/reopen the file between chunks
     * @param bufSize
     *            buffer size.
     * @return The new tailer
     */
    public static Tailer create(final File file, final TailerListener listener, final long delayMillis,
        final boolean end, final boolean reOpen, final int bufSize) {
        return Tailer.create(file, Tailer.DEFAULT_CHARSET, listener, delayMillis, end, reOpen, bufSize);
    }

    /**
     * Creates and starts a Tailer for the given file.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @param bufSize
     *            buffer size.
     * @return The new tailer
     */
    public static Tailer create(final File file, final TailerListener listener, final long delayMillis,
        final boolean end, final int bufSize) {
        return Tailer.create(file, listener, delayMillis, end, false, bufSize);
    }

    /**
     * The amount of time to wait for the file to be updated.
     */
    private final long delayMillis;

    private final ScheduledExecutorService executor = Executors.newScheduledThreadPool(1);

    /**
     * The file which will be tailed.
     */
    private final File file;

    private final TailerListener listener;

    private final CountDownLatch runTrigger = new CountDownLatch(1);

    private final TailerRun scheduled;

    /**
     * Creates a Tailer for the given file, with a specified buffer size.
     *
     * @param file
     *            the file to follow.
     * @param cset
     *            the Charset to be used for reading the file
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @param reOpen
     *            if true, close and reopen the file between reading chunks
     * @param bufSize
     *            Buffer size
     */
    public Tailer(final File file, final Charset cset, final TailerListener listener, final long delayMillis,
        final boolean end, final boolean reOpen, final int bufSize) {
        this.file = file;
        this.delayMillis = delayMillis;
        this.listener = listener;
        listener.init(this);
        this.scheduled = new TailerRun(file, cset, listener, end, reOpen, bufSize);
    }

    /**
     * Creates a Tailer for the given file, starting from the beginning, with
     * the default delay of 1.0s.
     *
     * @param file
     *            The file to follow.
     * @param listener
     *            the TailerListener to use.
     */
    public Tailer(final File file, final TailerListener listener) {
        this(file, listener, Tailer.DEFAULT_DELAY_MILLIS);
    }

    /**
     * Creates a Tailer for the given file, starting from the beginning.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     */
    public Tailer(final File file, final TailerListener listener, final long delayMillis) {
        this(file, listener, delayMillis, false);
    }

    /**
     * Creates a Tailer for the given file, with a delay other than the default
     * 1.0s.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     */
    public Tailer(final File file, final TailerListener listener, final long delayMillis, final boolean end) {
        this(file, listener, delayMillis, end, Tailer.DEFAULT_BUFSIZE);
    }

    /**
     * Creates a Tailer for the given file, with a delay other than the default
     * 1.0s.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @param reOpen
     *            if true, close and reopen the file between reading chunks
     */
    public Tailer(final File file, final TailerListener listener, final long delayMillis, final boolean end,
        final boolean reOpen) {
        this(file, listener, delayMillis, end, reOpen, Tailer.DEFAULT_BUFSIZE);
    }

    /**
     * Creates a Tailer for the given file, with a specified buffer size.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @param reOpen
     *            if true, close and reopen the file between reading chunks
     * @param bufSize
     *            Buffer size
     */
    public Tailer(final File file, final TailerListener listener, final long delayMillis, final boolean end,
        final boolean reOpen, final int bufSize) {
        this(file, Tailer.DEFAULT_CHARSET, listener, delayMillis, end, reOpen, bufSize);
    }

    /**
     * Creates a Tailer for the given file, with a specified buffer size.
     *
     * @param file
     *            the file to follow.
     * @param listener
     *            the TailerListener to use.
     * @param delayMillis
     *            the delay between checks of the file for new content in
     *            milliseconds.
     * @param end
     *            Set to true to tail from the end of the file, false to tail
     *            from the beginning of the file.
     * @param bufSize
     *            Buffer size
     */
    public Tailer(final File file, final TailerListener listener, final long delayMillis, final boolean end,
        final int bufSize) {
        this(file, listener, delayMillis, end, false, bufSize);
    }

    /**
     * Return the delay in milliseconds.
     *
     * @return the delay in milliseconds.
     */
    public long getDelay() {
        return this.delayMillis;
    }

    /**
     * Return the file.
     *
     * @return the file
     */
    public File getFile() {
        return this.file;
    }

    /**
     * Gets whether to keep on running.
     *
     * @return whether to keep on running.
     * @since 2.5
     */
    protected boolean getRun() {
        return this.runTrigger.getCount() > 0;
    }

    /**
     * Follows changes in the file, calling the TailerListener's handle method
     * for each new line.
     */
    @Override
    public void run() {
        final ScheduledFuture<?> future = this.executor.scheduleWithFixedDelay(this.scheduled, 0, this.delayMillis,
                TimeUnit.MILLISECONDS);
        try {
            this.runTrigger.await();
        } catch (final InterruptedException e) {
            this.listener.handle(e);
        } finally {
            future.cancel(true); // stop the periodic reading
            this.scheduled.cleanup();
            this.executor.shutdownNow();
            this.listener.destroy();
        }
    }

    /**
     * Allows the tailer to complete its current loop and return.
     */
    public void stop() {
        this.runTrigger.countDown();
    }

    public void waitUntilStarted() {
        while (!this.scheduled.hasStartedOnce() || this.scheduled.hasFinished()) {
            try {
                // wait for a miniscule amount of time
                Thread.sleep(Math.max(this.getDelay() / 100, 1));
            } catch (final InterruptedException e) {
                // do nothing
            }
        }
    }

}