Package com.couchbase.client.java
Class CouchbaseAsyncCluster
- java.lang.Object
-
- com.couchbase.client.java.CouchbaseAsyncCluster
-
- All Implemented Interfaces:
AsyncCluster
public class CouchbaseAsyncCluster extends Object implements AsyncCluster
Main asynchronous entry point to a Couchbase Cluster. TheCouchbaseAsyncCluster
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 theAsyncClusterManager
class, but mainly provides facilities to openAsyncBucket
s where the actual CRUD and query operations are performed against. The simplest way to initialize aCouchbaseAsyncCluster
is by using thecreate()
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 customizeCouchbaseEnvironment
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(); ```- Since:
- 2.0.0
- Author:
- Michael Nitschinger, Simon Baslé
-
-
Field Summary
Fields Modifier and Type Field Description static String
DEFAULT_BUCKET
The default bucket used whenopenBucket()
is called.static String
DEFAULT_HOST
The default hostname used to bootstrap thencreate()
is used.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description CouchbaseAsyncCluster
authenticate(Authenticator auth)
Sets theAuthenticator
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 theAuthenticator
currently used when credentials are needed for an operation, but no explicit credentials are provided.rx.Observable<AsyncClusterManager>
clusterManager()
Provides access to theAsyncClusterManager
to perform cluster-wide operations, using the credentials set through the configuredAuthenticator
, for theCredentialContext.CLUSTER_MANAGEMENT
context.rx.Observable<AsyncClusterManager>
clusterManager(String username, String password)
Provides access to theAsyncClusterManager
to perform cluster-wide operations.rx.Observable<ClusterFacade>
core()
Returns the underlying "core-io" library through itsClusterFacade
.static CouchbaseAsyncCluster
create()
Creates a newCouchbaseAsyncCluster
reference against theDEFAULT_HOST
.static CouchbaseAsyncCluster
create(CouchbaseEnvironment environment)
Creates a newCouchbaseAsyncCluster
reference against theDEFAULT_HOST
.static CouchbaseAsyncCluster
create(CouchbaseEnvironment environment, String... nodes)
Creates a newCouchbaseAsyncCluster
reference against the nodes passed in.static CouchbaseAsyncCluster
create(CouchbaseEnvironment environment, List<String> nodes)
Creates a newCouchbaseAsyncCluster
reference against the nodes passed in.static CouchbaseAsyncCluster
create(String... nodes)
Creates a newCouchbaseAsyncCluster
reference against the nodes passed in.static CouchbaseAsyncCluster
create(List<String> nodes)
Creates a newCouchbaseAsyncCluster
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 theCouchbaseEnvironment
if it is the exclusive owner.static CouchbaseAsyncCluster
fromConnectionString(CouchbaseEnvironment environment, String connectionString)
Creates a newCouchbaseAsyncCluster
reference using the connection string.static CouchbaseAsyncCluster
fromConnectionString(String connectionString)
Creates a newCouchbaseAsyncCluster
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 theAuthenticator
that was lastset
If no credential context can be found for the bucket when usingClassicAuthenticator
, 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 ofTranscoder
s.rx.Observable<AsyncBucket>
openBucket(String name, List<Transcoder<? extends Document,?>> transcoders)
Opens the bucket with the given name using the password from theAuthenticator
that was lastset
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used.rx.Observable<AsyncN1qlQueryResult>
query(N1qlQuery query)
Asynchronously perform a N1QL query that can span multiple buckets.
-
-
-
Field Detail
-
DEFAULT_BUCKET
public static final String DEFAULT_BUCKET
The default bucket used whenopenBucket()
is called. Defaults to "default".- See Also:
- Constant Field Values
-
DEFAULT_HOST
public static final String DEFAULT_HOST
The default hostname used to bootstrap thencreate()
is used. Defaults to "127.0.0.1".- See Also:
- Constant Field Values
-
-
Method Detail
-
create
public static CouchbaseAsyncCluster create()
Creates a newCouchbaseAsyncCluster
reference against theDEFAULT_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 usecreate(String...)
or similar instead. TheCouchbaseEnvironment
will be automatically created and its lifecycle managed.- Returns:
- a new
CouchbaseAsyncCluster
reference.
-
create
public static CouchbaseAsyncCluster create(CouchbaseEnvironment environment)
Creates a newCouchbaseAsyncCluster
reference against theDEFAULT_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 usecreate(String...)
or similar instead.- Parameters:
environment
- the custom environment to use for this cluster reference.- Returns:
- a new
CouchbaseAsyncCluster
reference.
-
create
public static CouchbaseAsyncCluster create(String... nodes)
Creates a newCouchbaseAsyncCluster
reference against the nodes passed in. TheCouchbaseEnvironment
will be automatically created and its lifecycle managed.- Parameters:
nodes
- the list of nodes to use when connecting to the cluster reference.- Returns:
- a new
CouchbaseAsyncCluster
reference.
-
create
public static CouchbaseAsyncCluster create(List<String> nodes)
Creates a newCouchbaseAsyncCluster
reference against the nodes passed in. TheCouchbaseEnvironment
will be automatically created and its lifecycle managed.- Parameters:
nodes
- the list of nodes to use when connecting to the cluster reference.- Returns:
- a new
CouchbaseAsyncCluster
reference.
-
create
public static CouchbaseAsyncCluster create(CouchbaseEnvironment environment, String... nodes)
Creates a newCouchbaseAsyncCluster
reference against the nodes passed in.- Parameters:
environment
- the custom environment to use for this cluster reference.nodes
- the list of nodes to use when connecting to the cluster reference.- Returns:
- a new
CouchbaseAsyncCluster
reference.
-
create
public static CouchbaseAsyncCluster create(CouchbaseEnvironment environment, List<String> nodes)
Creates a newCouchbaseAsyncCluster
reference against the nodes passed in.- Parameters:
environment
- the custom environment to use for this cluster reference.nodes
- the list of nodes to use when connecting to the cluster reference.- Returns:
- a new
CouchbaseAsyncCluster
reference.
-
fromConnectionString
public static CouchbaseAsyncCluster fromConnectionString(String connectionString)
Creates a newCouchbaseAsyncCluster
reference using the connection string. TheCouchbaseEnvironment
will be automatically created and its lifecycle managed.- Parameters:
connectionString
- the connection string to identify the remote cluster.- Returns:
- a new
CouchbaseAsyncCluster
reference.
-
fromConnectionString
public static CouchbaseAsyncCluster fromConnectionString(CouchbaseEnvironment environment, String connectionString)
Creates a newCouchbaseAsyncCluster
reference using the connection string.- Parameters:
environment
- the custom environment to use for this cluster reference.connectionString
- the connection string to identify the remote cluster.- Returns:
- a new
CouchbaseAsyncCluster
reference.
-
openBucket
public rx.Observable<AsyncBucket> openBucket()
Description copied from interface:AsyncCluster
Opens the default bucket with an empty password. TheObservable
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.- Specified by:
openBucket
in interfaceAsyncCluster
- Returns:
- the opened bucket if successful.
-
openBucket
public rx.Observable<AsyncBucket> openBucket(String name)
Description copied from interface:AsyncCluster
Opens the bucket with the given name using the password from theAuthenticator
that was lastset
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used. TheObservable
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.- Specified by:
openBucket
in interfaceAsyncCluster
- Parameters:
name
- the name of the bucket.- Returns:
- the opened bucket if successful.
-
openBucket
public rx.Observable<AsyncBucket> openBucket(String name, List<Transcoder<? extends Document,?>> transcoders)
Description copied from interface:AsyncCluster
Opens the bucket with the given name using the password from theAuthenticator
that was lastset
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used. TheObservable
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.- Specified by:
openBucket
in interfaceAsyncCluster
- Parameters:
name
- the name of the bucket.- Returns:
- the opened bucket if successful.
-
openBucket
public rx.Observable<AsyncBucket> openBucket(String name, String password)
Description copied from interface:AsyncCluster
Opens the bucket with the given name and password. TheObservable
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.- Specified by:
openBucket
in interfaceAsyncCluster
- Parameters:
name
- the name of the bucket.- Returns:
- the opened bucket if successful.
-
openBucket
public rx.Observable<AsyncBucket> openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders)
Description copied from interface:AsyncCluster
Opens the bucket with the given name, password and a custom list ofTranscoder
s. TheObservable
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.- Specified by:
openBucket
in interfaceAsyncCluster
- Parameters:
name
- the name of the bucket.- Returns:
- the opened bucket if successful.
-
disconnect
public rx.Observable<Boolean> disconnect()
Description copied from interface:AsyncCluster
Disconnects form all open buckets and shuts down theCouchbaseEnvironment
if it is the exclusive owner.- Specified by:
disconnect
in interfaceAsyncCluster
- Returns:
- true once done and everything succeeded, false otherwise.
-
clusterManager
public rx.Observable<AsyncClusterManager> clusterManager(String username, String password)
Description copied from interface:AsyncCluster
Provides access to theAsyncClusterManager
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.**- Specified by:
clusterManager
in interfaceAsyncCluster
- Parameters:
username
- the username to perform cluster-wide operations.password
- the password associated with the username.- Returns:
- the
AsyncClusterManager
if successful.
-
getSingleCredential
protected Credential getSingleCredential(CredentialContext context, String specific)
-
clusterManager
public rx.Observable<AsyncClusterManager> clusterManager()
Description copied from interface:AsyncCluster
Provides access to theAsyncClusterManager
to perform cluster-wide operations, using the credentials set through the configuredAuthenticator
, for theCredentialContext.CLUSTER_MANAGEMENT
context. The Observable can error under the following notable condition: -AuthenticatorException
: if noAuthenticator
is set or it doesn't contains a cluster management credential.- Specified by:
clusterManager
in interfaceAsyncCluster
- Returns:
- the
AsyncClusterManager
if successful.
-
core
public rx.Observable<ClusterFacade> core()
Description copied from interface:AsyncCluster
Returns the underlying "core-io" library through itsClusterFacade
. Handle with care, with great power comes great responsibility. All additional checks which are normally performed by this library are skipped.- Specified by:
core
in interfaceAsyncCluster
- Returns:
- the underlying
ClusterFacade
from the "core-io" package.
-
authenticate
public CouchbaseAsyncCluster authenticate(Authenticator auth)
Description copied from interface:AsyncCluster
Sets theAuthenticator
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 anyBucket
that has been opened with the previous Authenticator, as the instance is passed to the Bucket for its own use.- Specified by:
authenticate
in interfaceAsyncCluster
- Parameters:
auth
- the newAuthenticator
to use.- Returns:
- this AsyncCluster instance for chaining.
-
authenticate
public AsyncCluster authenticate(String username, String password)
Description copied from interface:AsyncCluster
Shortcut method to directly authenticate with a username and a password.- Specified by:
authenticate
in interfaceAsyncCluster
- Parameters:
username
- the username to authenticatepassword
- the password for the username- Returns:
- this Cluster instance for chaining.
-
authenticator
@Uncommitted @Private public Authenticator authenticator()
Get theAuthenticator
currently used when credentials are needed for an operation, but no explicit credentials are provided.- Returns:
- the Authenticator currently used for this cluster.
-
query
public rx.Observable<AsyncN1qlQueryResult> query(N1qlQuery query)
Description copied from interface:AsyncCluster
Asynchronously perform a N1QL query that can span multiple buckets. The query will use any credential set through this cluster'sAuthenticator
. In order to use that method, at least oneAsyncBucket
must currently be opened. Note that if you are only performing queries spanning a single bucket, you should prefer opening thatBucket
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
: noAuthenticator
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.- Specified by:
query
in interfaceAsyncCluster
- Parameters:
query
- theN1qlQuery
to execute.- Returns:
- an observable emitting at most a single
query result
.
-
diagnostics
public rx.Observable<DiagnosticsReport> diagnostics(String reportId)
Description copied from interface:AsyncCluster
Provides a simple health check which allows insight into the current state of services and endpoints.- Specified by:
diagnostics
in interfaceAsyncCluster
- Returns:
- health services in the form of
DiagnosticsReport
.
-
diagnostics
public rx.Observable<DiagnosticsReport> diagnostics()
Description copied from interface:AsyncCluster
Provides a simple health check which allows insight into the current state of services and endpoints.- Specified by:
diagnostics
in interfaceAsyncCluster
- Returns:
- health services in the form of
DiagnosticsReport
.
-
-