com.datastax.driver.dse

Class DseCluster.Builder

java.lang.Object

com.datastax.driver.core.Cluster.Builder

com.datastax.driver.dse.DseCluster.Builder

All Implemented Interfaces:

Cluster.Initializer

Enclosing class:

DseCluster

public static class DseCluster.Builder
extends Cluster.Builder

Helper class to build DseCluster instances.

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
DseCluster.Builder	addContactPoint(String address) Adds a contact point - or many if the given address resolves to multiple InetAddress s (A records).
DseCluster.Builder	addContactPoints(Collection<InetAddress> addresses) Adds contact points.
DseCluster.Builder	addContactPoints(InetAddress... addresses) Adds contact points.
DseCluster.Builder	addContactPoints(String... addresses) Adds contact points.
DseCluster.Builder	addContactPointsWithPorts(Collection<InetSocketAddress> addresses) Adds contact points.
DseCluster	build() Builds the cluster with the configured set of initial contact points and policies.
DseConfiguration	getConfiguration() The configuration that will be used for the new cluster.
DseCluster.Builder	withAddressTranslator(AddressTranslator translator) Configures the address translator to use for the new cluster.
DseCluster.Builder	withApplicationName(String name) An optional configuration identifying the name of the application using this cluster.
DseCluster.Builder	withApplicationVersion(String version) An optional configuration identifying the version of the application using this cluster.
DseCluster.Builder	withAuthProvider(AuthProvider authProvider) Use the specified AuthProvider when connecting to Cassandra hosts.
DseCluster.Builder	withClusterId(UUID id) An optional configuration for providing a unique identifier for the created cluster instance.
DseCluster.Builder	withClusterName(String name) An optional name for the create cluster.
DseCluster.Builder	withCodecRegistry(CodecRegistry codecRegistry) Configures the CodecRegistry instance to use for the new cluster.
DseCluster.Builder	withCompression(ProtocolOptions.Compression compression) Sets the compression to use for the transport.
DseCluster.Builder	withCredentials(String username, String password) Uses the provided credentials when connecting to Cassandra hosts.
DseCluster.Builder	withGraphOptions(GraphOptions graphOptions) Sets the default options to use with graph queries.
DseCluster.Builder	withInitialListeners(Collection<Host.StateListener> listeners) Register the provided listeners in the newly created cluster.
DseCluster.Builder	withLoadBalancingPolicy(LoadBalancingPolicy policy) Configures the load balancing policy to use for the new DSE cluster.
DseCluster.Builder	withMaxSchemaAgreementWaitSeconds(int maxSchemaAgreementWaitSeconds) Sets the maximum time to wait for schema agreement before returning from a DDL query.
DseCluster.Builder	withNettyOptions(NettyOptions nettyOptions) Set the NettyOptions to use for the newly created Cluster.
DseCluster.Builder	withoutGeospatialCodecs() Prevents the registration of geospatial codecs with the new cluster.
DseCluster.Builder	withoutJMXReporting() Disables JMX reporting of the metrics.
DseCluster.Builder	withoutMetrics() Disables metrics collection for the created cluster (metrics are enabled by default otherwise).
DseCluster.Builder	withoutSearchCodecs() Prevents the registration of search codecs with the new cluster.
DseCluster.Builder	withPoolingOptions(PoolingOptions options) Sets the PoolingOptions to use for the newly created Cluster.
DseCluster.Builder	withPort(int port) The port to use to connect to the Cassandra host.
DseCluster.Builder	withProtocolVersion(ProtocolVersion version) The native protocol version to use.
DseCluster.Builder	withQueryOptions(QueryOptions options) Sets the QueryOptions to use for the newly created Cluster.
DseCluster.Builder	withReconnectionPolicy(ReconnectionPolicy policy) Configures the reconnection policy to use for the new cluster.
DseCluster.Builder	withRetryPolicy(RetryPolicy policy) Configures the retry policy to use for the new cluster.
DseCluster.Builder	withSocketOptions(SocketOptions options) Sets the SocketOptions to use for the newly created Cluster.
DseCluster.Builder	withSpeculativeExecutionPolicy(SpeculativeExecutionPolicy policy) Configures the speculative execution policy to use for the new cluster.
DseCluster.Builder	withSSL() Enables the use of SSL for the created Cluster.
DseCluster.Builder	withSSL(SSLOptions sslOptions) Enable the use of SSL for the created Cluster using the provided options.
DseCluster.Builder	withTimestampGenerator(TimestampGenerator timestampGenerator) Configures the generator that will produce the client-side timestamp sent with each query.

Methods inherited from class com.datastax.driver.core.Cluster.Builder

addContactPointsWithPorts, allowBetaProtocolVersion, getClusterName, getContactPoints, getInitialListeners, withNoCompact, withThreadingOptions

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder()

Method Detail

withGraphOptions

public DseCluster.Builder withGraphOptions(GraphOptions graphOptions)

Sets the default options to use with graph queries.

If you don't provide this, the new cluster will get a GraphOptions instance with the default values.

Parameters:

graphOptions - the graph options.

Returns:

this builder (for method chaining).

withoutGeospatialCodecs

public DseCluster.Builder withoutGeospatialCodecs()

Prevents the registration of geospatial codecs with the new cluster.

If this method is not called, those codecs will be registered by default.

Returns:

this builder (for method chaining).

See Also:

CodecRegistry, TypeCodec

withoutSearchCodecs

public DseCluster.Builder withoutSearchCodecs()

Prevents the registration of search codecs with the new cluster.

Currently only DateRangeCodec is affected by this method. If this method is not called, this codec will be registered by default.

Returns:

this builder (for method chaining).

See Also:

CodecRegistry, TypeCodec

withClusterName

public DseCluster.Builder withClusterName(String name)

Description copied from class: Cluster.Builder

An optional name for the create cluster.

Note: this is not related to the Cassandra cluster name (though you are free to provide the same name). See Cluster.getClusterName() for details.

If you use this method and create more than one Cluster instance in the same JVM (which should be avoided unless you need to connect to multiple Cassandra clusters), you should make sure each Cluster instance get a unique name or you may have a problem with JMX reporting.

Overrides:

withClusterName in class Cluster.Builder

Parameters:

name - the cluster name to use for the created Cluster instance.

Returns:

this Builder.

withClusterId

public DseCluster.Builder withClusterId(UUID id)

An optional configuration for providing a unique identifier for the created cluster instance.

If not provided, an id will generated.

This value is passed to DSE and is useful as metadata for describing a client connection.

Parameters:

id - the id to assign to this cluster instance.

Returns:

this Builder.

withApplicationName

public DseCluster.Builder withApplicationName(String name)

An optional configuration identifying the name of the application using this cluster.

This value is passed to DSE and is useful as metadata for describing a client connection.

Parameters:

name - the name of the application using this cluster.

Returns:

this Builder.

withApplicationVersion

public DseCluster.Builder withApplicationVersion(String version)

An optional configuration identifying the version of the application using this cluster.

This value is to passed to DSE and is useful as metadata for describing a client connection.

Parameters:

version - the version of the application using this cluster.

Returns:

this Builder.

withPort

public DseCluster.Builder withPort(int port)

Description copied from class: Cluster.Builder

The port to use to connect to the Cassandra host.

If not set through this method, the default port (9042) will be used instead.

Overrides:

withPort in class Cluster.Builder

Parameters:

port - the port to set.

Returns:

this Builder.

withMaxSchemaAgreementWaitSeconds

public DseCluster.Builder withMaxSchemaAgreementWaitSeconds(int maxSchemaAgreementWaitSeconds)

Description copied from class: Cluster.Builder

Sets the maximum time to wait for schema agreement before returning from a DDL query.

If not set through this method, the default value (10 seconds) will be used.

Overrides:

withMaxSchemaAgreementWaitSeconds in class Cluster.Builder

Parameters:

maxSchemaAgreementWaitSeconds - the new value to set.

Returns:

this Builder.

withProtocolVersion

public DseCluster.Builder withProtocolVersion(ProtocolVersion version)

Description copied from class: Cluster.Builder

The native protocol version to use.

The driver supports versions 1 to 5 of the native protocol. Higher versions of the protocol have more features and should be preferred, but this also depends on the Cassandra version:

Native protocol version to Cassandra version correspondence

Protocol version	Minimum Cassandra version
1	1.2
2	2.0
3	2.1
4	2.2
5	3.10

By default, the driver will "auto-detect" which protocol version it can use when connecting to the first node. More precisely, it will try first with ProtocolVersion.NEWEST_SUPPORTED, and if not supported fallback to the highest version supported by the first node it connects to. Please note that once the version is "auto-detected", it won't change: if the first node the driver connects to is a Cassandra 1.2 node and auto-detection is used (the default), then the native protocol version 1 will be use for the lifetime of the Cluster instance.

By using Cluster.Builder.allowBetaProtocolVersion(), it is possible to force driver to connect to Cassandra node that supports the latest protocol beta version. Leaving this flag out will let client to connect with latest released version.

This method allows to force the use of a particular protocol version. Forcing version 1 is always fine since all Cassandra version (at least all those supporting the native protocol in the first place) so far support it. However, please note that a number of features of the driver won't be available if that version of the protocol is in use, including result set paging, BatchStatement, executing a non-prepared query with binary values (Session.execute(String, Object...)), ... (those methods will throw an UnsupportedFeatureException). Using the protocol version 1 should thus only be considered when using Cassandra 1.2, until nodes have been upgraded to Cassandra 2.0.

If version 2 of the protocol is used, then Cassandra 1.2 nodes will be ignored (the driver won't connect to them).

The default behavior (auto-detection) is fine in almost all case, but you may want to force a particular version if you have a Cassandra cluster with mixed 1.2/2.0 nodes (i.e. during a Cassandra upgrade).

Overrides:

withProtocolVersion in class Cluster.Builder

Parameters:

version - the native protocol version to use. null is also supported to trigger auto-detection (see above) but this is the default (so you don't have to call this method for that behavior).

Returns:

this Builder.

addContactPoint

public DseCluster.Builder addContactPoint(String address)

Description copied from class: Cluster.Builder

Adds a contact point - or many if the given address resolves to multiple InetAddress s (A records).

Contact points are addresses of Cassandra nodes that the driver uses to discover the cluster topology. Only one contact point is required (the driver will retrieve the address of the other nodes automatically), but it is usually a good idea to provide more than one contact point, because if that single contact point is unavailable, the driver cannot initialize itself correctly.

Note that by default (that is, unless you use the Cluster.Builder.withLoadBalancingPolicy(com.datastax.driver.core.policies.LoadBalancingPolicy)) method of this builder), the first successfully contacted host will be used to define the local data-center for the client. If follows that if you are running Cassandra in a multiple data-center setting, it is a good idea to only provide contact points that are in the same datacenter than the client, or to provide manually the load balancing policy that suits your need.

If the host name points to a DNS record with multiple a-records, all InetAddresses returned will be used. Make sure that all resulting InetAddresss returned point to the same cluster and datacenter.

Overrides:

addContactPoint in class Cluster.Builder

Parameters:

address - the address of the node(s) to connect to.

Returns:

this Builder.

addContactPoints

public DseCluster.Builder addContactPoints(String... addresses)

Description copied from class: Cluster.Builder

Adds contact points.

See Cluster.Builder.addContactPoint(java.lang.String) for more details on contact points.

Note that all contact points must be resolvable; if any of them cannot be resolved, this method will fail.

Overrides:

addContactPoints in class Cluster.Builder

Parameters:

addresses - addresses of the nodes to add as contact points.

Returns:

this Builder.

See Also:

Cluster.Builder.addContactPoint(java.lang.String)

addContactPoints

public DseCluster.Builder addContactPoints(InetAddress... addresses)

Description copied from class: Cluster.Builder

Adds contact points.

See Cluster.Builder.addContactPoint(java.lang.String) for more details on contact points.

Note that all contact points must be resolvable; if any of them cannot be resolved, this method will fail.

Overrides:

addContactPoints in class Cluster.Builder

Parameters:

addresses - addresses of the nodes to add as contact points.

Returns:

this Builder.

See Also:

Cluster.Builder.addContactPoint(java.lang.String)

addContactPoints

public DseCluster.Builder addContactPoints(Collection<InetAddress> addresses)

Description copied from class: Cluster.Builder

Adds contact points.

See Cluster.Builder.addContactPoint(java.lang.String) for more details on contact points.

Overrides:

addContactPoints in class Cluster.Builder

Parameters:

addresses - addresses of the nodes to add as contact points.

Returns:

this Builder

See Also:

Cluster.Builder.addContactPoint(java.lang.String)

addContactPointsWithPorts

public DseCluster.Builder addContactPointsWithPorts(Collection<InetSocketAddress> addresses)

Description copied from class: Cluster.Builder

Adds contact points.

See Cluster.Builder.addContactPoint(java.lang.String) for more details on contact points. Contrarily to other addContactPoints methods, this method allows to provide a different port for each contact point. Since Cassandra nodes must always all listen on the same port, this is rarely what you want and most users should prefer other addContactPoints methods to this one. However, this can be useful if the Cassandra nodes are behind a router and are not accessed directly. Note that if you are in this situation (Cassandra nodes are behind a router, not directly accessible), you almost surely want to provide a specific AddressTranslator (through Cluster.Builder.withAddressTranslator(com.datastax.driver.core.policies.AddressTranslator)) to translate actual Cassandra node addresses to the addresses the driver should use, otherwise the driver will not be able to auto-detect new nodes (and will generally not function optimally).

Overrides:

addContactPointsWithPorts in class Cluster.Builder

Parameters:

addresses - addresses of the nodes to add as contact points.

Returns:

this Builder

See Also:

Cluster.Builder.addContactPoint(java.lang.String)

withLoadBalancingPolicy

public DseCluster.Builder withLoadBalancingPolicy(LoadBalancingPolicy policy)

Configures the load balancing policy to use for the new DSE cluster.

If you use graph analytics queries, it should be wrapped into a DseLoadBalancingPolicy to ensure that queries are routed optimally.

If no load balancing policy is set through this method, the default is to use a Policies.defaultLoadBalancingPolicy() wrapped into a TargetingLoadBalancingPolicy.

Overrides:

withLoadBalancingPolicy in class Cluster.Builder

Parameters:

policy - the load balancing policy to use.

Returns:

this builder.

withReconnectionPolicy

public DseCluster.Builder withReconnectionPolicy(ReconnectionPolicy policy)

Description copied from class: Cluster.Builder

Configures the reconnection policy to use for the new cluster.

If no reconnection policy is set through this method, Policies.DEFAULT_RECONNECTION_POLICY will be used instead.

Overrides:

withReconnectionPolicy in class Cluster.Builder

Parameters:

policy - the reconnection policy to use.

Returns:

this Builder.

withRetryPolicy

public DseCluster.Builder withRetryPolicy(RetryPolicy policy)

Description copied from class: Cluster.Builder

Configures the retry policy to use for the new cluster.

If no retry policy is set through this method, Policies.DEFAULT_RETRY_POLICY will be used instead.

Overrides:

withRetryPolicy in class Cluster.Builder

Parameters:

policy - the retry policy to use.

Returns:

this Builder.

withAddressTranslator

public DseCluster.Builder withAddressTranslator(AddressTranslator translator)

Description copied from class: Cluster.Builder

Configures the address translator to use for the new cluster.

See AddressTranslator for more detail on address translation, but the default translator, IdentityTranslator, should be correct in most cases. If unsure, stick to the default.

Overrides:

withAddressTranslator in class Cluster.Builder

Parameters:

translator - the translator to use.

Returns:

this Builder.

withTimestampGenerator

public DseCluster.Builder withTimestampGenerator(TimestampGenerator timestampGenerator)

Description copied from class: Cluster.Builder

Configures the generator that will produce the client-side timestamp sent with each query.

This feature is only available with version V3 or above of the native protocol. With earlier versions, timestamps are always generated server-side, and setting a generator through this method will have no effect.

If no generator is set through this method, the driver will default to client-side timestamps by using AtomicMonotonicTimestampGenerator.

Overrides:

withTimestampGenerator in class Cluster.Builder

Parameters:

timestampGenerator - the generator to use.

Returns:

this Builder.

withSpeculativeExecutionPolicy

public DseCluster.Builder withSpeculativeExecutionPolicy(SpeculativeExecutionPolicy policy)

Description copied from class: Cluster.Builder

Configures the speculative execution policy to use for the new cluster.

If no policy is set through this method, Policies.defaultSpeculativeExecutionPolicy() will be used instead.

Overrides:

withSpeculativeExecutionPolicy in class Cluster.Builder

Parameters:

policy - the policy to use.

Returns:

this Builder.

withCodecRegistry

public DseCluster.Builder withCodecRegistry(CodecRegistry codecRegistry)

Description copied from class: Cluster.Builder

Configures the CodecRegistry instance to use for the new cluster.

If no codec registry is set through this method, CodecRegistry.DEFAULT_INSTANCE will be used instead.

Note that if two or more Cluster instances are configured to use the default codec registry, they are going to share the same instance. In this case, care should be taken when registering new codecs on it as any codec registered by one cluster would be immediately available to others sharing the same default instance.

Overrides:

withCodecRegistry in class Cluster.Builder

Parameters:

codecRegistry - the codec registry to use.

Returns:

this Builder.

withCredentials

public DseCluster.Builder withCredentials(String username,
                                          String password)

Description copied from class: Cluster.Builder

Uses the provided credentials when connecting to Cassandra hosts.

This should be used if the Cassandra cluster has been configured to use the PasswordAuthenticator. If the the default AllowAllAuthenticator is used instead, using this method has no effect.

Overrides:

withCredentials in class Cluster.Builder

Parameters:

username - the username to use to login to Cassandra hosts.

password - the password corresponding to username.

Returns:

this Builder.

withAuthProvider

public DseCluster.Builder withAuthProvider(AuthProvider authProvider)

Description copied from class: Cluster.Builder

Use the specified AuthProvider when connecting to Cassandra hosts.

Use this method when a custom authentication scheme is in place. You shouldn't call both this method and withCredentials on the same Builder instance as one will supersede the other

Overrides:

withAuthProvider in class Cluster.Builder

Parameters:

authProvider - the AuthProvider to use to login to Cassandra hosts.

Returns:

this Builder

withCompression

public DseCluster.Builder withCompression(ProtocolOptions.Compression compression)

Description copied from class: Cluster.Builder

Sets the compression to use for the transport.

Overrides:

withCompression in class Cluster.Builder

Parameters:

compression - the compression to set.

Returns:

this Builder.

See Also:

ProtocolOptions.Compression

withoutMetrics

public DseCluster.Builder withoutMetrics()

Description copied from class: Cluster.Builder

Disables metrics collection for the created cluster (metrics are enabled by default otherwise).

Overrides:

withoutMetrics in class Cluster.Builder

Returns:

this builder.

withSSL

public DseCluster.Builder withSSL()

Description copied from class: Cluster.Builder

Enables the use of SSL for the created Cluster.

Calling this method will use the JDK-based implementation with the default options (see RemoteEndpointAwareJdkSSLOptions.Builder). This is thus a shortcut for withSSL(JdkSSLOptions.builder().build()).

Note that if SSL is enabled, the driver will not connect to any Cassandra nodes that doesn't have SSL enabled and it is strongly advised to enable SSL on every Cassandra node if you plan on using SSL in the driver.

Overrides:

withSSL in class Cluster.Builder

Returns:

this builder.

withSSL

public DseCluster.Builder withSSL(SSLOptions sslOptions)

Description copied from class: Cluster.Builder

Enable the use of SSL for the created Cluster using the provided options.

Overrides:

withSSL in class Cluster.Builder

Parameters:

sslOptions - the SSL options to use.

Returns:

this builder.

withInitialListeners

public DseCluster.Builder withInitialListeners(Collection<Host.StateListener> listeners)

Description copied from class: Cluster.Builder

Register the provided listeners in the newly created cluster.

Note: repeated calls to this method will override the previous ones.

Overrides:

withInitialListeners in class Cluster.Builder

Parameters:

listeners - the listeners to register.

Returns:

this builder.

withoutJMXReporting

public DseCluster.Builder withoutJMXReporting()

Description copied from class: Cluster.Builder

Disables JMX reporting of the metrics.

JMX reporting is enabled by default (see Metrics) but can be disabled using this option. If metrics are disabled, this is a no-op.

Overrides:

withoutJMXReporting in class Cluster.Builder

Returns:

this builder.

withPoolingOptions

public DseCluster.Builder withPoolingOptions(PoolingOptions options)

Description copied from class: Cluster.Builder

Sets the PoolingOptions to use for the newly created Cluster.

If no pooling options are set through this method, default pooling options will be used.

Overrides:

withPoolingOptions in class Cluster.Builder

Parameters:

options - the pooling options to use.

Returns:

this builder.

withSocketOptions

public DseCluster.Builder withSocketOptions(SocketOptions options)

Description copied from class: Cluster.Builder

Sets the SocketOptions to use for the newly created Cluster.

If no socket options are set through this method, default socket options will be used.

Overrides:

withSocketOptions in class Cluster.Builder

Parameters:

options - the socket options to use.

Returns:

this builder.

withQueryOptions

public DseCluster.Builder withQueryOptions(QueryOptions options)

Description copied from class: Cluster.Builder

Sets the QueryOptions to use for the newly created Cluster.

If no query options are set through this method, default query options will be used.

Overrides:

withQueryOptions in class Cluster.Builder

Parameters:

options - the query options to use.

Returns:

this builder.

withNettyOptions

public DseCluster.Builder withNettyOptions(NettyOptions nettyOptions)

Description copied from class: Cluster.Builder

Set the NettyOptions to use for the newly created Cluster.

If no Netty options are set through this method, NettyOptions.DEFAULT_INSTANCE will be used as a default value, which means that no customization will be applied.

Overrides:

withNettyOptions in class Cluster.Builder

Parameters:

nettyOptions - the NettyOptions to use.

Returns:

this builder.

build

public DseCluster build()

Description copied from class: Cluster.Builder

Builds the cluster with the configured set of initial contact points and policies.

This is a convenience method for Cluster.buildFrom(this).

Overrides:

build in class Cluster.Builder

Returns:

the newly built Cluster instance.

getConfiguration

public DseConfiguration getConfiguration()

Description copied from class: Cluster.Builder

The configuration that will be used for the new cluster.

You should not modify this object directly because changes made to the returned object may not be used by the cluster build. Instead, you should use the other methods of this Builder.

Specified by:

getConfiguration in interface Cluster.Initializer

Overrides:

getConfiguration in class Cluster.Builder

Returns:

the configuration to use for the new cluster.