public class CouchbaseCluster extends Object implements Cluster
CouchbaseCluster
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 ClusterManager
class,
but mainly provides facilities to open Bucket
s where the actual CRUD and query
operations are performed against.
The simplest way to initialize a CouchbaseCluster
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
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 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();
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();
```Modifier and Type | Method and Description |
---|---|
AsyncCluster |
async()
Returns a reference to the underlying async cluster.
|
CouchbaseCluster |
authenticate(Authenticator auth)
Sets the
Authenticator 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 the
Authenticator currently used when credentials are needed for an
operation, but no explicit credentials are provided. |
ClusterManager |
clusterManager()
Provides access to the
ClusterManager to perform cluster-wide operations, using the credentials set
through the configured Authenticator (see Cluster.authenticate(Authenticator) ), for the
CredentialContext.CLUSTER_MANAGEMENT context. |
ClusterManager |
clusterManager(String username,
String password)
Provides access to the
ClusterManager to perform cluster-wide operations. |
ClusterFacade |
core()
Returns the underlying "core-io" library through its
ClusterFacade . |
static CouchbaseCluster |
create()
Creates a new
CouchbaseCluster reference against the
CouchbaseAsyncCluster.DEFAULT_HOST . |
static CouchbaseCluster |
create(CouchbaseEnvironment environment)
Creates a new
CouchbaseCluster reference against the
CouchbaseAsyncCluster.DEFAULT_HOST . |
static CouchbaseCluster |
create(CouchbaseEnvironment environment,
List<String> nodes)
Creates a new
CouchbaseCluster reference against the nodes passed in. |
static CouchbaseCluster |
create(CouchbaseEnvironment environment,
String... nodes)
Creates a new
CouchbaseCluster reference against the nodes passed in. |
static CouchbaseCluster |
create(List<String> nodes)
Creates a new
CouchbaseCluster reference against the nodes passed in. |
static CouchbaseCluster |
create(String... nodes)
Creates a new
CouchbaseCluster 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 the
CouchbaseEnvironment 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 the
CouchbaseEnvironment if it is the exclusive owner
with a custom timeout. |
static CouchbaseCluster |
fromConnectionString(CouchbaseEnvironment environment,
String connectionString)
Creates a new
CouchbaseCluster reference using the connection string. |
static CouchbaseCluster |
fromConnectionString(String connectionString)
Creates a new
CouchbaseCluster 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 the
Authenticator
If no credential context can be found for the bucket when using ClassicAuthenticator , the old behavior of
defaulting to an empty password is used. |
Bucket |
openBucket(String name,
List<Transcoder<? extends Document,?>> transcoders)
Opens the bucket with the given name, using the default timeout and the password from the
Authenticator
If no credential context can be found for the bucket when using ClassicAuthenticator , 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 the
Authenticator
If no credential context can be found for the bucket when using ClassicAuthenticator , 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 the
Authenticator
If no credential context can be found for the bucket when using ClassicAuthenticator , 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,
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,
String password,
long timeout,
TimeUnit timeUnit)
Opens a bucket identified by its name and password with a custom timeout.
|
N1qlQueryResult |
query(N1qlQuery query)
Synchronously perform a N1QL query that can span multiple buckets, with the default
timeout . |
N1qlQueryResult |
query(N1qlQuery query,
long timeout,
TimeUnit timeUnit)
Synchronously perform a N1QL query that can span multiple buckets, with a custom timeout.
|
public static CouchbaseCluster create()
CouchbaseCluster
reference against the
CouchbaseAsyncCluster.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.CouchbaseCluster
reference.public static CouchbaseCluster create(CouchbaseEnvironment environment)
CouchbaseCluster
reference against the
CouchbaseAsyncCluster.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.CouchbaseCluster
reference.public static CouchbaseCluster create(String... nodes)
CouchbaseCluster
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.CouchbaseCluster
reference.public static CouchbaseCluster create(List<String> nodes)
CouchbaseCluster
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.CouchbaseCluster
reference.public static CouchbaseCluster create(CouchbaseEnvironment environment, String... nodes)
CouchbaseCluster
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.CouchbaseCluster
reference.public static CouchbaseCluster create(CouchbaseEnvironment environment, List<String> nodes)
CouchbaseCluster
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.CouchbaseCluster
reference.public static CouchbaseCluster fromConnectionString(String connectionString)
CouchbaseCluster
reference using the connection string.
The CouchbaseEnvironment
will be automatically created and its lifecycle managed.connectionString
- the connection string to identify the remote cluster.CouchbaseCluster
reference.public static CouchbaseCluster fromConnectionString(CouchbaseEnvironment environment, String connectionString)
CouchbaseCluster
reference using the connection string.environment
- the custom environment to use for this cluster reference.connectionString
- the connection string to identify the remote cluster.CouchbaseCluster
reference.public AsyncCluster async()
Cluster
public Bucket openBucket()
Cluster
openBucket
in interface Cluster
public Bucket openBucket(long timeout, TimeUnit timeUnit)
Cluster
openBucket
in interface Cluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.public Bucket openBucket(String name)
Cluster
Authenticator
If no credential context can be found for the bucket when using ClassicAuthenticator
, 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.openBucket
in interface Cluster
public Bucket openBucket(String name, long timeout, TimeUnit timeUnit)
Cluster
Authenticator
If no credential context can be found for the bucket when using ClassicAuthenticator
, 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.openBucket
in interface Cluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.public Bucket openBucket(String name, List<Transcoder<? extends Document,?>> transcoders)
Cluster
Authenticator
If no credential context can be found for the bucket when using ClassicAuthenticator
, 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.openBucket
in interface Cluster
public Bucket openBucket(String name, List<Transcoder<? extends Document,?>> transcoders, long timeout, TimeUnit timeUnit)
Cluster
Authenticator
If no credential context can be found for the bucket when using ClassicAuthenticator
, 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.openBucket
in interface Cluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.public Bucket openBucket(String name, String password)
Cluster
openBucket
in interface Cluster
public Bucket openBucket(String name, String password, long timeout, TimeUnit timeUnit)
Cluster
openBucket
in interface Cluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.public Bucket openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders)
Cluster
openBucket
in interface Cluster
public Bucket openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders, long timeout, TimeUnit timeUnit)
Cluster
openBucket
in interface Cluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.public ClusterManager clusterManager(String username, String password)
Cluster
ClusterManager
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 Cluster
username
- the username to perform cluster-wide operations.password
- the password associated with the username.ClusterManager
if successful.public ClusterManager clusterManager()
Cluster
ClusterManager
to perform cluster-wide operations, using the credentials set
through the configured Authenticator
(see Cluster.authenticate(Authenticator)
), for the
CredentialContext.CLUSTER_MANAGEMENT
context.clusterManager
in interface Cluster
ClusterManager
if successful.public Boolean disconnect()
Cluster
CouchbaseEnvironment
if it is the exclusive owner
with the default disconnect timeout.disconnect
in interface Cluster
public Boolean disconnect(long timeout, TimeUnit timeUnit)
Cluster
CouchbaseEnvironment
if it is the exclusive owner
with a custom timeout.disconnect
in interface Cluster
public ClusterFacade core()
Cluster
ClusterFacade
.
Handle with care, with great power comes great responsibility. All additional checks which are normally performed
by this library are skipped.core
in interface Cluster
ClusterFacade
from the "core-io" package.public CouchbaseCluster authenticate(Authenticator auth)
Cluster
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.authenticate
in interface Cluster
auth
- the new Authenticator
to use.public CouchbaseCluster authenticate(String username, String password)
Cluster
authenticate
in interface Cluster
username
- 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 N1qlQueryResult query(N1qlQuery query)
Cluster
timeout
.
The query will use credentials set through this cluster's Authenticator
.
In order to use that method, at least one Bucket
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.
This method throws under the following conditions:
- UnsupportedOperationException
: no bucket is currently opened.
- IllegalStateException
: no Authenticator
is set or no credentials are available in it for cluster
level querying.
- TimeoutException
wrapped in a RuntimeException
: 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.query
in interface Cluster
query
- the N1qlQuery
to execute.query result
.public N1qlQueryResult query(N1qlQuery query, long timeout, TimeUnit timeUnit)
Cluster
Authenticator
.
In order to use that method, at least one Bucket
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.
This method throws under the following conditions:
- UnsupportedOperationException
: no bucket is currently opened.
- IllegalStateException
: no Authenticator
is set or no credentials are available in it for cluster
level querying.
- TimeoutException
wrapped in a RuntimeException
: 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 Cluster
query
- the N1qlQuery
to execute.timeout
- the custom timeout.timeUnit
- the unit for the timeout.query result
.public DiagnosticsReport diagnostics()
Cluster
diagnostics
in interface Cluster
DiagnosticsReport
.public DiagnosticsReport diagnostics(String reportId)
Cluster
diagnostics
in interface Cluster
DiagnosticsReport
.Copyright © 2015 Couchbase, Inc.