commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nia...@apache.org
Subject svn commit: r1033786 - /commons/proper/io/trunk/src/main/java/org/apache/commons/io/input/Tailer.java
Date Thu, 11 Nov 2010 00:37:37 GMT
Author: niallp
Date: Thu Nov 11 00:37:37 2010
New Revision: 1033786

URL: http://svn.apache.org/viewvc?rev=1033786&view=rev
Log:
Improve Tailer examples in JavaDocs

Modified:
    commons/proper/io/trunk/src/main/java/org/apache/commons/io/input/Tailer.java

Modified: commons/proper/io/trunk/src/main/java/org/apache/commons/io/input/Tailer.java
URL: http://svn.apache.org/viewvc/commons/proper/io/trunk/src/main/java/org/apache/commons/io/input/Tailer.java?rev=1033786&r1=1033785&r2=1033786&view=diff
==============================================================================
--- commons/proper/io/trunk/src/main/java/org/apache/commons/io/input/Tailer.java (original)
+++ commons/proper/io/trunk/src/main/java/org/apache/commons/io/input/Tailer.java Thu Nov
11 00:37:37 2010
@@ -27,29 +27,80 @@ import org.apache.commons.io.IOUtils;
 /**
  * Simple implementation of the unix "tail -f" functionality.
  * <p>
- * Example Usage:
+ * <h2>1. Create a TailerListener implementation</h3>
+ * <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>
- *      // Simplest invocation using static helper method:
- *      TailerListener listener = ...
+ *  public class MyTailerListener extends TailerListenerAdapter {
+ *      public void handle(String line) {
+ *          System.out.println(line);
+ *      }
+ *  }
+ * </pre>
+ * 
+ * <h2>2. Using a Tailer</h2>
+ *
+ * You can create and use a Tailer in one of three ways:
+ * <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>
+ *
+ * An example of each of these is shown below.
+ * 
+ * <h3>2.1 Using the static helper method</h3>
+ *
+ * <pre>
+ *      TailerListener listener = new MyTailerListener();
  *      Tailer tailer = Tailer.create(file, listener, delay);
+ * </pre>
  *      
- *      // Alternative method using executor:
- *      TailerListener listener = ...
+ * <h3>2.2 Use an Executor</h3>
+ * 
+ * <pre>
+ *      TailerListener listener = new MyTailerListener();
  *      Tailer tailer = new Tailer(file, listener, delay);
- *      Executor executor ...
+ *
+ *      // stupid executor impl. for demo purposes
+ *      Executor executor = new Executor() {
+ *          public void execute(Runnable command) {
+ *              command.run();
+ *           }
+ *      };
+ *
  *      executor.execute(tailer);
+ * </pre>
  *      
- *      // Alternative method if you want to handle the threading yourself:
- *      TailerListener listener = ...
+ *      
+ * <h3>2.3 Use 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();
- *      
- *      // Remember to stop the tailer when you have done with it:
+ * </pre>
+ *
+ * <h2>3. Stop Tailing</h3>
+ * <p>Remember to stop the tailer when you have done with it:</p>
+ * <pre>
  *      tailer.stop();
  * </pre>
  *
+ * @see TailerListener
+ * @see TailerListenerAdapter
  * @version $Id$
  * @since Commons IO 2.0
  */



Mime
View raw message