Cluster (Couchbase Java SDK)

All Known Implementing Classes:

CouchbaseCluster
```
@InterfaceStability.Committed
 @InterfaceAudience.Public
public interface Cluster
```
Represents a Couchbase Server Cluster.
A Cluster is able to open many Buckets while sharing the underlying resources very efficiently. In addition, the ClusterManager is available to perform cluster-wide operations.

Since:

2.0

Author:

Michael Nitschinger

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Cluster`	`authenticate(Authenticator auth)` Sets the `Authenticator` to use when credentials are needed for an operation but no explicit credentials are provided.
`Cluster`	`authenticate(String username, String password)` Shortcut method to directly authenticate with a username and a password.
`ClusterManager`	`clusterManager()` Provides access to the `ClusterManager` to perform cluster-wide operations, using the credentials set through the configured `Authenticator` (see `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`.
`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.
`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`
`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`
`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`
`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`
`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.

- Method Detail
  - openBucket
```
Bucket openBucket()
```
    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.
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
Bucket openBucket(long timeout,
                  TimeUnit timeUnit)
```
    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.
    Parameters:
    
    timeout - the custom timeout.
    
    timeUnit - the time unit for the custom timeout.
    
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
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.
    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.
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
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.
    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.
    Parameters:
    
    timeout - the custom timeout.
    
    timeUnit - the time unit for the custom timeout.
    
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
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.
    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.
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
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.
    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.
    Parameters:
    
    timeout - the custom timeout.
    
    timeUnit - the time unit for the custom timeout.
    
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
Bucket openBucket(String name,
                  String password)
```
    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.
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
Bucket openBucket(String name,
                  String password,
                  long timeout,
                  TimeUnit timeUnit)
```
    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.
    Parameters:
    
    timeout - the custom timeout.
    
    timeUnit - the time unit for the custom timeout.
    
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
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.
    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.
    Returns:
    
    the opened bucket if successful.
  - openBucket
```
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.
    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.
    Parameters:
    
    timeout - the custom timeout.
    
    timeUnit - the time unit for the custom timeout.
    
    Returns:
    
    the opened bucket if successful.
  - query
```
@InterfaceStability.Uncommitted
N1qlQueryResult query(N1qlQuery query)
```
    Synchronously perform a N1QL query that can span multiple buckets, with the default 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.
    Parameters:
    
    query - the N1qlQuery to execute.
    
    Returns:
    
    the query result.
  - query
```
@InterfaceStability.Uncommitted
N1qlQueryResult query(N1qlQuery query,
                                                      long timeout,
                                                      TimeUnit timeUnit)
```
    Synchronously perform a N1QL query that can span multiple buckets, with a custom 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 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.
    
    timeout - the custom timeout.
    
    timeUnit - the unit for the timeout.
    
    Returns:
    
    the query result.
  - clusterManager
```
ClusterManager clusterManager(String username,
                              String password)
```
    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.
    
    Parameters:
    
    username - the username to perform cluster-wide operations.
    
    password - the password associated with the username.
    
    Returns:
    
    the ClusterManager if successful.
  - clusterManager
```
ClusterManager clusterManager()
```
    Provides access to the ClusterManager to perform cluster-wide operations, using the credentials set through the configured Authenticator (see authenticate(Authenticator)), for the CredentialContext.CLUSTER_MANAGEMENT context.
    
    Returns:
    
    the ClusterManager if successful.
    
    Throws:
    
    AuthenticatorException - if no Authenticator is set or it doesn’t contain a cluster management credential.
  - disconnect
```
Boolean disconnect()
```
    Disconnects form all open buckets and shuts down the CouchbaseEnvironment if it is the exclusive owner with the default disconnect timeout.
    
    Returns:
    
    true once done and everything succeeded, false otherwise.
  - disconnect
```
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.
    
    Returns:
    
    true once done and everything succeeded, false otherwise.
  - core
```
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
```
Cluster 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 Cluster instance for chaining.
  - authenticate
```
Cluster 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.
  - diagnostics
```
@InterfaceStability.Experimental
 @InterfaceAudience.Public
DiagnosticsReport diagnostics()
```
    Provides a simple health check which allows insight into the current state of services and endpoints.
    
    Returns:
    
    health services in the form of DiagnosticsReport.
  - diagnostics
```
@InterfaceStability.Experimental
 @InterfaceAudience.Public
DiagnosticsReport diagnostics(String reportId)
```
    Provides a simple health check which allows insight into the current state of services and endpoints.
    
    Returns:
    
    health services in the form of DiagnosticsReport.

Interface Cluster

Method Summary

Method Detail

openBucket

openBucket

openBucket

openBucket

openBucket

openBucket

openBucket

openBucket

openBucket

openBucket

query

query

clusterManager

clusterManager

disconnect

disconnect

core

authenticate

authenticate

diagnostics

diagnostics