Package com.couchbase.client.java

Interface AsyncCluster

All Known Implementing Classes:

CouchbaseAsyncCluster

@InterfaceStability.Committed
@InterfaceAudience.Public
public interface AsyncCluster

Represents a Couchbase Server Cluster.

A AsyncCluster is able to open many AsyncBuckets while sharing the underlying resources very efficiently. In addition, the AsyncClusterManager is available to perform cluster-wide operations.

Since:

2.0

Author:

Michael Nitschinger

Method Summary

Modifier and Type	Method and Description
AsyncCluster	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.
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.
rx.Observable<Boolean>	disconnect() Disconnects form all open buckets and shuts down the CouchbaseEnvironment if it is the exclusive owner.
rx.Observable<ServicesHealth>	healthCheck() Provides a simple health check which allows insight into the current state of services and endpoints.
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
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
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.

Method Detail

openBucket

rx.Observable<AsyncBucket> openBucket()

Opens the default bucket with an empty password.

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.

Returns:

the opened bucket if successful.

openBucket

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.

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.

Parameters:

name - the name of the bucket.

Returns:

the opened bucket if successful.

openBucket

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.

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.

Parameters:

name - the name of the bucket.

Returns:

the opened bucket if successful.

openBucket

rx.Observable<AsyncBucket> openBucket(String name,
                                      String password)

Opens the bucket with the given name and password.

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.

Parameters:

name - the name of the bucket.

Returns:

the opened bucket if successful.

openBucket

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.

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.

Parameters:

name - the name of the bucket.

Returns:

the opened bucket if successful.

query

@InterfaceStability.Uncommitted
rx.Observable<AsyncN1qlQueryResult> query(N1qlQuery query)

Asynchronously perform a N1QL query that can span multiple buckets. The query will use any credential set through this cluster’s Authenticator.

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.

Parameters:

query - the N1qlQuery to execute.

Returns:

an observable emitting at most a single query result.

clusterManager

rx.Observable<AsyncClusterManager> clusterManager(String username,
                                                  String password)

Provides access to the AsyncClusterManager 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.

Parameters:

username - the username to perform cluster-wide operations.

password - the password associated with the username.

Returns:

the AsyncClusterManager if successful.

clusterManager

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.

The Observable can error under the following notable condition:

• AuthenticatorException: if no Authenticator is set or it doesn’t contains a cluster management credential.

Returns:

the AsyncClusterManager if successful.

disconnect

rx.Observable<Boolean> disconnect()

Disconnects form all open buckets and shuts down the CouchbaseEnvironment if it is the exclusive owner.

Returns:

true once done and everything succeeded, false otherwise.

core

rx.Observable<ClusterFacade> core()

Returns the underlying “core-io” library through its ClusterFacade.

Handle with care, with great power comes great responsibility. All additional checks which are normally performed by this library are skipped.

Returns:

the underlying ClusterFacade from the “core-io” package.

authenticate

AsyncCluster authenticate(Authenticator auth)

Sets the Authenticator 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.

Parameters:

auth - the new Authenticator to use.

Returns:

this AsyncCluster instance for chaining.

authenticate

AsyncCluster authenticate(String username,
                          String password)

Shortcut method to directly authenticate with a username and a password.

Parameters:

username - the username to authenticate

password - the password for the username

Returns:

this Cluster instance for chaining.

healthCheck

@InterfaceStability.Experimental
@InterfaceAudience.Public
rx.Observable<ServicesHealth> healthCheck()

Provides a simple health check which allows insight into the current state of services and endpoints.

Returns:

health services in the form of ServicesHealth.