public static class Cluster.Builder extends Object implements Cluster.Initializer
Cluster
instances.Constructor and Description |
---|
Builder() |
Modifier and Type | Method and Description |
---|---|
Cluster.Builder |
addContactPoint(String address)
Adds a contact point - or many if the given address resolves to multiple
InetAddress s (A records). |
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.Builder |
addContactPointsWithPorts(Collection<InetSocketAddress> addresses)
Adds contact points.
|
Cluster.Builder |
addContactPointsWithPorts(InetSocketAddress... addresses)
Adds contact points.
|
Cluster.Builder |
allowBetaProtocolVersion()
Create cluster connection using latest development protocol version,
which is currently in beta.
|
Cluster |
build()
Builds the cluster with the configured set of initial contact points
and policies.
|
String |
getClusterName()
An optional name for the created cluster.
|
Configuration |
getConfiguration()
The configuration that will be used for the new cluster.
|
List<InetSocketAddress> |
getContactPoints()
Returns the initial Cassandra hosts to connect to.
|
Collection<Host.StateListener> |
getInitialListeners()
Optional listeners to register against the newly created cluster.
|
Cluster.Builder |
withAddressTranslator(AddressTranslator translator)
Configures the address translator to use for the new cluster.
|
Cluster.Builder |
withAuthProvider(AuthProvider authProvider)
Use the specified AuthProvider when connecting to Cassandra
hosts.
|
Cluster.Builder |
withClusterName(String name)
An optional name for the create cluster.
|
Cluster.Builder |
withCodecRegistry(CodecRegistry codecRegistry)
Configures the
CodecRegistry instance to use for the new cluster. |
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 |
withInitialListeners(Collection<Host.StateListener> listeners)
Register the provided listeners in the newly created cluster.
|
Cluster.Builder |
withLoadBalancingPolicy(LoadBalancingPolicy policy)
Configures the load balancing policy to use for the new cluster.
|
Cluster.Builder |
withMaxSchemaAgreementWaitSeconds(int maxSchemaAgreementWaitSeconds)
Sets the maximum time to wait for schema agreement before returning from a DDL query.
|
Cluster.Builder |
withNettyOptions(NettyOptions nettyOptions)
Set the
NettyOptions to use for the newly created 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)
Sets 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 |
withProtocolVersion(ProtocolVersion version)
The native protocol version to use.
|
Cluster.Builder |
withQueryOptions(QueryOptions options)
Sets the QueryOptions to use for the newly created Cluster.
|
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)
Sets the SocketOptions to use for the newly created Cluster.
|
Cluster.Builder |
withSpeculativeExecutionPolicy(SpeculativeExecutionPolicy policy)
Configures the speculative execution policy to use for the new 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. |
Cluster.Builder |
withThreadingOptions(ThreadingOptions options)
Sets the threading options to use for the newly created Cluster.
|
Cluster.Builder |
withTimestampGenerator(TimestampGenerator timestampGenerator)
Configures the generator that will produce the client-side timestamp sent
with each query.
|
public String getClusterName()
Cluster.Initializer
Cluster.getClusterName()
for more
information.getClusterName
in interface Cluster.Initializer
null
to use an automatically
generated name.public List<InetSocketAddress> getContactPoints()
Cluster.Initializer
getContactPoints
in interface Cluster.Initializer
addContactPoint(java.lang.String)
for more details on contact points.public Cluster.Builder withClusterName(String name)
Cluster.getClusterName()
for
details.
If you use this method and create more than one Cluster instance in the
same JVM (which should be avoided unless you need to connect to multiple
Cassandra clusters), you should make sure each Cluster instance get a
unique name or you may have a problem with JMX reporting.name
- the cluster name to use for the created Cluster instance.public Cluster.Builder withPort(int port)
port
- the port to set.public Cluster.Builder allowBetaProtocolVersion()
V5
.
Use with caution, refer to the server and protocol documentation for the details
on latest protocol version.public Cluster.Builder withMaxSchemaAgreementWaitSeconds(int maxSchemaAgreementWaitSeconds)
maxSchemaAgreementWaitSeconds
- the new value to set.IllegalStateException
- if the provided value is zero or less.public Cluster.Builder withProtocolVersion(ProtocolVersion version)
Protocol version | Minimum Cassandra version |
---|---|
1 | 1.2 |
2 | 2.0 |
3 | 2.1 |
4 | 2.2 |
5 | 3.10 |
ProtocolVersion.NEWEST_SUPPORTED
, and if not supported fallback to
the highest version supported by the first node it connects to. Please note
that once the version is "auto-detected", it won't change: if the first node
the driver connects to is a Cassandra 1.2 node and auto-detection is used
(the default), then the native protocol version 1 will be use for the lifetime
of the Cluster instance.
By using allowBetaProtocolVersion()
, it is
possible to force driver to connect to Cassandra node that supports the latest
protocol beta version. Leaving this flag out will let client to connect with
latest released version.
This method allows to force the use of a particular protocol version. Forcing
version 1 is always fine since all Cassandra version (at least all those
supporting the native protocol in the first place) so far support it. However,
please note that a number of features of the driver won't be available if that
version of the protocol is in use, including result set paging,
BatchStatement
, executing a non-prepared query with binary values
(Session.execute(String, Object...)
), ... (those methods will throw
an UnsupportedFeatureException). Using the protocol version 1 should thus
only be considered when using Cassandra 1.2, until nodes have been upgraded
to Cassandra 2.0.
If version 2 of the protocol is used, then Cassandra 1.2 nodes will be ignored
(the driver won't connect to them).
The default behavior (auto-detection) is fine in almost all case, but you may
want to force a particular version if you have a Cassandra cluster with mixed
1.2/2.0 nodes (i.e. during a Cassandra upgrade).version
- the native protocol version to use. null
is also supported
to trigger auto-detection (see above) but this is the default (so you don't have
to call this method for that behavior).public Cluster.Builder addContactPoint(String address)
InetAddress
s (A records).
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.
Note that by default (that is, unless you use the withLoadBalancingPolicy(com.datastax.driver.core.policies.LoadBalancingPolicy)
)
method of this builder), the first successfully contacted host will be used
to define the local data-center for the client. If follows that if you are
running Cassandra in a multiple data-center setting, it is a good idea to
only provide contact points that are in the same datacenter than the client,
or to provide manually the load balancing policy that suits your need.
If the host name points to a DNS record with multiple a-records, all InetAddresses
returned will be used. Make sure that all resulting InetAddress
s returned
point to the same cluster and datacenter.address
- the address of the node(s) to connect to.IllegalArgumentException
- if the given address
could not be resolved.SecurityException
- if a security manager is present and
permission to resolve the host name is denied.public Cluster.Builder addContactPoints(String... addresses)
addContactPoint(java.lang.String)
for more details on contact
points.
Note that all contact points must be resolvable;
if any of them cannot be resolved, this method will fail.addresses
- addresses of the nodes to add as contact points.IllegalArgumentException
- if any of the given addresses
could not be resolved.SecurityException
- if a security manager is present and
permission to resolve the host name is denied.addContactPoint(java.lang.String)
public Cluster.Builder addContactPoints(InetAddress... addresses)
addContactPoint(java.lang.String)
for more details on contact
points.
Note that all contact points must be resolvable;
if any of them cannot be resolved, this method will fail.addresses
- addresses of the nodes to add as contact points.IllegalArgumentException
- if any of the given addresses
could not be resolved.SecurityException
- if a security manager is present and
permission to resolve the host name is denied.addContactPoint(java.lang.String)
public Cluster.Builder addContactPoints(Collection<InetAddress> addresses)
addContactPoint(java.lang.String)
for more details on contact
points.addresses
- addresses of the nodes to add as contact points.addContactPoint(java.lang.String)
public Cluster.Builder addContactPointsWithPorts(InetSocketAddress... addresses)
addContactPoint(java.lang.String)
for more details on contact
points. Contrarily to other addContactPoints
methods, this method
allows to provide a different port for each contact point. Since Cassandra
nodes must always all listen on the same port, this is rarely what you
want and most users should prefer other addContactPoints
methods to
this one. However, this can be useful if the Cassandra nodes are behind
a router and are not accessed directly. Note that if you are in this
situation (Cassandra nodes are behind a router, not directly accessible),
you almost surely want to provide a specific AddressTranslator
(through withAddressTranslator(com.datastax.driver.core.policies.AddressTranslator)
) to translate actual Cassandra node
addresses to the addresses the driver should use, otherwise the driver
will not be able to auto-detect new nodes (and will generally not function
optimally).addresses
- addresses of the nodes to add as contact points.addContactPoint(java.lang.String)
public Cluster.Builder addContactPointsWithPorts(Collection<InetSocketAddress> addresses)
addContactPoint(java.lang.String)
for more details on contact
points. Contrarily to other addContactPoints
methods, this method
allows to provide a different port for each contact point. Since Cassandra
nodes must always all listen on the same port, this is rarely what you
want and most users should prefer other addContactPoints
methods to
this one. However, this can be useful if the Cassandra nodes are behind
a router and are not accessed directly. Note that if you are in this
situation (Cassandra nodes are behind a router, not directly accessible),
you almost surely want to provide a specific AddressTranslator
(through withAddressTranslator(com.datastax.driver.core.policies.AddressTranslator)
) to translate actual Cassandra node
addresses to the addresses the driver should use, otherwise the driver
will not be able to auto-detect new nodes (and will generally not function
optimally).addresses
- addresses of the nodes to add as contact points.addContactPoint(java.lang.String)
public Cluster.Builder withLoadBalancingPolicy(LoadBalancingPolicy policy)
Policies.defaultLoadBalancingPolicy()
will be used instead.policy
- the load balancing policy to use.public Cluster.Builder withReconnectionPolicy(ReconnectionPolicy policy)
Policies.DEFAULT_RECONNECTION_POLICY
will be used instead.policy
- the reconnection policy to use.public Cluster.Builder withRetryPolicy(RetryPolicy policy)
Policies.DEFAULT_RETRY_POLICY
will be used instead.policy
- the retry policy to use.public Cluster.Builder withAddressTranslator(AddressTranslator translator)
AddressTranslator
for more detail on address translation,
but the default translator, IdentityTranslator
, should be
correct in most cases. If unsure, stick to the default.translator
- the translator to use.public Cluster.Builder withTimestampGenerator(TimestampGenerator timestampGenerator)
V3
or
above of the native protocol. With earlier versions, timestamps are always
generated server-side, and setting a generator through this method will have
no effect.
If no generator is set through this method, the driver will default to
client-side timestamps by using AtomicMonotonicTimestampGenerator
.timestampGenerator
- the generator to use.public Cluster.Builder withSpeculativeExecutionPolicy(SpeculativeExecutionPolicy policy)
Policies.defaultSpeculativeExecutionPolicy()
will be used instead.policy
- the policy to use.public Cluster.Builder withCodecRegistry(CodecRegistry codecRegistry)
CodecRegistry
instance to use for the new cluster.
If no codec registry is set through this method, CodecRegistry.DEFAULT_INSTANCE
will be used instead.
Note that if two or more Cluster
instances are configured to
use the default codec registry, they are going to share the same instance.
In this case, care should be taken when registering new codecs on it as any
codec registered by one cluster would be immediately available to others
sharing the same default instance.
codecRegistry
- the codec registry to use.public Cluster.Builder withCredentials(String username, String password)
PasswordAuthenticator
. If the the default AllowAllAuthenticator
is used instead, using this method has no
effect.username
- the username to use to login to Cassandra hosts.password
- the password corresponding to username
.public Cluster.Builder withAuthProvider(AuthProvider authProvider)
withCredentials
on the same Builder
instance as one will supersede the
otherauthProvider
- the AuthProvider
to use to login to
Cassandra hosts.public Cluster.Builder withCompression(ProtocolOptions.Compression compression)
compression
- the compression to set.ProtocolOptions.Compression
public Cluster.Builder withoutMetrics()
public Cluster.Builder withSSL()
Cluster
.
Calling this method will use the JDK-based implementation with the default options
(see RemoteEndpointAwareJdkSSLOptions.Builder
).
This is thus a shortcut for withSSL(JdkSSLOptions.builder().build())
.
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.public Cluster.Builder withSSL(SSLOptions sslOptions)
Cluster
using the provided options.sslOptions
- the SSL options to use.public Cluster.Builder withInitialListeners(Collection<Host.StateListener> listeners)
listeners
- the listeners to register.public Cluster.Builder withoutJMXReporting()
Metrics
) but can be
disabled using this option. If metrics are disabled, this is a
no-op.public Cluster.Builder withPoolingOptions(PoolingOptions options)
options
- the pooling options to use.public Cluster.Builder withSocketOptions(SocketOptions options)
options
- the socket options to use.public Cluster.Builder withQueryOptions(QueryOptions options)
options
- the query options to use.public Cluster.Builder withThreadingOptions(ThreadingOptions options)
ThreadingOptions
will be used.options
- the options.public Cluster.Builder withNettyOptions(NettyOptions nettyOptions)
NettyOptions
to use for the newly created Cluster.
If no Netty options are set through this method, NettyOptions.DEFAULT_INSTANCE
will be used as a default value, which means that no customization will be applied.nettyOptions
- the NettyOptions
to use.public Configuration getConfiguration()
Builder
.getConfiguration
in interface Cluster.Initializer
public Collection<Host.StateListener> getInitialListeners()
Cluster.Initializer
Host.StateListener.onAdd(com.datastax.driver.core.Host)
events for the initial contact points.getInitialListeners
in interface Cluster.Initializer
Host.StateListener
to register
against the newly created cluster.public Cluster build()
Cluster.buildFrom(this)
.Copyright © 2012–2017. All rights reserved.