public class CouchbaseCluster extends Object implements Cluster
Main synchronous entry point to a Couchbase Cluster.
The 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
.
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.
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.
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 |
---|---|
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. |
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 a bucket identified by its name with an empty password and with the default connect timeout.
|
Bucket |
openBucket(String name,
long timeout,
TimeUnit timeUnit)
Opens a bucket identified by its name with an empty password and with a custom timeout.
|
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.
|
public static CouchbaseCluster create()
Creates a new 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)
Creates a new 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)
Creates a new 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)
Creates a new 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)
Creates a new 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)
Creates a new 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)
Creates a new 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)
Creates a new 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 Bucket openBucket()
Cluster
Opens the default bucket with an empty password with the default connect timeout.
This method throws:
openBucket
in interface Cluster
public Bucket openBucket(long timeout, TimeUnit timeUnit)
Cluster
Opens the default bucket with an empty password with a custom timeout.
This method throws:
openBucket
in interface Cluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.public Bucket openBucket(String name)
Cluster
Opens a bucket identified by its name with an empty password and with the default connect timeout.
This method throws:
openBucket
in interface Cluster
public Bucket openBucket(String name, long timeout, TimeUnit timeUnit)
Cluster
Opens a bucket identified by its name with an empty password and with a custom timeout.
This method throws:
openBucket
in interface Cluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.public Bucket openBucket(String name, String password)
Cluster
Opens a bucket identified by its name and password with the default connect timeout.
This method throws:
openBucket
in interface Cluster
public Bucket openBucket(String name, String password, long timeout, TimeUnit timeUnit)
Cluster
Opens a bucket identified by its name and password with a custom timeout.
This method throws:
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
Opens a bucket identified by its name and password with custom transcoders and with the default connect timeout.
This method throws:
openBucket
in interface Cluster
public Bucket openBucket(String name, String password, List<Transcoder<? extends Document,?>> transcoders, long timeout, TimeUnit timeUnit)
Cluster
Opens a bucket identified by its name and password with custom transcoders and with a custom timeout.
This method throws:
openBucket
in interface Cluster
timeout
- the custom timeout.timeUnit
- the time unit for the custom timeout.public ClusterManager clusterManager(String username, String password)
Cluster
Provides access to the 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 Boolean disconnect()
Cluster
Disconnects form all open buckets and shuts down the CouchbaseEnvironment
if it is the exclusive owner with the default disconnect timeout.
disconnect
in interface Cluster
public Boolean disconnect(long timeout, TimeUnit timeUnit)
Cluster
Disconnects form all open buckets and shuts down the CouchbaseEnvironment
if it is the exclusive owner with a custom timeout.
disconnect
in interface Cluster
public ClusterFacade core()
Cluster
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.
core
in interface Cluster
ClusterFacade
from the “core-io” package.Copyright © 2015 Couchbase, Inc.