Permalink
Browse files

Documentation improvements for the constructors.

Improving documentation for the constructors and making
it clear that - for the moment - different usernames and
bucketnames are not possible.

Change-Id: I9e130f05009a888031cad76a76dc1fcc0f7411dd
Reviewed-on: http://review.couchbase.org/21217
Reviewed-by: Michael Wiederhold <mike@couchbase.com>
Reviewed-by: Matt Ingenthron <matt@couchbase.com>
Tested-by: Michael Wiederhold <mike@couchbase.com>
  • Loading branch information...
1 parent 2178868 commit 96332980449ea58cc2a90805028bf9c0350f39da @daschl daschl committed with mikewied Oct 1, 2012
Showing with 44 additions and 31 deletions.
  1. +44 −31 src/main/java/com/couchbase/client/CouchbaseClient.java
@@ -91,6 +91,12 @@
/**
* A client for Couchbase Server.
+ *
+ * This class acts as your main entry point while working with your Couchbase
+ * cluster (if you want to work with TAP, see the TapClient instead).
+ *
+ * If you are working with Couchbase Server 2.0, remember to set the appropriate
+ * view mode depending on your environment.
*/
public class CouchbaseClient extends MemcachedClient
implements CouchbaseClientIF, Reconfigurable {
@@ -153,16 +159,14 @@
}
/**
- * Get a CouchbaseClient based on the REST response from a Couchbase server.
- *
- * This constructor is merely a convenience for situations where the bucket
- * name is the same as the user name. This is commonly the case.
+ * Get a CouchbaseClient based on the initial server list provided.
*
- * To connect to the "default" special bucket for a given cluster, use an
- * empty string as the password.
+ * This constructor should be used if the bucket name is the same as the
+ * username (which is normally the case). If your bucket does not have
+ * a password (likely the "default" bucket), use an empty string instead.
*
- * If a password has not been assigned to the bucket, it is typically an empty
- * string.
+ * This method is only a convenience method so you don't have to create a
+ * CouchbaseConnectionFactory for yourself.
*
* @param baseList the URI list of one or more servers from the cluster
* @param bucketName the bucket name in the cluster you wish to use
@@ -171,51 +175,60 @@
* @throws ConfigurationException if the configuration provided by the server
* has issues or is not compatible
*/
- public CouchbaseClient(List<URI> baseList, String bucketName, String pwd)
+ public CouchbaseClient(final List<URI> baseList, final String bucketName,
+ final String pwd)
throws IOException {
this(new CouchbaseConnectionFactory(baseList, bucketName, pwd));
}
/**
- * Get a CouchbaseClient based on the REST response from a Couchbase server
- * where the username is different than the bucket name.
+ * Get a CouchbaseClient based on the initial server list provided.
+ *
+ * Currently, Couchbase Server does not support a different username than the
+ * bucket name. Therefore, this method ignores the given username for now
+ * but will likely use it in the future.
*
- * To connect to the "default" special bucket for a given cluster, use an
- * empty string as the password.
+ * This constructor should be used if the bucket name is NOT the same as the
+ * username. If your bucket does not have a password (likely the "default"
+ * bucket), use an empty string instead.
*
- * If a password has not been assigned to the bucket, it is typically an empty
- * string.
+ * This method is only a convenience method so you don't have to create a
+ * CouchbaseConnectionFactory for yourself.
*
* @param baseList the URI list of one or more servers from the cluster
* @param bucketName the bucket name in the cluster you wish to use
- * @param usr the username for the bucket; this nearly always be the same as
- * the bucket name
+ * @param user the username for the bucket
* @param pwd the password for the bucket
* @throws IOException if connections could not be made
- * @throws ConfigurationException if the configuration provided by
- * the server has issues or is not compatible
+ * @throws ConfigurationException if the configuration provided by the server
+ * has issues or is not compatible
*/
public CouchbaseClient(final List<URI> baseList, final String bucketName,
- final String usr, final String pwd) throws IOException {
+ final String user, final String pwd)
+ throws IOException {
this(new CouchbaseConnectionFactory(baseList, bucketName, pwd));
}
/**
- * Get a CouchbaseClient based on the REST response from a Couchbase server
- * where the username is different than the bucket name.
+ * Get a CouchbaseClient based on the settings from the given
+ * CouchbaseConnectionFactory.
*
- * Note that when specifying a ConnectionFactory you must specify a
- * BinaryConnectionFactory. Also the ConnectionFactory's protocol and locator
- * values are always overwritten. The protocol will always be binary and the
- * locator will be chosen based on the bucket type you are connecting to.
+ * If your bucket does not have a password (likely the "default" bucket), use
+ * an empty string instead.
*
- * To connect to the "default" special bucket for a given cluster, use an
- * empty string as the password.
+ * The URI list provided here is only used during the initial connection to
+ * the cluster. Afterwards, the actual cluster-map is synchronized from the
+ * cluster and maintained internally by the client. This allows the client to
+ * update the map as needed (when the cluster topology changes).
*
- * If a password has not been assigned to the bucket, it is typically an empty
- * string.
+ * Note that when specifying a ConnectionFactory you must specify a
+ * BinaryConnectionFactory (which is the case if you use the
+ * CouchbaseConnectionFactory). Also the ConnectionFactory's protocol and
+ * locator values are always overwritten. The protocol will always be binary
+ * and the locator will be chosen based on the bucket type you are connecting
+ * to.
*
- * The subscribe variable is determines whether or not we will subscribe to
+ * The subscribe variable determines whether or not we will subscribe to
* the configuration changes feed. This constructor should be used when
* calling super from subclasses of CouchbaseClient since the subclass might
* want to start the changes feed later.

0 comments on commit 9633298

Please sign in to comment.