Issue 9: better javadoc

git-svn-id: http://jclouds.googlecode.com/svn/trunk@883 3d8758e0-26b5-11de-8745-db77d3ebf521

core/src/main/java/org/jclouds/command/pool/FutureCommandConnectionPoolClient.java

@@ -40,8 +40,8 @@ import com.google.inject.Inject;
  * 
  * @author Adrian Cole
  */
-public class FutureCommandConnectionPoolClient<C, O extends FutureCommand<?, ?, ?>>
+public class FutureCommandConnectionPoolClient<C, O extends FutureCommand<?, ?, ?>> extends
-	extends BaseLifeCycle implements FutureCommandClient<O> {
+         BaseLifeCycle implements FutureCommandClient<O> {
    private final FutureCommandConnectionPool<C, O> futureCommandConnectionPool;
    private final BlockingQueue<O> commandQueue;
 
@@ -54,20 +54,27 @@ public class FutureCommandConnectionPoolClient<C, O extends FutureCommand<?, ?,
       this.commandQueue = commandQueue;
    }
 
+   /**
+    * {@inheritDoc}
+    * <p/>
+    * we continue while the connection pool is active
+    */
    @Override
    protected boolean shouldDoWork() {
-	return super.shouldDoWork()
+      return super.shouldDoWork() && futureCommandConnectionPool.getStatus().equals(Status.ACTIVE);
-		&& futureCommandConnectionPool.getStatus()
-			.equals(Status.ACTIVE);
    }
 
+   /**
+    * {@inheritDoc}
+    * 
+    * If the reason we are shutting down is due an exception, we set that exception on all pending
+    * commands. Otherwise, we cancel the pending commands.
+    */
    @Override
    protected void doShutdown() {
-	exception.compareAndSet(null, futureCommandConnectionPool
+      exception.compareAndSet(null, futureCommandConnectionPool.getException());
-		.getException());
       while (!commandQueue.isEmpty()) {
-	    FutureCommand<?, ?, ?> command = (FutureCommand<?, ?, ?>) commandQueue
+         FutureCommand<?, ?, ?> command = (FutureCommand<?, ?, ?>) commandQueue.remove();
-		    .remove();
          if (command != null) {
             if (exception.get() != null)
                command.setException(exception.get());
@@ -79,6 +86,10 @@ public class FutureCommandConnectionPoolClient<C, O extends FutureCommand<?, ?,
 
    @Override
    protected void doWork() throws InterruptedException {
+      takeACommandOffTheQueueAndInvokeIt();
+   }
+
+   private void takeACommandOffTheQueueAndInvokeIt() throws InterruptedException {
       O command = commandQueue.poll(1, TimeUnit.SECONDS);
       if (command != null) {
          try {
@@ -90,36 +101,39 @@ public class FutureCommandConnectionPoolClient<C, O extends FutureCommand<?, ?,
       }
    }
 
+   /**
+    * This is an asynchronous operation that puts the <code>command</code> onto a queue. Later, it
+    * will be processed via the {@link #invoke(FutureCommand) invoke} method.
+    */
    public void submit(O command) {
       exceptionIfNotActive();
       commandQueue.add(command);
    }
 
+   /**
+    * Invoke binds a command with a connection from the pool. This binding is called a
+    * {@link FutureCommandConnectionHandle handle}. The handle will keep this binding until the
+    * command's response is parsed or an exception is set on the Command object.
+    * 
+    * @param command
+    */
    protected void invoke(O command) {
       exceptionIfNotActive();
       FutureCommandConnectionHandle<C, O> connectionHandle = null;
       try {
          connectionHandle = futureCommandConnectionPool.getHandle(command);
       } catch (InterruptedException e) {
-	    logger
+         logger.warn(e, "Interrupted getting a connection for command %1$s; retrying", command);
-		    .warn(
-			    e,
-			    "Interrupted getting a connection for command %1$s; retrying",
-			    command);
          commandQueue.add(command);
          return;
       } catch (TimeoutException e) {
-	    logger.warn(e,
+         logger.warn(e, "Timeout getting a connection for command %1$s; retrying", command);
-		    "Timeout getting a connection for command %1$s; retrying",
-		    command);
          commandQueue.add(command);
          return;
       }
 
       if (connectionHandle == null) {
-	    logger.error(
+         logger.error("Failed to obtain connection for command %1$s; retrying", command);
-		    "Failed to obtain connection for command %1$s; retrying",
-		    command);
          commandQueue.add(command);
          return;
       }
@@ -131,10 +145,8 @@ public class FutureCommandConnectionPoolClient<C, O extends FutureCommand<?, ?,
       final StringBuilder sb = new StringBuilder();
       sb.append("FutureCommandConnectionPoolClient");
       sb.append("{status=").append(status);
-	sb.append(", commandQueue=").append(
+      sb.append(", commandQueue=").append((commandQueue != null) ? commandQueue.size() : 0);
-		(commandQueue != null) ? commandQueue.size() : 0);
+      sb.append(", futureCommandConnectionPool=").append(futureCommandConnectionPool);
-	sb.append(", futureCommandConnectionPool=").append(
-		futureCommandConnectionPool);
       sb.append('}');
       return sb.toString();
    }

core/src/main/java/org/jclouds/http/commands/CommandFactory.java

@@ -28,7 +28,8 @@ import org.jclouds.http.commands.callables.xml.ParseSax;
 import com.google.inject.Inject;
 
 /**
- * // TODO: Adrian: Document this!
+ * temporary factory until guice can do multi-type assisted inject
+ * @see <a href="http://code.google.com/p/google-guice/issues/detail?id=346" />
  * 
  * @author Adrian Cole
  */

core/src/main/java/org/jclouds/lifecycle/BaseLifeCycle.java

@@ -46,8 +46,7 @@ public abstract class BaseLifeCycle implements Runnable, LifeCycle {
    protected volatile Status status;
    protected AtomicReference<Exception> exception = new AtomicReference<Exception>();
 
-    public BaseLifeCycle(ExecutorService executor,
+   public BaseLifeCycle(ExecutorService executor, BaseLifeCycle... dependencies) {
-	    BaseLifeCycle... dependencies) {
       this.executor = executor;
       this.dependencies = dependencies;
       this.statusLock = new Object();
@@ -77,6 +76,10 @@ public abstract class BaseLifeCycle implements Runnable, LifeCycle {
 
    protected abstract void doShutdown();
 
+   /**
+    * @return false if any dependencies are inactive, or we are inactive, or we have a global
+    *         exception.
+    */
    protected boolean shouldDoWork() {
       try {
          exceptionIfDepedenciesNotActive();
@@ -116,8 +119,7 @@ public abstract class BaseLifeCycle implements Runnable, LifeCycle {
       for (BaseLifeCycle dependency : dependencies) {
          if (dependency.status.compareTo(Status.ACTIVE) != 0) {
             throw new IllegalStateException(String.format(
-			"Illegal state: %1$s for component: %2$s",
+                     "Illegal state: %1$s for component: %2$s", dependency.status, dependency));
-			dependency.status, dependency));
          }
       }
    }
@@ -130,8 +132,7 @@ public abstract class BaseLifeCycle implements Runnable, LifeCycle {
       awaitStatus(Status.SHUT_DOWN, timeout);
    }
 
-    protected void awaitStatus(Status intended, long timeout)
+   protected void awaitStatus(Status intended, long timeout) throws InterruptedException {
-	    throws InterruptedException {
       synchronized (this.statusLock) {
          long deadline = System.currentTimeMillis() + timeout;
          long remaining = timeout;
@@ -167,8 +168,7 @@ public abstract class BaseLifeCycle implements Runnable, LifeCycle {
 
    protected void exceptionIfNotActive() {
       if (!status.equals(Status.ACTIVE))
-	    throw new IllegalStateException(String.format("not active: %1$s",
+         throw new IllegalStateException(String.format("not active: %1$s", this));
-		    this));
    }
 
 }

core/src/main/java/org/jclouds/lifecycle/Closer.java

@@ -30,7 +30,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * // TODO: Adrian: Document this!
+ * This will close objects in the reverse order that they were added.
  * 
  * @author Adrian Cole
  */

core/src/main/java/org/jclouds/lifecycle/config/LifeCycleModule.java

@@ -48,7 +48,9 @@ import com.google.inject.spi.TypeEncounter;
 import com.google.inject.spi.TypeListener;
 
 /**
- * // TODO: Adrian: Document this!
+ * This associates java lifecycle annotations with guice hooks. For example, we invoke
+ * {@link PostConstruct} after injection, and Associate {@link PostDestroy} with a global
+ * {@link Closer} object.
  * 
  * @author Adrian Cole
  */
@@ -69,8 +71,7 @@ public class LifeCycleModule extends AbstractModule {
 
    protected void bindPostInjectionInvoke(final Closer closer) {
       bindListener(any(), new TypeListener() {
-	    public <I> void hear(TypeLiteral<I> injectableType,
+         public <I> void hear(TypeLiteral<I> injectableType, TypeEncounter<I> encounter) {
-		    TypeEncounter<I> encounter) {
             Set<Method> methods = new HashSet<Method>();
             Class<? super I> type = injectableType.getRawType();
             while (type != null) {
@@ -78,27 +79,14 @@ public class LifeCycleModule extends AbstractModule {
                type = type.getSuperclass();
             }
             for (final Method method : methods) {
-		    PostConstruct postConstruct = method
+               invokePostConstructMethodAfterInjection(encounter, method);
-			    .getAnnotation(PostConstruct.class);
+               associatePreDestroyWithCloser(closer, encounter, method);
-		    if (postConstruct != null) {
-			encounter.register(new InjectionListener<I>() {
-			    public void afterInjection(I injectee) {
-				try {
-				    method.invoke(injectee);
-				} catch (InvocationTargetException ie) {
-				    Throwable e = ie.getTargetException();
-				    throw new ProvisionException(
-					    e.getMessage(), e);
-				} catch (IllegalAccessException e) {
-				    throw new ProvisionException(
-					    e.getMessage(), e);
             }
          }
-			});
-		    }
 
-		    PreDestroy preDestroy = method
+         private <I> void associatePreDestroyWithCloser(final Closer closer,
-			    .getAnnotation(PreDestroy.class);
+                  TypeEncounter<I> encounter, final Method method) {
+            PreDestroy preDestroy = method.getAnnotation(PreDestroy.class);
             if (preDestroy != null) {
                encounter.register(new InjectionListener<I>() {
                   public void afterInjection(final I injectee) {
@@ -107,13 +95,10 @@ public class LifeCycleModule extends AbstractModule {
                            try {
                               method.invoke(injectee);
                            } catch (InvocationTargetException ie) {
-					    Throwable e = ie
+                              Throwable e = ie.getTargetException();
-						    .getTargetException();
+                              throw new IOException(e.getMessage());
-					    throw new IOException(e
-						    .getMessage());
                            } catch (IllegalAccessException e) {
-					    throw new IOException(e
+                              throw new IOException(e.getMessage());
-						    .getMessage());
                            }
                         }
                      });
@@ -122,6 +107,24 @@ public class LifeCycleModule extends AbstractModule {
                });
             }
          }
+
+         private <I> void invokePostConstructMethodAfterInjection(TypeEncounter<I> encounter,
+                  final Method method) {
+            PostConstruct postConstruct = method.getAnnotation(PostConstruct.class);
+            if (postConstruct != null) {
+               encounter.register(new InjectionListener<I>() {
+                  public void afterInjection(I injectee) {
+                     try {
+                        method.invoke(injectee);
+                     } catch (InvocationTargetException ie) {
+                        Throwable e = ie.getTargetException();
+                        throw new ProvisionException(e.getMessage(), e);
+                     } catch (IllegalAccessException e) {
+                        throw new ProvisionException(e.getMessage(), e);
+                     }
+                  }
+               });
+            }
          }
       });
    }