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

static class	Cluster.Builder Helper class to build Cluster instances.
static interface	Cluster.Initializer Initializer for Cluster instances.

Method Summary

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.
Cluster	register(Host.StateListener listener) Registers the provided listener to be notified on hosts up/down/added/removed events.
void	shutdown() Shuts down this cluster instance.
boolean	shutdown(long timeout, TimeUnit unit) Shutdown this cluster instance, only waiting a definite amount of time.
void	unregister(Host.StateListener listener) Unregisters the provided listener from being notified on hosts events.

Methods inherited from class java.lang.Object

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

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 void 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 monitor.

Parameters:

listener - the Host.StateListener to unregister.

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.