Merge pull request #967 from jclouds/better-factory-javadoc

improved javadoc including where to look for alternative syntax

blobstore/src/main/java/org/jclouds/blobstore/BlobStoreContextFactory.java

@@ -31,9 +31,17 @@ import com.google.common.collect.ImmutableSet;
 import com.google.inject.Module;
 
 /**
+ * This class is deprecated in favor of {@link ContextBuilder}. Please view
+ * sample usage below:
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder("aws-s3")
+ *                         .credentials(apikey, secret)
+ *                         .buildView(BlobStoreContext.class);
+ * </pre>
  * 
  * @see ContextBuilder
- * @see BlobStoreContextBuilder
+ * @deprecated  As of version 1.5, replaced by {@link ContextBuilder}
  * @author Adrian Cole
  */
 @Deprecated

compute/src/main/java/org/jclouds/compute/ComputeServiceContextFactory.java

@@ -31,9 +31,19 @@ import com.google.common.collect.ImmutableSet;
 import com.google.inject.Module;
 
 /**
+ * This class is deprecated in favor of {@link ContextBuilder}. Please view
+ * sample usage below:
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder("openstack-nova")
+ *                         .endpoint("http://10.10.10.10:5000/v2.0")
+ *                         .credentials(user, pass)
+ *                         .modules(singleton(new SshjSshClientModule()))
+ *                         .buildView(ComputeServiceContext.class);
+ * </pre>
  * 
  * @see ContextBuilder
- * @see ComputeServiceContextBuilder
+ * @deprecated  As of version 1.5, replaced by {@link ContextBuilder}
  * @author Adrian Cole
  */
 @Deprecated

core/src/main/java/org/jclouds/ContextBuilder.java

@@ -91,17 +91,46 @@ import com.google.inject.Stage;
 import com.google.inject.TypeLiteral;
 
 /**
- * Creates {@link RestContext} or {@link Injector} instances based on the most commonly requested
+ * Creates {@link Context} or {@link Injector} configured to an api and
- * arguments.
+ * endpoint. Alternatively, this can be used to make a portable {@link View} of
+ * that api.
+ * 
+ * <br/>
+ * ex. to build a {@link RestContext} on a particular endpoint using the typed
+ * interface
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder(new NovaApiMetadata())
+ *                         .endpoint("http://10.10.10.10:5000/v2.0")
+ *                         .credentials(user, pass)
+ *                         .build(NovaApiMetadata.CONTEXT_TOKEN)
+ * </pre>
+ * 
+ * <br/>
+ * ex. to build a {@link View} of a particular backend context, looked up by
+ * key.
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder("aws-s3")
+ *                         .credentials(apikey, secret)
+ *                         .buildView(BlobStoreContext.class);
+ * </pre>
+ * 
+ * <h4>Assumptions</h4>
+ * 
+ * Threadsafe objects will be bound as singletons to the Injector or Context
+ * provided.
  * <p/>
- * Note that Threadsafe objects will be bound as singletons to the Injector or Context provided.
+ * If no <code>Module</code>s are specified, the default
- * <p/>
+ * {@link JDKLoggingModule logging} and
- * <p/>
+ * {@link JavaUrlHttpCommandExecutorServiceModule http transports} will be
- * If no <code>Module</code>s are specified, the default {@link JDKLoggingModule logging} and
+ * installed.
- * {@link JavaUrlHttpCommandExecutorServiceModule http transports} will be installed.
  * 
  * @author Adrian Cole, Andrew Newdigate
- * @see RestContext
+ * @see Context
+ * @see View
+ * @see ApiMetadata
+ * @see ProviderMetadata
  */
 public class ContextBuilder {
 

loadbalancer/src/main/java/org/jclouds/loadbalancer/LoadBalancerServiceContextFactory.java

@@ -31,9 +31,17 @@ import com.google.common.collect.ImmutableSet;
 import com.google.inject.Module;
 
 /**
+ * This class is deprecated in favor of {@link ContextBuilder}. Please view
+ * sample usage below:
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder("aws-elb")
+ *                         .credentials(apikey, secret)
+ *                         .buildView(LoadBalancerServiceContext.class);
+ * </pre>
  * 
  * @see ContextBuilder
- * @see LoadBalancerServiceContextBuilder
+ * @deprecated  As of version 1.5, replaced by {@link ContextBuilder}
  * @author Adrian Cole
  */
 @Deprecated