com.datastax.driver.core

Class Cluster.Builder

java.lang.Object

com.datastax.driver.core.Cluster.Builder

All Implemented Interfaces:

Cluster.Initializer

Enclosing class:

Cluster

public static class Cluster.Builder
extends Object
implements Cluster.Initializer

Helper class to build Cluster instances.

Constructor Summary

Constructors

Constructor and Description
Cluster.Builder()

Method Summary

Methods

Modifier and Type	Method and Description
Cluster.Builder	addContactPoint(String address) Adds a contact point.
Cluster.Builder	addContactPoints(Collection<InetAddress> addresses) Adds contact points.
Cluster.Builder	addContactPoints(InetAddress... addresses) Adds contact points.
Cluster.Builder	addContactPoints(String... addresses) Adds contact points.
Cluster	build() Builds the cluster with the configured set of initial contact points and policies.
Configuration	getConfiguration() The configuration that will be used for the new cluster.
List<InetAddress>	getContactPoints() Returns the initial Cassandra hosts to connect to.
PoolingOptions	poolingOptions() Deprecated. you are now encouraged to use the withPoolingOptions(com.datastax.driver.core.PoolingOptions) method. This method is deprecated and will be removed in the next major version of the driver.
SocketOptions	socketOptions() Deprecated. you are now encouraged to use the withPoolingOptions(com.datastax.driver.core.PoolingOptions) method. This method is deprecated and will be removed in the next major version of the driver.
Cluster.Builder	withCompression(ProtocolOptions.Compression compression) Sets the compression to use for the transport.
Cluster.Builder	withCredentials(String username, String password) Uses the provided credentials when connecting to Cassandra hosts.
Cluster.Builder	withDeferredInitialization() Defer the initialization of the created cluster.
Cluster.Builder	withLoadBalancingPolicy(LoadBalancingPolicy policy) Configures the load balancing policy to use for the new cluster.
Cluster.Builder	withoutJMXReporting() Disables JMX reporting of the metrics.
Cluster.Builder	withoutMetrics() Disables metrics collection for the created cluster (metrics are enabled by default otherwise).
Cluster.Builder	withPoolingOptions(PoolingOptions options) Set the PoolingOptions to use for the newly created Cluster.
Cluster.Builder	withPort(int port) The port to use to connect to the Cassandra host.
Cluster.Builder	withReconnectionPolicy(ReconnectionPolicy policy) Configures the reconnection policy to use for the new cluster.
Cluster.Builder	withRetryPolicy(RetryPolicy policy) Configures the retry policy to use for the new cluster.
Cluster.Builder	withSocketOptions(SocketOptions options) Set the SocketOptions to use for the newly created Cluster.
Cluster.Builder	withSSL() Enables the use of SSL for the created Cluster.
Cluster.Builder	withSSL(SSLOptions sslOptions) Enable the use of SSL for the created Cluster using the provided options.

Methods inherited from class java.lang.Object

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

Constructor Detail

Cluster.Builder

public Cluster.Builder()

Method Detail

getContactPoints

public List<InetAddress> getContactPoints()

Description copied from interface: Cluster.Initializer

Returns the initial Cassandra hosts to connect to.

Specified by:

getContactPoints in interface Cluster.Initializer

Returns:

the initial Cassandra contact points. See addContactPoint(java.lang.String) for more details on contact points.

withPort

public Cluster.Builder withPort(int port)

The port to use to connect to the Cassandra host. If not set through this method, the default port (9042) will be used instead.

Parameters:

port - the port to set.

Returns:

this Builder

addContactPoint

public Cluster.Builder addContactPoint(String address)

Adds a contact point. 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.

Parameters:

address - the address of the node to connect to

Returns:

this Builder

Throws:

IllegalArgumentException - if no IP address for address could be found

SecurityException - if a security manager is present and permission to resolve the host name is denied.

addContactPoints

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

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

Parameters:

addresses - addresses of the nodes to add as contact point

Returns:

this Builder

Throws:

IllegalArgumentException - if no IP address for at least one of addresses could be found

SecurityException - if a security manager is present and permission to resolve the host name is denied.

See Also:

addContactPoint(java.lang.String)

addContactPoints

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

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

Parameters:

addresses - addresses of the nodes to add as contact point

Returns:

this Builder

See Also:

addContactPoint(java.lang.String)

addContactPoints

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

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

Parameters:

addresses - addresses of the nodes to add as contact point

Returns:

this Builder

See Also:

addContactPoint(java.lang.String)

withLoadBalancingPolicy

public Cluster.Builder withLoadBalancingPolicy(LoadBalancingPolicy policy)

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

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

Parameters:

policy - the load balancing policy to use

Returns:

this Builder

withReconnectionPolicy

public Cluster.Builder withReconnectionPolicy(ReconnectionPolicy policy)

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.

Parameters:

policy - the reconnection policy to use

Returns:

this Builder

withRetryPolicy

public Cluster.Builder withRetryPolicy(RetryPolicy policy)

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.

Parameters:

policy - the retry policy to use

Returns:

this Builder

withCredentials

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

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.

Parameters:

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

password - the password corresponding to username.

Returns:

this Builder

withCompression

public Cluster.Builder withCompression(ProtocolOptions.Compression compression)

Sets the compression to use for the transport.

Parameters:

compression - the compression to set

Returns:

this Builder

See Also:

ProtocolOptions.Compression

withoutMetrics

public Cluster.Builder withoutMetrics()

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

Returns:

this builder

withSSL

public Cluster.Builder withSSL()

Enables the use of SSL for the created Cluster.

Calling this method will use default SSL options (see SSLOptions.SSLOptions()). This is thus a shortcut for withSSL(new SSLOptions()). 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.

Returns:

this builder

withSSL

public Cluster.Builder withSSL(SSLOptions sslOptions)

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

Parameters:

sslOptions - the SSL options to use.

Returns:

this builder

withoutJMXReporting

public Cluster.Builder withoutJMXReporting()

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.

Returns:

this builder

poolingOptions

@Deprecated
public PoolingOptions poolingOptions()

Deprecated. you are now encouraged to use the withPoolingOptions(com.datastax.driver.core.PoolingOptions) method. This method is deprecated and will be removed in the next major version of the driver.

Return the pooling options used by this builder.

Returns:

the pooling options that will be used by this builder. You can use the returned object to define the initial pooling options for the built cluster.

withPoolingOptions

public Cluster.Builder withPoolingOptions(PoolingOptions options)

Set the PoolingOptions to use for the newly created Cluster.

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

Parameters:

options - the pooling options to use.

Returns:

this builder.

socketOptions

@Deprecated
public SocketOptions socketOptions()

Deprecated. you are now encouraged to use the withPoolingOptions(com.datastax.driver.core.PoolingOptions) method. This method is deprecated and will be removed in the next major version of the driver.

Returns the socket options used by this builder.

Returns:

the socket options that will be used by this builder. You can use the returned object to define the initial socket options for the built cluster.

withSocketOptions

public Cluster.Builder withSocketOptions(SocketOptions options)

Set the SocketOptions to use for the newly created Cluster.

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

Parameters:

options - the socket options to use.

Returns:

this builder.

withDeferredInitialization

public Cluster.Builder withDeferredInitialization()

Defer the initialization of the created cluster.

By default, building the cluster (calling the build() method of this object) triggers the creation of a connection to one of the contact points. That connection is then used to fetch the metadata on the Cassandra cluster we are connected to (other nodes, schema, ...). If this method is used, the creation of that connection will be deferred until the first call to connect() or getMetadata() on the resulting Cluster object.

This method is useful when it is not convenient to deal with connection problems while creating the Cluster object. Note that this method only exists in the 1.X branch of the driver since deferred initialization is the default on the 2.X branch.

Returns:

this builder.

getConfiguration

public Configuration getConfiguration()

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

Returns:

the configuration to use for the new cluster.

build

public Cluster build()

Builds the cluster with the configured set of initial contact points and policies. This is a convenience method for Cluster.buildFrom(this).

Returns:

the newly built Cluster instance.

Throws:

NoHostAvailableException - if none of the contact points provided can be reached.

AuthenticationException - if an authentication error occurs. while contacting the initial contact points