com.couchbase.client.java

Class ReactiveCluster

java.lang.Object

com.couchbase.client.java.ReactiveCluster

public class ReactiveCluster
extends Object

The Cluster is the main entry point when connecting to a Couchbase cluster using the reactive APIs.

Most likely you want to start out by using the connect(String, String, String) entry point. For more advanced options you want to use the connect(String, ClusterOptions) method. The entry point that allows overriding the seed nodes (connect(Set, ClusterOptions) is only needed if you run a couchbase cluster at non-standard ports.

When the application shuts down (or the SDK is not needed anymore), you are required to call disconnect(). If you omit this step, the application will terminate (all spawned threads are daemon threads) but any operations or work in-flight will not be able to complete and lead to undesired side-effects. Note that disconnect will also shutdown all associated buckets.

Cluster-level operations like query(String) will not work unless at leas one bucket is opened against a pre 6.5 cluster. If you are using 6.5 or later, you can run cluster-level queries without opening a bucket. All of these operations are lazy, so the SDK will bootstrap in the background and service queries as quickly as possible. This also means that the first operations might be a bit slower until all sockets are opened in the background and the configuration is loaded. If you want to wait explicitly, you can utilize the waitUntilReady(Duration) method before performing your first query.

The SDK will only work against Couchbase Server 5.0 and later, because RBAC (role-based access control) is a first class concept since 3.0 and therefore required.

Method Summary

Modifier and Type	Method and Description
ReactiveAnalyticsIndexManager	analyticsIndexes() Provides access to the Analytics index management services.
Mono<ReactiveAnalyticsResult>	analyticsQuery(String statement) Performs an Analytics query with default AnalyticsOptions.
Mono<ReactiveAnalyticsResult>	analyticsQuery(String statement, AnalyticsOptions options) Performs an Analytics query with custom AnalyticsOptions.
AsyncCluster	async() Provides access to the underlying AsyncCluster.
ReactiveBucket	bucket(String bucketName) Opens a ReactiveBucket with the given name.
ReactiveBucketManager	buckets() Provides access to the bucket management services.
static ReactiveCluster	connect(Set<com.couchbase.client.core.env.SeedNode> seedNodes, ClusterOptions options) Connect to a Couchbase cluster with a list of seed nodes and custom options.
static ReactiveCluster	connect(String connectionString, ClusterOptions options) Connect to a Couchbase cluster with custom Authenticator.
static ReactiveCluster	connect(String connectionString, String username, String password) Connect to a Couchbase cluster with a username and a password as credentials.
com.couchbase.client.core.Core	core() Provides access to the underlying Core.
Mono<com.couchbase.client.core.diagnostics.DiagnosticsResult>	diagnostics() Runs a diagnostic report on the current state of the cluster from the SDKs point of view.
Mono<com.couchbase.client.core.diagnostics.DiagnosticsResult>	diagnostics(DiagnosticsOptions options) Runs a diagnostic report with custom options on the current state of the cluster from the SDKs point of view.
Mono<Void>	disconnect() Performs a non-reversible disconnect of this ReactiveCluster.
Mono<Void>	disconnect(Duration timeout) Performs a non-reversible disconnect of this ReactiveCluster.
ClusterEnvironment	environment() Provides access to the configured ClusterEnvironment for this cluster.
ReactiveEventingFunctionManager	eventingFunctions() Provides access to the eventing function management services for functions in the admin scope.
ReactiveCouchbaseHttpClient	httpClient() Returns a specialized HTTP client for making requests to the Couchbase Server REST API.
Mono<com.couchbase.client.core.diagnostics.PingResult>	ping() Performs application-level ping requests against services in the couchbase cluster.
Mono<com.couchbase.client.core.diagnostics.PingResult>	ping(PingOptions options) Performs application-level ping requests with custom options against services in the couchbase cluster.
Mono<ReactiveQueryResult>	query(String statement) Performs a N1QL query with default QueryOptions.
Mono<ReactiveQueryResult>	query(String statement, QueryOptions options) Performs a N1QL query with custom QueryOptions.
ReactiveQueryIndexManager	queryIndexes() Provides access to the N1QL index management services.
Mono<ReactiveSearchResult>	search(String indexName, SearchRequest searchRequest) Performs a request against the Full Text Search (FTS) service, with default SearchOptions.
Mono<ReactiveSearchResult>	search(String indexName, SearchRequest searchRequest, SearchOptions options) Performs a request against the Full Text Search (FTS) service, with custom SearchOptions.
ReactiveSearchIndexManager	searchIndexes() Provides access to the search index management services.
Mono<ReactiveSearchResult>	searchQuery(String indexName, SearchQuery query) Performs a Full Text Search (FTS) query with default SearchOptions.
Mono<ReactiveSearchResult>	searchQuery(String indexName, SearchQuery query, SearchOptions options) Performs a Full Text Search (FTS) query with custom SearchOptions.
ReactiveTransactions	transactions() Allows access to transactions.
ReactiveUserManager	users() Provides access to the user management services.
Mono<Void>	waitUntilReady(Duration timeout) Waits until the desired ClusterState is reached.
Mono<Void>	waitUntilReady(Duration timeout, WaitUntilReadyOptions options) Waits until the desired ClusterState is reached.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

connect

public static ReactiveCluster connect(String connectionString,
                                      String username,
                                      String password)

Connect to a Couchbase cluster with a username and a password as credentials.

Parameters:

connectionString - connection string used to locate the Couchbase cluster.

username - the name of the user with appropriate permissions on the cluster.

password - the password of the user with appropriate permissions on the cluster.

Returns:

the instantiated ReactiveCluster.

connect

public static ReactiveCluster connect(String connectionString,
                                      ClusterOptions options)

Connect to a Couchbase cluster with custom Authenticator.

Parameters:

connectionString - connection string used to locate the Couchbase cluster.

options - custom options when creating the cluster.

Returns:

the instantiated ReactiveCluster.

connect

public static ReactiveCluster connect(Set<com.couchbase.client.core.env.SeedNode> seedNodes,
                                      ClusterOptions options)

Connect to a Couchbase cluster with a list of seed nodes and custom options.

Please note that you likely only want to use this method if you need to pass in custom ports for specific seed nodes during bootstrap. Otherwise we recommend relying ont he simpler connect(String, ClusterOptions) method instead.

Parameters:

seedNodes - the seed nodes used to connect to the cluster.

options - custom options when creating the cluster.

Returns:

the instantiated ReactiveCluster.

core

@Stability.Volatile
public com.couchbase.client.core.Core core()

Provides access to the underlying Core.

This is advanced API, use with care!

httpClient

@Stability.Volatile
public ReactiveCouchbaseHttpClient httpClient()

Returns a specialized HTTP client for making requests to the Couchbase Server REST API.

users

public ReactiveUserManager users()

Provides access to the user management services.

buckets

public ReactiveBucketManager buckets()

Provides access to the bucket management services.

analyticsIndexes

public ReactiveAnalyticsIndexManager analyticsIndexes()

Provides access to the Analytics index management services.

searchIndexes

public ReactiveSearchIndexManager searchIndexes()

Provides access to the search index management services.

queryIndexes

public ReactiveQueryIndexManager queryIndexes()

Provides access to the N1QL index management services.

eventingFunctions

@Stability.Uncommitted
public ReactiveEventingFunctionManager eventingFunctions()

Provides access to the eventing function management services for functions in the admin scope.

async

public AsyncCluster async()

Provides access to the underlying AsyncCluster.

environment

public ClusterEnvironment environment()

Provides access to the configured ClusterEnvironment for this cluster.

query

public Mono<ReactiveQueryResult> query(String statement)

Performs a N1QL query with default QueryOptions.

Parameters:

statement - the N1QL query statement as a raw string.

Returns:

the ReactiveQueryResult once the response arrives successfully.

query

public Mono<ReactiveQueryResult> query(String statement,
                                       QueryOptions options)

Performs a N1QL query with custom QueryOptions.

Parameters:

statement - the N1QL query statement as a raw string.

options - the custom options for this query.

Returns:

the ReactiveQueryResult once the response arrives successfully.

analyticsQuery

public Mono<ReactiveAnalyticsResult> analyticsQuery(String statement)

Performs an Analytics query with default AnalyticsOptions.

Parameters:

statement - the Analytics query statement as a raw string.

Returns:

the ReactiveAnalyticsResult once the response arrives successfully.

analyticsQuery

public Mono<ReactiveAnalyticsResult> analyticsQuery(String statement,
                                                    AnalyticsOptions options)

Performs an Analytics query with custom AnalyticsOptions.

Parameters:

statement - the Analytics query statement as a raw string.

options - the custom options for this analytics query.

Returns:

the ReactiveAnalyticsResult once the response arrives successfully.

search

public Mono<ReactiveSearchResult> search(String indexName,
                                         SearchRequest searchRequest)

Performs a request against the Full Text Search (FTS) service, with default SearchOptions.

This can be used to perform a traditional FTS query, and/or a vector search.

This method is for global FTS indexes. For scoped indexes, use ReactiveScope instead.

Parameters:

searchRequest - the request, in the form of a SearchRequest

Returns:

the SearchResult once the response arrives successfully, inside a Mono.

Throws:

com.couchbase.client.core.error.TimeoutException - if the operation times out before getting a result.

com.couchbase.client.core.error.CouchbaseException - for all other error reasons (acts as a base type and catch-all).

search

public Mono<ReactiveSearchResult> search(String indexName,
                                         SearchRequest searchRequest,
                                         SearchOptions options)

Performs a request against the Full Text Search (FTS) service, with custom SearchOptions.

This can be used to perform a traditional FTS query, and/or a vector search.

This method is for global FTS indexes. For scoped indexes, use ReactiveScope instead.

Parameters:

searchRequest - the request, in the form of a SearchRequest

Returns:

the SearchResult once the response arrives successfully, inside a Mono.

Throws:

com.couchbase.client.core.error.TimeoutException - if the operation times out before getting a result.

com.couchbase.client.core.error.CouchbaseException - for all other error reasons (acts as a base type and catch-all).

searchQuery

public Mono<ReactiveSearchResult> searchQuery(String indexName,
                                              SearchQuery query)

Performs a Full Text Search (FTS) query with default SearchOptions.

This method is for global FTS indexes. For scoped indexes, use ReactiveScope instead.

New users should consider the newer search(String, SearchRequest) interface instead, which can do both the traditional FTS SearchQuery that this method performs, and/or can also be used to perform a VectorSearch.

Parameters:

query - the query, in the form of a SearchQuery

Returns:

the ReactiveSearchResult once the response arrives successfully, inside a Mono

searchQuery

public Mono<ReactiveSearchResult> searchQuery(String indexName,
                                              SearchQuery query,
                                              SearchOptions options)

Performs a Full Text Search (FTS) query with custom SearchOptions.

This method is for global FTS indexes. For scoped indexes, use ReactiveScope instead.

New users should consider the newer search(String, SearchRequest) interface instead, which can do both the traditional FTS SearchQuery that this method performs, and/or can also be used to perform a VectorSearch.

Parameters:

query - the query, in the form of a SearchQuery

options - the custom options for this query.

Returns:

the ReactiveSearchResult once the response arrives successfully, inside a Mono

bucket

public ReactiveBucket bucket(String bucketName)

Opens a ReactiveBucket with the given name.

Parameters:

bucketName - the name of the bucket to open.

Returns:

a ReactiveBucket once opened.

disconnect

public Mono<Void> disconnect()

Performs a non-reversible disconnect of this ReactiveCluster.

If this method is used, the default disconnect timeout on the environment is used. Please use the companion overload (disconnect(Duration) if you want to provide a custom duration.

If a custom ClusterEnvironment has been passed in during connect, it is VERY important to shut it down after calling this method. This will prevent any in-flight tasks to be stopped prematurely.

disconnect

public Mono<Void> disconnect(Duration timeout)

Performs a non-reversible disconnect of this ReactiveCluster.

If a custom ClusterEnvironment has been passed in during connect, it is VERY important to shut it down after calling this method. This will prevent any in-flight tasks to be stopped prematurely.

Parameters:

timeout - overriding the default disconnect timeout if needed.

diagnostics

public Mono<com.couchbase.client.core.diagnostics.DiagnosticsResult> diagnostics()

Runs a diagnostic report on the current state of the cluster from the SDKs point of view.

Please note that it does not perform any I/O to do this, it will only use the current known state of the cluster to assemble the report (so, if for example no N1QL query has been run the socket pool might be empty and as result not show up in the report).

Returns:

the DiagnosticsResult once complete.

diagnostics

public Mono<com.couchbase.client.core.diagnostics.DiagnosticsResult> diagnostics(DiagnosticsOptions options)

Runs a diagnostic report with custom options on the current state of the cluster from the SDKs point of view.

Please note that it does not perform any I/O to do this, it will only use the current known state of the cluster to assemble the report (so, if for example no N1QL query has been run the socket pool might be empty and as result not show up in the report).

Parameters:

options - options that allow to customize the report.

Returns:

the DiagnosticsResult once complete.

ping

public Mono<com.couchbase.client.core.diagnostics.PingResult> ping()

Performs application-level ping requests against services in the couchbase cluster.

Note that this operation performs active I/O against services and endpoints to assess their health. If you do not wish to perform I/O, consider using the diagnostics() instead. You can also combine the functionality of both APIs as needed, which is waitUntilReady(Duration) is doing in its implementation as well.

Returns:

the PingResult once complete.

ping

public Mono<com.couchbase.client.core.diagnostics.PingResult> ping(PingOptions options)

Performs application-level ping requests with custom options against services in the couchbase cluster.

Note that this operation performs active I/O against services and endpoints to assess their health. If you do not wish to perform I/O, consider using the diagnostics(DiagnosticsOptions) instead. You can also combine the functionality of both APIs as needed, which is waitUntilReady(Duration) is doing in its implementation as well.

Returns:

the PingResult once complete.

waitUntilReady

public Mono<Void> waitUntilReady(Duration timeout)

Waits until the desired ClusterState is reached.

This method will wait until either the cluster state is "online", or the timeout is reached. Since the SDK is bootstrapping lazily, this method allows to eagerly check during bootstrap if all of the services are online and usable before moving on.

Parameters:

timeout - the maximum time to wait until readiness.

Returns:

a mono that completes either once ready or timeout.

waitUntilReady

public Mono<Void> waitUntilReady(Duration timeout,
                                 WaitUntilReadyOptions options)

Waits until the desired ClusterState is reached.

This method will wait until either the cluster state is "online" by default, or the timeout is reached. Since the SDK is bootstrapping lazily, this method allows to eagerly check during bootstrap if all of the services are online and usable before moving on. You can tune the properties through WaitUntilReadyOptions.

Parameters:

timeout - the maximum time to wait until readiness.

options - the options to customize the readiness waiting.

Returns:

a mono that completes either once ready or timeout.

transactions

@Stability.Uncommitted
public ReactiveTransactions transactions()

Allows access to transactions.

Returns:

the Transactions interface.