com.datastax.driver.core

Class Cluster

java.lang.Object

com.datastax.driver.core.Cluster

public class Cluster
extends Object

information and known state of a Cassandra cluster.

This is the main entry point of the driver. A simple example of access to a Cassandra cluster would be:

   Cluster cluster = Cluster.builder().addContactPoint("192.168.0.1").build();
   Session session = cluster.connect("db1");

   for (Row row : session.execute("SELECT * FROM table1"))
       // do something ...
 

A cluster object maintains a permanent connection to one of the cluster nodes which it uses solely to maintain information on the state and current topology of the cluster. Using the connection, the driver will discover all the nodes currently in the cluster as well as new nodes joining the cluster subsequently.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Cluster.Builder Helper class to build Cluster instances.
static interface	Cluster.Initializer Initializer for Cluster instances.

Method Summary

Methods

Modifier and Type	Method and Description
static Cluster.Builder	builder() Creates a new Cluster.Builder instance.
static Cluster	buildFrom(Cluster.Initializer initializer) Build a new cluster based on the provided initializer.
Session	connect() Creates a new session on this cluster.
Session	connect(String keyspace) Creates a new session on this cluster and sets the keyspace to the provided one.
String	getClusterName() The name of this cluster object.
Configuration	getConfiguration() The cluster configuration.
Metadata	getMetadata() Returns read-only metadata on the connected cluster.
Metrics	getMetrics() The cluster metrics.
Cluster	init() Initialize this Cluster instance.
Cluster	register(Host.StateListener listener) Registers the provided listener to be notified on hosts up/down/added/removed events.
Cluster	register(LatencyTracker tracker) Registers the provided tracker to be updated with hosts read latencies.
ShutdownFuture	shutdown() Initiates a shutdown of this cluster instance.
Cluster	unregister(Host.StateListener listener) Unregisters the provided listener from being notified on hosts events.
Cluster	unregister(LatencyTracker tracker) Unregisters the provided latency tracking from being updated with host read latencies.

Methods inherited from class java.lang.Object

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

Method Detail

init

public Cluster init()

Initialize this Cluster instance. This method creates an initial connection to one of the contact points used to construct the Cluster instance. That connection is then used to populate the cluster Metadata.

Calling this method is optional in the sense that any call to one of the connect methods of this object will automatically trigger a call to this method beforehand. It is thus only useful to call this method if for some reason you want to populate the metadata (or test that at least one contact point can be reached) without creating a first Session.

Please note that this method only create one connection for metadata gathering reasons. In particular, it doesn't create any connection pool. Those are created when a new Session is created through connect.

This method has no effect if the cluster is already initialized.

Returns:

this Cluster object.

Throws:

NoHostAvailableException - if no host amongst the contact points can be reached.

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

buildFrom

public static Cluster buildFrom(Cluster.Initializer initializer)

Build a new cluster based on the provided initializer.

Note that for building a cluster programmatically, Cluster.Builder provides a slightly less verbose shortcut with Cluster.Builder.build().

Also note that that all the contact points provided by initializer must share the same port.

Parameters:

initializer - the Cluster.Initializer to use

Returns:

the newly created Cluster instance

Throws:

IllegalArgumentException - if the list of contact points provided by initializer is empty or if not all those contact points have the same port.

builder

public static Cluster.Builder builder()

Creates a new Cluster.Builder instance.

This is a convenenience method for new Cluster.Builder().

Returns:

the new cluster builder.

connect

public Session connect()

Creates a new session on this cluster.

Returns:

a new session on this cluster sets to no keyspace.

Throws:

NoHostAvailableException - if the Cluster has not been initialized yet (init() has not be called and this is the first connect call) and no host amongst the contact points can be reached.

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

connect

public Session connect(String keyspace)

Creates a new session on this cluster and sets the keyspace to the provided one.

Parameters:

keyspace - The name of the keyspace to use for the created Session.

Returns:

a new session on this cluster sets to keyspace keyspaceName.

Throws:

NoHostAvailableException - if the Cluster has not been initialized yet (init() has not be called and this is the first connect call) and no host amongst the contact points can be reached, or if no host can be contacted to set the keyspace.

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

getClusterName

public String getClusterName()

The name of this cluster object.

Note that this is not the Cassandra cluster name, but rather a name assigned to this Cluster object. Currently, that name is only used for one purpose: to distinguish exposed JMX metrics when multiple Cluster instances live in the same JVM (which should be rare in the first place). That name can be set at Cluster building time (through Cluster.Builder.withClusterName(java.lang.String) for instance) but will default to a name like cluster1 where each Cluster instance in the same JVM will ahve a different number.

Returns:

the name for this cluster instance.

getMetadata

public Metadata getMetadata()

Returns read-only metadata on the connected cluster.

This includes the known nodes with their status as seen by the driver, as well as the schema definitions. Since this return metadata on the connected cluster, this method may trigger the creation of a connection if none has been established yet (neither init() nor connect() has been called yet).

Returns:

the cluster metadata.

Throws:

NoHostAvailableException - if the Cluster has not been initialized yet and no host amongst the contact points can be reached.

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

getConfiguration

public Configuration getConfiguration()

The cluster configuration.

Returns:

the cluster configuration.

getMetrics

public Metrics getMetrics()

The cluster metrics.

Returns:

the cluster metrics, or null if metrics collection has been disabled (that is if Configuration.getMetricsOptions() returns null).

register

public Cluster register(Host.StateListener listener)

Registers the provided listener to be notified on hosts up/down/added/removed events.

Registering the same listener multiple times is a no-op.

Note that while LoadBalancingPolicy implements Host.StateListener, the configured load balancy does not need to (and should not) be registered through this method to received host related events.

Parameters:

listener - the new Host.StateListener to register.

Returns:

this Cluster object;

unregister

public Cluster unregister(Host.StateListener listener)

Unregisters the provided listener from being notified on hosts events.

This method is a no-op if listener hadn't previously be registered against this Cluster.

Parameters:

listener - the Host.StateListener to unregister.

Returns:

this Cluster object;

register

public Cluster register(LatencyTracker tracker)

Registers the provided tracker to be updated with hosts read latencies.

Registering the same listener multiple times is a no-op.

Be warry that the registered tracker update method will be call very frequently (at the end of every query to a Cassandra host) and should thus not be costly.

The main use case for a LatencyTracker is so LoadBalancingPolicy can implement latency awareness Typically, LatencyAwarePolicy registers it's own internal LatencyTracker (automatically, you don't have to call this method directly).

Parameters:

tracker - the new LatencyTracker to register.

Returns:

this Cluster object;

unregister

public Cluster unregister(LatencyTracker tracker)

Unregisters the provided latency tracking from being updated with host read latencies.

This method is a no-op if tracker hadn't previously be registered against this Cluster.

Parameters:

tracker - the LatencyTracker to unregister.

Returns:

this Cluster object;

shutdown

public ShutdownFuture shutdown()

Initiates a shutdown of this cluster instance. This method is asynchronous and return a future on the completion of the shutdown process. As soon a the cluster is shutdown, no new request will be accepted, but already submitted queries are allowed to complete. Shutdown closes all connections from all sessions and reclaims all ressources used by this Cluster instance.

If for some reason you wish to expedite this process, the ShutdownFuture.force() can be called on the result future.

This method has no particular effect if the cluster was already shut down (in which case the returned future will return immediately).

Returns:

a future on the completion of the shtudown process.