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.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Cluster(List<InetAddress> contactPoints, Configuration configuration, boolean init) Constructs a new Cluster instance.

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.
Configuration	getConfiguration() The cluster configuration.
Metadata	getMetadata() Returns read-only metadata on the connected cluster.
Metrics	getMetrics() The cluster metrics.
boolean	isShutdown() Whether shutdown has been called on 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.
void	shutdown() Shuts down this cluster instance.
boolean	shutdown(long timeout, TimeUnit unit) Shutdown this cluster instance, only waiting a definite amount of time.
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

Constructor Detail

Cluster

protected Cluster(List<InetAddress> contactPoints,
       Configuration configuration,
       boolean init)

Constructs a new Cluster instance.

This constructor is mainly exposed so Cluster can be sub-classed as a mean to make testing/mocking easier or to "intecept" it's method call. Most users shouldn't extend this class however and should prefer either using the builder() or calling buildFrom(com.datastax.driver.core.Cluster.Initializer) with a custom Initializer.

Parameters:

contactPoints - the list of contact points to use for the new cluster.

configuration - the configuration for the new cluster.

init - whether or not initialization should be perform by this constructor. Passing false is equivalent to using Cluster.Builder.withDeferredInitialization() on a Cluster.Builder.

Method Detail

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:

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

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

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

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.

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 no host can be contacted to set the keyspace.

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.

Returns:

the cluster metadata.

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 void shutdown()

Shuts down this cluster instance. This closes all connections from all the sessions of this Cluster instance and reclaims all resources used by it.

This method waits indefinitely for the driver to shut down.

This method has no effect if the cluster was already shut down.

shutdown

public boolean shutdown(long timeout,
               TimeUnit unit)

Shutdown this cluster instance, only waiting a definite amount of time. This closes all connections from all the sessions of this Cluster instance and reclaim all resources used by it.

Note that this method is not thread safe in the sense that if another shutdown is perform in parallel, it might return true even if the instance is not yet fully shutdown.

Parameters:

timeout - how long to wait for the cluster instance to shutdown.

unit - the unit for the timeout.

Returns:

true if the instance has been properly shutdown within the timeout, false otherwise.

isShutdown

public boolean isShutdown()

Whether shutdown has been called on this Cluster instance.

Returns:

true if shutdown has been called on this instance, false otherwise.