public class Cluster extends Object implements Closeable
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.
Modifier and Type | Class and Description |
---|---|
static class |
Cluster.Builder
Helper class to build
Cluster instances. |
static interface |
Cluster.Initializer
Initializer for
Cluster instances. |
Modifier | Constructor and Description |
---|---|
protected |
Cluster(Cluster.Initializer initializer)
Constructs a new Cluster instance.
|
protected |
Cluster(String name,
List<InetSocketAddress> contactPoints,
Configuration configuration)
Constructs a new Cluster instance.
|
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.
|
void |
close()
Initiates a shutdown of this cluster instance and blocks until
that shutdown completes.
|
CloseFuture |
closeAsync()
Initiates a shutdown of this cluster instance.
|
Session |
connect()
Creates a new session on this cluster and initialize it.
|
Session |
connect(String keyspace)
Creates a new session on this cluster, initialize it and sets the
keyspace to the provided one.
|
ListenableFuture<Session> |
connectAsync()
Creates a new session on this cluster and initializes it asynchronously.
|
ListenableFuture<Session> |
connectAsync(String keyspace)
Creates a new session on this cluster, and initializes it to the given
keyspace asynchronously.
|
String |
getClusterName()
The name of this cluster object.
|
Configuration |
getConfiguration()
The cluster configuration.
|
static String |
getDriverVersion()
Returns the current version of the driver.
|
Metadata |
getMetadata()
Returns read-only metadata on the connected cluster.
|
Metrics |
getMetrics()
The cluster metrics.
|
Cluster |
init()
Initialize this Cluster instance.
|
boolean |
isClosed()
Whether this Cluster instance has been closed.
|
Session |
newSession()
Creates a new session on this cluster but does not initialize it.
|
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.
|
Cluster |
register(SchemaChangeListener listener)
Registers the provided listener to be updated with schema change events.
|
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.
|
Cluster |
unregister(SchemaChangeListener listener)
Unregisters the provided schema change listener from being updated
with schema change events.
|
protected Cluster(String name, List<InetSocketAddress> contactPoints, Configuration configuration)
builder()
or calling buildFrom(com.datastax.driver.core.Cluster.Initializer)
with a custom
Initializer.name
- the name to use for the cluster (this is not the Cassandra cluster name, see getClusterName()
).contactPoints
- the list of contact points to use for the new cluster.configuration
- the configuration for the new cluster.protected Cluster(Cluster.Initializer initializer)
builder()
.initializer
- the initializer to use.buildFrom(com.datastax.driver.core.Cluster.Initializer)
public Cluster init()
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 creates one control connection for
gathering cluster metadata. In particular, it doesn't create any connection pools.
Those are created when a new Session
is created through
connect
.
This method has no effect if the cluster is already initialized.Cluster
object.NoHostAvailableException
- if no host amongst the contact points
can be reached.AuthenticationException
- if an authentication error occurs
while contacting the initial contact points.IllegalStateException
- if the Cluster was closed prior to calling
this method. This can occur either directly (through close()
or
closeAsync()
), or as a result of an error while initializing the
Cluster.public static Cluster buildFrom(Cluster.Initializer initializer)
Cluster.Builder.build()
.
Also note that that all the contact points provided by initializer
must share the same port.initializer
- the Cluster.Initializer to useIllegalArgumentException
- if the list of contact points provided
by initializer
is empty or if not all those contact points have the same port.public static Cluster.Builder builder()
Cluster.Builder
instance.
This is a convenience method for new Cluster.Builder()
.public static String getDriverVersion()
public Session newSession()
Session.init()
method is
called explicitly, or whenever the returned session object is used.
Once a session returned by this method gets initialized (see above), it
will be set to no keyspace. If you want to set such session to a
keyspace, you will have to explicitly execute a 'USE mykeyspace' query.
Note that if you do not particularly need to defer initialization, it is
simpler to use one of the connect()
method of this class.public Session connect()
newSession()
.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.IllegalStateException
- if the Cluster was closed prior to calling
this method. This can occur either directly (through close()
or
closeAsync()
), or as a result of an error while initializing the
Cluster.public Session connect(String keyspace)
newSession()
.keyspace
- The name of the keyspace to use for the created
Session
.keyspaceName
.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.InvalidQueryException
- if the keyspace does not exists.IllegalStateException
- if the Cluster was closed prior to calling
this method. This can occur either directly (through close()
or
closeAsync()
), or as a result of an error while initializing the
Cluster.public ListenableFuture<Session> connectAsync()
Cluster
if needed; note that cluster
initialization happens synchronously on the thread that called this method.
Therefore it is recommended to initialize the cluster at application
startup, and not rely on this method to do it.NoHostAvailableException
- if the Cluster has not been initialized
yet (init()
has not been called and this is the first connect call)
and no host amongst the contact points can be reached.IllegalStateException
- if the Cluster was closed prior to calling
this method. This can occur either directly (through close()
or
closeAsync()
), or as a result of an error while initializing the
Cluster.connect()
public ListenableFuture<Session> connectAsync(String keyspace)
Cluster
if needed; note that cluster
initialization happens synchronously on the thread that called this method.
Therefore it is recommended to initialize the cluster at application
startup, and not rely on this method to do it.keyspace
- The name of the keyspace to use for the created
Session
.NoHostAvailableException
- if the Cluster has not been initialized
yet (init()
has not been called and this is the first connect call)
and no host amongst the contact points can be reached.IllegalStateException
- if the Cluster was closed prior to calling
this method. This can occur either directly (through close()
or
closeAsync()
), or as a result of an error while initializing the
Cluster.public String getClusterName()
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 have a different number.public Metadata getMetadata()
init()
nor connect()
has been called yet).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.IllegalStateException
- if the Cluster was closed prior to calling
this method. This can occur either directly (through close()
or
closeAsync()
), or as a result of an error while initializing the
Cluster.public Configuration getConfiguration()
public Metrics getMetrics()
null
if this cluster has not yet been initialized
, or if
metrics collection has been disabled (that is if Configuration.getMetricsOptions()
returns null
).public Cluster register(Host.StateListener listener)
LoadBalancingPolicy
implements
Host.StateListener
, the configured load balancing does not
need to (and should not) be registered through this method to
received host related events.listener
- the new Host.StateListener
to register.Cluster
object;public Cluster unregister(Host.StateListener listener)
listener
hadn't previously be
registered against this Cluster.listener
- the Host.StateListener
to unregister.Cluster
object;public Cluster register(LatencyTracker 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).tracker
- the new LatencyTracker
to register.Cluster
object;public Cluster unregister(LatencyTracker tracker)
tracker
hadn't previously be
registered against this Cluster.tracker
- the LatencyTracker
to unregister.Cluster
object;public Cluster register(SchemaChangeListener listener)
listener
- the new SchemaChangeListener
to register.Cluster
object;public Cluster unregister(SchemaChangeListener listener)
listener
hadn't previously be
registered against this Cluster.listener
- the SchemaChangeListener
to unregister.Cluster
object;public CloseFuture closeAsync()
CloseFuture.force()
can be called on the result future.
This method has no particular effect if the cluster was already closed
(in which case the returned future will return immediately).public void close()
closeAsync().get()
.close
in interface Closeable
close
in interface AutoCloseable
public boolean isClosed()
closeAsync()
or close()
) has been called, it does not guarantee
that the closing is done. If you want to guarantee that the closing is done,
you can call close()
and wait until it returns (or call the get method
on closeAsync()
with a very short timeout and check this doesn't timeout).true
if this Cluster instance has been closed, false
otherwise.