public class CouchbaseAsyncCluster extends Object implements AsyncCluster
CouchbaseAsyncCluster object is the main entry point when connecting to a remote
Couchbase Server cluster. It will either create a bundled stateful environment or accept
one passed in, in case the application needs to connect to more clusters at the same time.
It provides cluster level management facilities through the AsyncClusterManager class,
but mainly provides facilities to open AsyncBuckets where the actual CRUD and query
operations are performed against.
The simplest way to initialize a CouchbaseAsyncCluster is by using the create()
factory method. This is only recommended during development, since it will connect to a Cluster
residing on `127.0.0.1`.
```java
AsyncCluster cluster = CouchbaseAsyncCluster.create();
```
In production, it is recommended that at least two or three hosts are passed in, so in case one
fails the SDK is able to bootstrap through alternative options.
```java
AsyncCluster cluster = CouchbaseAsyncCluster.create(
"192.168.56.101", "192.168.56.102", "192.168.56.103"
);
```
Please make sure that these hosts are part of the same cluster, otherwise non-deterministic
connecting behaviour will arise (the SDK may connect to the wrong cluster).
If you need to customize CouchbaseEnvironment options or connect to multiple clusters,
it is recommended to explicitly create one and then reuse it. Keep in mind that the cluster will
not shut down the environment if it didn't create it, so this is up to the caller.
```java
CouchbaseEnvironment environment = DefaultCouchbaseEnvironment.builder()
.kvTimeout(3000) // change the default kv timeout
.build();
AsyncCluster cluster = CouchbaseAsyncCluster.create(environment, "192.168.56.101",
"192.168.56.102");
Observable<Bucket> bucket = cluster.openBucket("travel-sample");
// Perform your work here...
cluster.disconnect();
environment.shutdownAsync().toBlocking().single();
```| Modifier and Type | Field and Description |
|---|---|
static String |
DEFAULT_BUCKET
The default bucket used when
openBucket() is called. |
static String |
DEFAULT_HOST
The default hostname used to bootstrap then
create() is used. |
| Modifier and Type | Method and Description |
|---|---|
CouchbaseAsyncCluster |
authenticate(Authenticator auth)
Sets the
Authenticator to use when credentials are needed for an operation
but no explicit credentials are provided. |
AsyncCluster |
authenticate(String username,
String password)
Shortcut method to directly authenticate with a username and a password.
|
Authenticator |
authenticator()
Get the
Authenticator currently used when credentials are needed for an
operation, but no explicit credentials are provided. |
rx.Observable<AsyncClusterManager> |
clusterManager()
Provides access to the
AsyncClusterManager to perform cluster-wide operations, using the
credentials set through the configured Authenticator, for the
CredentialContext.CLUSTER_MANAGEMENT context. |
rx.Observable<AsyncClusterManager> |
clusterManager(String username,
String password)
Provides access to the
AsyncClusterManager to perform cluster-wide operations. |
rx.Observable<ClusterFacade> |
core()
Returns the underlying "core-io" library through its
ClusterFacade. |
static CouchbaseAsyncCluster |
create()
Creates a new
CouchbaseAsyncCluster reference against the DEFAULT_HOST. |
static CouchbaseAsyncCluster |
create(CouchbaseEnvironment environment)
Creates a new
CouchbaseAsyncCluster reference against the DEFAULT_HOST. |
static CouchbaseAsyncCluster |
create(CouchbaseEnvironment environment,
List<String> nodes)
Creates a new
CouchbaseAsyncCluster reference against the nodes passed in. |
static CouchbaseAsyncCluster |
create(CouchbaseEnvironment environment,
String... nodes)
Creates a new
CouchbaseAsyncCluster reference against the nodes passed in. |
static CouchbaseAsyncCluster |
create(List<String> nodes)
Creates a new
CouchbaseAsyncCluster reference against the nodes passed in. |
static CouchbaseAsyncCluster |
create(String... nodes)
Creates a new
CouchbaseAsyncCluster reference against the nodes passed in. |
rx.Observable<DiagnosticsReport> |
diagnostics()
Provides a simple health check which allows insight into the current state of
services and endpoints.
|
rx.Observable<DiagnosticsReport> |
diagnostics(String reportId)
Provides a simple health check which allows insight into the current state of
services and endpoints.
|
rx.Observable<Boolean> |
disconnect()
Disconnects form all open buckets and shuts down the
CouchbaseEnvironment if it is the exclusive owner. |
static CouchbaseAsyncCluster |
fromConnectionString(CouchbaseEnvironment environment,
String connectionString)
Creates a new
CouchbaseAsyncCluster reference using the connection string. |
static CouchbaseAsyncCluster |
fromConnectionString(String connectionString)
Creates a new
CouchbaseAsyncCluster reference using the connection string. |
protected Credential |
getSingleCredential(CredentialContext context,
String specific) |
rx.Observable<AsyncBucket> |
openBucket()
Opens the default bucket with an empty password.
|
rx.Observable<AsyncBucket> |
openBucket(String name)
Opens the bucket with the given name using the password from the
Authenticator that was last
set
If no credential context can be found for the bucket when using ClassicAuthenticator , the old behavior of defaulting to an empty
password is used. |
rx.Observable<AsyncBucket> |
openBucket(String name,
List<Transcoder<? extends Document,?>> transcoders)
Opens the bucket with the given name using the password from the
Authenticator that was last
set
If no credential context can be found for the bucket when using ClassicAuthenticator , the old behavior of defaulting to an empty
password is used. |
rx.Observable<AsyncBucket> |
openBucket(String name,
String password)
Opens the bucket with the given name and password.
|
rx.Observable<AsyncBucket> |
openBucket(String name,
String password,
List<Transcoder<? extends Document,?>> transcoders)
Opens the bucket with the given name, password and a custom list of
Transcoders. |
rx.Observable<AsyncN1qlQueryResult> |
query(N1qlQuery query)
Asynchronously perform a N1QL query that can span multiple buckets.
|
public static final String DEFAULT_BUCKET
openBucket() is called.
Defaults to "default".public static final String DEFAULT_HOST
create() is used.
Defaults to "127.0.0.1".public static CouchbaseAsyncCluster create()
CouchbaseAsyncCluster reference against the DEFAULT_HOST.
**Note:** It is recommended to use this method only during development, since it does not
allow you to pass in hostnames when connecting to a remote cluster. Please use
create(String...) or similar instead.
The CouchbaseEnvironment will be automatically created and its lifecycle managed.CouchbaseAsyncCluster reference.public static CouchbaseAsyncCluster create(CouchbaseEnvironment environment)
CouchbaseAsyncCluster reference against the DEFAULT_HOST.
**Note:** It is recommended to use this method only during development, since it does not
allow you to pass in hostnames when connecting to a remote cluster. Please use
create(String...) or similar instead.environment - the custom environment to use for this cluster reference.CouchbaseAsyncCluster reference.public static CouchbaseAsyncCluster create(String... nodes)
CouchbaseAsyncCluster reference against the nodes passed in.
The CouchbaseEnvironment will be automatically created and its lifecycle managed.nodes - the list of nodes to use when connecting to the cluster reference.CouchbaseAsyncCluster reference.public static CouchbaseAsyncCluster create(List<String> nodes)
CouchbaseAsyncCluster reference against the nodes passed in.
The CouchbaseEnvironment will be automatically created and its lifecycle managed.nodes - the list of nodes to use when connecting to the cluster reference.CouchbaseAsyncCluster reference.public static CouchbaseAsyncCluster create(CouchbaseEnvironment environment, String... nodes)
CouchbaseAsyncCluster reference against the nodes passed in.environment - the custom environment to use for this cluster reference.nodes - the list of nodes to use when connecting to the cluster reference.CouchbaseAsyncCluster reference.public static CouchbaseAsyncCluster create(CouchbaseEnvironment environment, List<String> nodes)
CouchbaseAsyncCluster reference against the nodes passed in.environment - the custom environment to use for this cluster reference.nodes - the list of nodes to use when connecting to the cluster reference.CouchbaseAsyncCluster reference.public static CouchbaseAsyncCluster fromConnectionString(String connectionString)
CouchbaseAsyncCluster reference using the connection string.
The CouchbaseEnvironment will be automatically created and its lifecycle managed.connectionString - the connection string to identify the remote cluster.CouchbaseAsyncCluster reference.public static CouchbaseAsyncCluster fromConnectionString(CouchbaseEnvironment environment, String connectionString)
CouchbaseAsyncCluster reference using the connection string.environment - the custom environment to use for this cluster reference.connectionString - the connection string to identify the remote cluster.CouchbaseAsyncCluster reference.public rx.Observable<AsyncBucket> openBucket()
AsyncClusterObservable can error under the following conditions:
- com.couchbase.client.core.CouchbaseException: If the bucket could not be opened (see logs and nested stack
trace for more details why it failed).
- com.couchbase.client.core.BackpressureException: If the incoming request rate is too high to be processed.openBucket in interface AsyncClusterpublic rx.Observable<AsyncBucket> openBucket(String name)
AsyncClusterAuthenticator that was last
set
If no credential context can be found for the bucket when using ClassicAuthenticator , the old behavior of defaulting to an empty
password is used.
The Observable can error under the following conditions:
- com.couchbase.client.core.CouchbaseException: If the bucket could not be opened (see logs and nested stack
trace for more details why it failed).
- com.couchbase.client.core.BackpressureException: If the incoming request rate is too high to be processed.
- AuthenticatorException: If more than one credentials was returned by the Authenticator for this bucket.openBucket in interface AsyncClustername - the name of the bucket.public rx.Observable<AsyncBucket> openBucket(String name, List<Transcoder<? extends Document,?>> transcoders)
AsyncClusterAuthenticator that was last
set
If no credential context can be found for the bucket when using ClassicAuthenticator , the old behavior of defaulting to an empty
password is used.
The Observable can error under the following conditions:
- com.couchbase.client.core.CouchbaseException: If the bucket could not be opened (see logs and nested stack
trace for more details why it failed).
- com.couchbase.client.core.BackpressureException: If the incoming request rate is too high to be processed.
- AuthenticatorException: If more than one credentials was returned by the Authenticator for this bucket.openBucket in interface AsyncClustername - the name of the bucket.public rx.Observable<AsyncBucket> openBucket(String name, String password)
AsyncClusterObservable can error under the following conditions:
- com.couchbase.client.core.CouchbaseException: If the bucket could not be opened (see logs and nested stack
trace for more details why it failed).
- com.couchbase.client.core.BackpressureException: If the incoming request rate is too high to be processed.openBucket in interface AsyncClustername - the name of the bucket.public rx.Observable<AsyncBucket> openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders)
AsyncClusterTranscoders.
The Observable can error under the following conditions:
- com.couchbase.client.core.CouchbaseException: If the bucket could not be opened (see logs and nested stack
trace for more details why it failed).
- com.couchbase.client.core.BackpressureException: If the incoming request rate is too high to be processed.openBucket in interface AsyncClustername - the name of the bucket.public rx.Observable<Boolean> disconnect()
AsyncClusterCouchbaseEnvironment if it is the exclusive owner.disconnect in interface AsyncClusterpublic rx.Observable<AsyncClusterManager> clusterManager(String username, String password)
AsyncClusterAsyncClusterManager to perform cluster-wide operations.
Note that the credentials provided here are different from bucket-level credentials. As a rule of thumb, the
"Administrator" credentials need to be passed in here or any credentials with enough permissions to perform
the underlying operations. **Bucket level credentials will not work.**clusterManager in interface AsyncClusterusername - the username to perform cluster-wide operations.password - the password associated with the username.AsyncClusterManager if successful.protected Credential getSingleCredential(CredentialContext context, String specific)
public rx.Observable<AsyncClusterManager> clusterManager()
AsyncClusterAsyncClusterManager to perform cluster-wide operations, using the
credentials set through the configured Authenticator, for the
CredentialContext.CLUSTER_MANAGEMENT context.
The Observable can error under the following notable condition:
- AuthenticatorException: if no Authenticator is set or it doesn't contains a cluster
management credential.clusterManager in interface AsyncClusterAsyncClusterManager if successful.public rx.Observable<ClusterFacade> core()
AsyncClusterClusterFacade.
Handle with care, with great power comes great responsibility. All additional checks which are normally performed
by this library are skipped.core in interface AsyncClusterClusterFacade from the "core-io" package.public CouchbaseAsyncCluster authenticate(Authenticator auth)
AsyncClusterAuthenticator to use when credentials are needed for an operation
but no explicit credentials are provided.
Note that setting a new Authenticator will not be propagated to any Bucket that
has been opened with the previous Authenticator, as the instance is passed to the Bucket
for its own use.authenticate in interface AsyncClusterauth - the new Authenticator to use.public AsyncCluster authenticate(String username, String password)
AsyncClusterauthenticate in interface AsyncClusterusername - the username to authenticatepassword - the password for the username@InterfaceStability.Uncommitted @InterfaceAudience.Private public Authenticator authenticator()
Authenticator currently used when credentials are needed for an
operation, but no explicit credentials are provided.public rx.Observable<AsyncN1qlQueryResult> query(N1qlQuery query)
AsyncClusterAuthenticator.
In order to use that method, at least one AsyncBucket must currently be opened. Note that if you
are only performing queries spanning a single bucket, you should prefer opening that Bucket and
use the query API at the bucket level.
The Observable can fail in the following notable conditions:
- UnsupportedOperationException: no bucket is currently opened.
- IllegalStateException: no Authenticator is set or no credentials are available in it for cluster
level querying.
- TimeoutException: the operation takes longer than the specified timeout.
- BackpressureException: the producer outpaces the SDK.
- RequestCancelledException: the operation had to be cancelled while on the wire or the retry strategy
cancelled it instead of retrying.query in interface AsyncClusterquery - the N1qlQuery to execute.query result.public rx.Observable<DiagnosticsReport> diagnostics(String reportId)
AsyncClusterdiagnostics in interface AsyncClusterDiagnosticsReport.public rx.Observable<DiagnosticsReport> diagnostics()
AsyncClusterdiagnostics in interface AsyncClusterDiagnosticsReport.Copyright © 2015 Couchbase, Inc.