svn commit: r1156883 - /incubator/flume/branches/flume-728/flume-ng-core/src/main/java/org/apache/flume/lifecycle/LifecycleAware.java

[es...@apache.org]

Author: esammer
Date: Fri Aug 12 00:47:06 2011
New Revision: 1156883

URL: http://svn.apache.org/viewvc?rev=1156883&view=rev
Log:
- Added javadoc.

Modified:
    incubator/flume/branches/flume-728/flume-ng-core/src/main/java/org/apache/flume/lifecycle/LifecycleAware.java

Modified: incubator/flume/branches/flume-728/flume-ng-core/src/main/java/org/apache/flume/lifecycle/LifecycleAware.java
URL: http://svn.apache.org/viewvc/incubator/flume/branches/flume-728/flume-ng-core/src/main/java/org/apache/flume/lifecycle/LifecycleAware.java?rev=1156883&r1=1156882&r2=1156883&view=diff
==============================================================================
--- incubator/flume/branches/flume-728/flume-ng-core/src/main/java/org/apache/flume/lifecycle/LifecycleAware.java (original)
+++ incubator/flume/branches/flume-728/flume-ng-core/src/main/java/org/apache/flume/lifecycle/LifecycleAware.java Fri Aug 12 00:47:06 2011
@@ -2,14 +2,105 @@ package org.apache.flume.lifecycle;
 
 import org.apache.flume.core.Context;
 
+/**
+ * <p>
+ * An interface implemented by any class that has a defined, stateful,
+ * lifecycle.
+ * </p>
+ * <p>
+ * Implementations of {@link LifecycleAware} conform to a standard method of
+ * starting, stopping, and reporting their current state. Additionally, this
+ * interface creates a standard method of communicating failure to perform a
+ * lifecycle operation to the caller (i.e. via {@link LifecycleException}). It
+ * is never considered valid to call {@link #start(Context)} or
+ * {@link #stop(Context)} more than once or to call them in the wrong order.
+ * While this is not strictly enforced, it may be in the future.
+ * </p>
+ * <p>
+ * Example services may include Flume nodes and the master, but also lower level
+ * components that can be controlled in a similar manner.
+ * </p>
+ * <p>
+ * Example usage
+ * </p>
+ * <code>
+ *  public class MyService implements LifecycleAware {
+ * 
+ *    private LifecycleState lifecycleState;
+ * 
+ *    public MyService() {
+ *      lifecycleState = LifecycleState.IDLE;
+ *    }
+ * 
+ *    @Override
+ *    public void start(Context context) throws LifecycleException,
+ *      InterruptedException {
+ * 
+ *      ...your code does something.
+ * 
+ *      lifecycleState = LifecycleState.START;
+ *    }
+ * 
+ *    @Override
+ *    public void stop(Context context) throws LifecycleException,
+ *      InterruptedException {
+ * 
+ *      try {
+ *        ...you stop services here.
+ *      } catch (SomethingException) {
+ *        lifecycleState = LifecycleState.ERROR;
+ *      }
+ * 
+ *      lifecycleState = LifecycleState.STOP;
+ *    }
+ * 
+ *    @Override
+ *    public LifecycleState getLifecycleState() {
+ *      return lifecycleState;
+ *    }
+ * 
+ *  }
+ * </code>
+ */
 public interface LifecycleAware {
 
+  /**
+   * <p>
+   * Starts a service or component.
+   * </p>
+   * <p>
+   * Implementations should determine the result of any start logic and effect
+   * the return value of {@link #getLifecycleState()} accordingly.
+   * </p>
+   * 
+   * @param context
+   * @throws LifecycleException
+   * @throws InterruptedException
+   */
   public void start(Context context) throws LifecycleException,
       InterruptedException;
 
+  /**
+   * <p>
+   * Stops a service or component.
+   * </p>
+   * <p>
+   * Implementations should determine the result of any stop logic and effect
+   * the return value of {@link #getLifecycleState()} accordingly.
+   * </p>
+   * 
+   * @param context
+   * @throws LifecycleException
+   * @throws InterruptedException
+   */
   public void stop(Context context) throws LifecycleException,
       InterruptedException;
 
+  /**
+   * <p>
+   * Return the current state of the service or component.
+   * </p>
+   */
   public LifecycleState getLifecycleState();
 
 }