Package com.couchbase.client.java
Class CouchbaseCluster
- java.lang.Object
-
- com.couchbase.client.java.CouchbaseCluster
-
- All Implemented Interfaces:
Cluster
public class CouchbaseCluster extends Object implements Cluster
Main synchronous entry point to a Couchbase Cluster. TheCouchbaseCluster
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 theClusterManager
class, but mainly provides facilities to openBucket
s where the actual CRUD and query operations are performed against. The simplest way to initialize aCouchbaseCluster
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 Cluster cluster = CouchbaseCluster.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 Cluster cluster = CouchbaseCluster.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(); Cluster cluster = CouchbaseCluster.create(environment, "192.168.56.101", "192.168.56.102"); 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é
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description AsyncCluster
async()
Returns a reference to the underlying async cluster.CouchbaseCluster
authenticate(Authenticator auth)
Sets theAuthenticator
to use when credentials are needed for an operation but no explicit credentials are provided.CouchbaseCluster
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.ClusterManager
clusterManager()
Provides access to theClusterManager
to perform cluster-wide operations, using the credentials set through the configuredAuthenticator
(seeCluster.authenticate(Authenticator)
), for theCredentialContext.CLUSTER_MANAGEMENT
context.ClusterManager
clusterManager(String username, String password)
Provides access to theClusterManager
to perform cluster-wide operations.ClusterFacade
core()
Returns the underlying "core-io" library through itsClusterFacade
.static CouchbaseCluster
create()
Creates a newCouchbaseCluster
reference against theCouchbaseAsyncCluster.DEFAULT_HOST
.static CouchbaseCluster
create(CouchbaseEnvironment environment)
Creates a newCouchbaseCluster
reference against theCouchbaseAsyncCluster.DEFAULT_HOST
.static CouchbaseCluster
create(CouchbaseEnvironment environment, String... nodes)
Creates a newCouchbaseCluster
reference against the nodes passed in.static CouchbaseCluster
create(CouchbaseEnvironment environment, List<String> nodes)
Creates a newCouchbaseCluster
reference against the nodes passed in.static CouchbaseCluster
create(String... nodes)
Creates a newCouchbaseCluster
reference against the nodes passed in.static CouchbaseCluster
create(List<String> nodes)
Creates a newCouchbaseCluster
reference against the nodes passed in.DiagnosticsReport
diagnostics()
Provides a simple health check which allows insight into the current state of services and endpoints.DiagnosticsReport
diagnostics(String reportId)
Provides a simple health check which allows insight into the current state of services and endpoints.Boolean
disconnect()
Disconnects form all open buckets and shuts down theCouchbaseEnvironment
if it is the exclusive owner with the default disconnect timeout.Boolean
disconnect(long timeout, TimeUnit timeUnit)
Disconnects form all open buckets and shuts down theCouchbaseEnvironment
if it is the exclusive owner with a custom timeout.static CouchbaseCluster
fromConnectionString(CouchbaseEnvironment environment, String connectionString)
Creates a newCouchbaseCluster
reference using the connection string.static CouchbaseCluster
fromConnectionString(String connectionString)
Creates a newCouchbaseCluster
reference using the connection string.Bucket
openBucket()
Opens the default bucket with an empty password with the default connect timeout.Bucket
openBucket(long timeout, TimeUnit timeUnit)
Opens the default bucket with an empty password with a custom timeout.Bucket
openBucket(String name)
Opens the bucket with the given name, using the default timeout and the password from theAuthenticator
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used.Bucket
openBucket(String name, long timeout, TimeUnit timeUnit)
Opens the bucket with the given name, using a custom timeout and the password from theAuthenticator
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used.Bucket
openBucket(String name, String password)
Opens a bucket identified by its name and password with the default connect timeout.Bucket
openBucket(String name, String password, long timeout, TimeUnit timeUnit)
Opens a bucket identified by its name and password with a custom timeout.Bucket
openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders)
Opens a bucket identified by its name and password with custom transcoders and with the default connect timeout.Bucket
openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders, long timeout, TimeUnit timeUnit)
Opens a bucket identified by its name and password with custom transcoders and with a custom timeout.Bucket
openBucket(String name, List<Transcoder<? extends Document,?>> transcoders)
Opens the bucket with the given name, using the default timeout and the password from theAuthenticator
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used.Bucket
openBucket(String name, List<Transcoder<? extends Document,?>> transcoders, long timeout, TimeUnit timeUnit)
Opens the bucket with the given name, using a custom timeout and the password from theAuthenticator
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used.N1qlQueryResult
query(N1qlQuery query)
Synchronously perform a N1QL query that can span multiple buckets, with the defaulttimeout
.N1qlQueryResult
query(N1qlQuery query, long timeout, TimeUnit timeUnit)
Synchronously perform a N1QL query that can span multiple buckets, with a custom timeout.
-
-
-
Method Detail
-
create
public static CouchbaseCluster create()
Creates a newCouchbaseCluster
reference against theCouchbaseAsyncCluster.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 usecreate(String...)
or similar instead. TheCouchbaseEnvironment
will be automatically created and its lifecycle managed.- Returns:
- a new
CouchbaseCluster
reference.
-
create
public static CouchbaseCluster create(CouchbaseEnvironment environment)
Creates a newCouchbaseCluster
reference against theCouchbaseAsyncCluster.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 usecreate(String...)
or similar instead.- Parameters:
environment
- the custom environment to use for this cluster reference.- Returns:
- a new
CouchbaseCluster
reference.
-
create
public static CouchbaseCluster create(String... nodes)
Creates a newCouchbaseCluster
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
CouchbaseCluster
reference.
-
create
public static CouchbaseCluster create(List<String> nodes)
Creates a newCouchbaseCluster
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
CouchbaseCluster
reference.
-
create
public static CouchbaseCluster create(CouchbaseEnvironment environment, String... nodes)
Creates a newCouchbaseCluster
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
CouchbaseCluster
reference.
-
create
public static CouchbaseCluster create(CouchbaseEnvironment environment, List<String> nodes)
Creates a newCouchbaseCluster
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
CouchbaseCluster
reference.
-
fromConnectionString
public static CouchbaseCluster fromConnectionString(String connectionString)
Creates a newCouchbaseCluster
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
CouchbaseCluster
reference.
-
fromConnectionString
public static CouchbaseCluster fromConnectionString(CouchbaseEnvironment environment, String connectionString)
Creates a newCouchbaseCluster
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
CouchbaseCluster
reference.
-
async
public AsyncCluster async()
Description copied from interface:Cluster
Returns a reference to the underlying async cluster.
-
openBucket
public Bucket openBucket()
Description copied from interface:Cluster
Opens the default bucket with an empty password with the default connect timeout. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(long timeout, TimeUnit timeUnit)
Description copied from interface:Cluster
Opens the default bucket with an empty password with a custom timeout. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
- Parameters:
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(String name)
Description copied from interface:Cluster
Opens the bucket with the given name, using the default timeout and the password from theAuthenticator
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(String name, long timeout, TimeUnit timeUnit)
Description copied from interface:Cluster
Opens the bucket with the given name, using a custom timeout and the password from theAuthenticator
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(String name, List<Transcoder<? extends Document,?>> transcoders)
Description copied from interface:Cluster
Opens the bucket with the given name, using the default timeout and the password from theAuthenticator
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(String name, List<Transcoder<? extends Document,?>> transcoders, long timeout, TimeUnit timeUnit)
Description copied from interface:Cluster
Opens the bucket with the given name, using a custom timeout and the password from theAuthenticator
If no credential context can be found for the bucket when usingClassicAuthenticator
, the old behavior of defaulting to an empty password is used. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(String name, String password)
Description copied from interface:Cluster
Opens a bucket identified by its name and password with the default connect timeout. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(String name, String password, long timeout, TimeUnit timeUnit)
Description copied from interface:Cluster
Opens a bucket identified by its name and password with a custom timeout. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders)
Description copied from interface:Cluster
Opens a bucket identified by its name and password with custom transcoders and with the default connect timeout. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
- Returns:
- the opened bucket if successful.
-
openBucket
public Bucket openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders, long timeout, TimeUnit timeUnit)
Description copied from interface:Cluster
Opens a bucket identified by its name and password with custom transcoders and with a custom timeout. This method throws: - java.util.concurrent.TimeoutException: If the timeout is exceeded. - 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 interfaceCluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.- Returns:
- the opened bucket if successful.
-
clusterManager
public ClusterManager clusterManager(String username, String password)
Description copied from interface:Cluster
Provides access to theClusterManager
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 interfaceCluster
- Parameters:
username
- the username to perform cluster-wide operations.password
- the password associated with the username.- Returns:
- the
ClusterManager
if successful.
-
clusterManager
public ClusterManager clusterManager()
Description copied from interface:Cluster
Provides access to theClusterManager
to perform cluster-wide operations, using the credentials set through the configuredAuthenticator
(seeCluster.authenticate(Authenticator)
), for theCredentialContext.CLUSTER_MANAGEMENT
context.- Specified by:
clusterManager
in interfaceCluster
- Returns:
- the
ClusterManager
if successful.
-
disconnect
public Boolean disconnect()
Description copied from interface:Cluster
Disconnects form all open buckets and shuts down theCouchbaseEnvironment
if it is the exclusive owner with the default disconnect timeout.- Specified by:
disconnect
in interfaceCluster
- Returns:
- true once done and everything succeeded, false otherwise.
-
disconnect
public Boolean disconnect(long timeout, TimeUnit timeUnit)
Description copied from interface:Cluster
Disconnects form all open buckets and shuts down theCouchbaseEnvironment
if it is the exclusive owner with a custom timeout.- Specified by:
disconnect
in interfaceCluster
- Returns:
- true once done and everything succeeded, false otherwise.
-
core
public ClusterFacade core()
Description copied from interface:Cluster
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 interfaceCluster
- Returns:
- the underlying
ClusterFacade
from the "core-io" package.
-
authenticate
public CouchbaseCluster authenticate(Authenticator auth)
Description copied from interface:Cluster
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 interfaceCluster
- Parameters:
auth
- the newAuthenticator
to use.- Returns:
- this Cluster instance for chaining.
-
authenticate
public CouchbaseCluster authenticate(String username, String password)
Description copied from interface:Cluster
Shortcut method to directly authenticate with a username and a password.- Specified by:
authenticate
in interfaceCluster
- 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 N1qlQueryResult query(N1qlQuery query)
Description copied from interface:Cluster
Synchronously perform a N1QL query that can span multiple buckets, with the defaulttimeout
. The query will use credentials set through this cluster'sAuthenticator
. In order to use that method, at least oneBucket
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. This method throws under the following conditions: -UnsupportedOperationException
: no bucket is currently opened. -IllegalStateException
: noAuthenticator
is set or no credentials are available in it for cluster level querying. -TimeoutException
wrapped in aRuntimeException
: the operation takes longer than the default 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 interfaceCluster
- Parameters:
query
- theN1qlQuery
to execute.- Returns:
- the
query result
.
-
query
public N1qlQueryResult query(N1qlQuery query, long timeout, TimeUnit timeUnit)
Description copied from interface:Cluster
Synchronously perform a N1QL query that can span multiple buckets, with a custom timeout. The query will use credentials set through this cluster'sAuthenticator
. In order to use that method, at least oneBucket
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. This method throws under the following conditions: -UnsupportedOperationException
: no bucket is currently opened. -IllegalStateException
: noAuthenticator
is set or no credentials are available in it for cluster level querying. -TimeoutException
wrapped in aRuntimeException
: 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 interfaceCluster
- Parameters:
query
- theN1qlQuery
to execute.timeout
- the custom timeout.timeUnit
- the unit for the timeout.- Returns:
- the
query result
.
-
diagnostics
public DiagnosticsReport diagnostics()
Description copied from interface:Cluster
Provides a simple health check which allows insight into the current state of services and endpoints.- Specified by:
diagnostics
in interfaceCluster
- Returns:
- health services in the form of
DiagnosticsReport
.
-
diagnostics
public DiagnosticsReport diagnostics(String reportId)
Description copied from interface:Cluster
Provides a simple health check which allows insight into the current state of services and endpoints.- Specified by:
diagnostics
in interfaceCluster
- Returns:
- health services in the form of
DiagnosticsReport
.
-
-