com.datastax.oss.driver.api.core.session

Class SessionBuilder<SelfT extends SessionBuilder,SessionT>

java.lang.Object

com.datastax.oss.driver.api.core.session.SessionBuilder<SelfT,SessionT>

Direct Known Subclasses:

CqlSessionBuilder

@NotThreadSafe
public abstract class SessionBuilder<SelfT extends SessionBuilder,SessionT>
extends Object

Base implementation to build session instances.

You only need to deal with this directly if you use custom driver extensions. For the default session implementation, see CqlSession.builder().

This class is mutable and not thread-safe.

Field Summary

Fields

Modifier and Type	Field and Description
protected Callable<InputStream>	cloudConfigInputStream
protected DriverConfigLoader	configLoader
protected CqlIdentifier	keyspace
protected ProgrammaticArguments.Builder	programmaticArgumentsBuilder
protected Set<EndPoint>	programmaticContactPoints
protected SelfT	self

Constructor Summary

Constructors

Constructor and Description
SessionBuilder()

Method Summary

Modifier and Type	Method and Description
SelfT	addContactEndPoint(EndPoint contactPoint) Adds a contact point to use for the initial connection to the cluster.
SelfT	addContactEndPoints(Collection<EndPoint> contactPoints) Adds contact points to use for the initial connection to the cluster.
SelfT	addContactPoint(InetSocketAddress contactPoint) Adds a contact point to use for the initial connection to the cluster.
SelfT	addContactPoints(Collection<InetSocketAddress> contactPoints) Adds contact points to use for the initial connection to the cluster.
SelfT	addTypeCodecs(TypeCodec<?>... typeCodecs) Registers additional codecs for custom type mappings.
SessionT	build() Convenience method to call buildAsync() and block on the result.
CompletionStage<SessionT>	buildAsync() Creates the session with the options set by this builder.
protected DriverContext	buildContext(DriverConfigLoader configLoader, List<TypeCodec<?>> typeCodecs, NodeStateListener nodeStateListener, SchemaChangeListener schemaChangeListener, RequestTracker requestTracker, Map<String,String> localDatacenters, Map<String,Predicate<Node>> nodeFilters, ClassLoader classLoader) Deprecated. this method only exists for backward compatibility (if a subclass written for driver 4.1.0 returns a non-null result, that value will be used). Please override buildContext(DriverConfigLoader, ProgrammaticArguments) instead.
protected DriverContext	buildContext(DriverConfigLoader configLoader, ProgrammaticArguments programmaticArguments) This must return an instance of InternalDriverContext (it's not expressed directly in the signature to avoid leaking that type through the protected API).
protected CompletionStage<CqlSession>	buildDefaultSessionAsync()
protected DriverConfigLoader	defaultConfigLoader()
SelfT	withAuthCredentials(String username, String password) Configures the session to use plaintext authentication with the given username and password.
SelfT	withAuthProvider(AuthProvider authProvider) Registers an authentication provider to use with the session.
SelfT	withClassLoader(ClassLoader classLoader) The ClassLoader to use to reflectively load class names defined in configuration.
SelfT	withCloudProxyAddress(InetSocketAddress cloudProxyAddress) Configures this SessionBuilder to use the provided Cloud proxy endpoint.
SelfT	withCloudSecureConnectBundle(InputStream cloudConfigInputStream) Configures this SessionBuilder for Cloud deployments by retrieving connection information from the provided InputStream.
SelfT	withCloudSecureConnectBundle(Path cloudConfigPath) Configures this SessionBuilder for Cloud deployments by retrieving connection information from the provided Path.
SelfT	withCloudSecureConnectBundle(URL cloudConfigUrl) Configures this SessionBuilder for Cloud deployments by retrieving connection information from the provided URL.
SelfT	withConfigLoader(DriverConfigLoader configLoader) Sets the configuration loader to use.
SelfT	withKeyspace(CqlIdentifier keyspace) Sets the keyspace to connect the session to.
SelfT	withKeyspace(String keyspaceName) Shortcut for setKeyspace(CqlIdentifier.fromCql(keyspaceName))
SelfT	withLocalDatacenter(String localDatacenter) Alias to withLocalDatacenter(String, String) for the default profile.
SelfT	withLocalDatacenter(String profileName, String localDatacenter) Specifies the datacenter that is considered "local" by the load balancing policy.
SelfT	withNodeFilter(Predicate<Node> nodeFilter) Alias to withNodeFilter(String, Predicate) for the default profile.
SelfT	withNodeFilter(String profileName, Predicate<Node> nodeFilter) Adds a custom filter to include/exclude nodes for a particular execution profile.
SelfT	withNodeStateListener(NodeStateListener nodeStateListener) Registers a node state listener to use with the session.
SelfT	withRequestTracker(RequestTracker requestTracker) Registers a request tracker to use with the session.
SelfT	withSchemaChangeListener(SchemaChangeListener schemaChangeListener) Registers a schema change listener to use with the session.
SelfT	withSslContext(SSLContext sslContext) Configures the session to use SSL with the given context.
SelfT	withSslEngineFactory(SslEngineFactory sslEngineFactory) Registers an SSL engine factory for the session.
protected abstract SessionT	wrap(CqlSession defaultSession)

Methods inherited from class java.lang.Object

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

Field Detail

self

protected final SelfT extends SessionBuilder self

configLoader

protected DriverConfigLoader configLoader

programmaticContactPoints

protected Set<EndPoint> programmaticContactPoints

keyspace

protected CqlIdentifier keyspace

cloudConfigInputStream

protected Callable<InputStream> cloudConfigInputStream

programmaticArgumentsBuilder

protected ProgrammaticArguments.Builder programmaticArgumentsBuilder

Constructor Detail

SessionBuilder

public SessionBuilder()

Method Detail

withConfigLoader

@NonNull
public SelfT withConfigLoader(@Nullable
                                       DriverConfigLoader configLoader)

Sets the configuration loader to use.

If you don't call this method, the builder will use the default implementation, based on the Typesafe config library. More precisely, configuration properties are loaded and merged from the following (first-listed are higher priority):

• system properties
• application.conf (all resources on classpath with this name)
• application.json (all resources on classpath with this name)
• application.properties (all resources on classpath with this name)
• reference.conf (all resources on classpath with this name). In particular, this will load the reference.conf included in the core driver JAR, that defines default options for all mandatory options.

The resulting configuration is expected to contain a datastax-java-driver section.

This default loader will honor the reload interval defined by the option basic.config-reload-interval.

See Also:

Typesafe config's standard loading behavior

defaultConfigLoader

@NonNull
protected DriverConfigLoader defaultConfigLoader()

addContactPoints

@NonNull
public SelfT addContactPoints(@NonNull
                                       Collection<InetSocketAddress> contactPoints)

Adds contact points to use for the initial connection to the cluster.

These 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.

Contact points can also be provided statically in the configuration. If both are specified, they will be merged. If both are absent, the driver will default to 127.0.0.1:9042.

Contrary to the configuration, DNS names with multiple A-records will not be handled here. If you need that, extract them manually with InetAddress.getAllByName(String) before calling this method. Similarly, if you need connect addresses to stay unresolved, make sure you pass unresolved instances here (see advanced.resolve-contact-points in the configuration for more explanations).

addContactPoint

@NonNull
public SelfT addContactPoint(@NonNull
                                      InetSocketAddress contactPoint)

Adds a contact point to use for the initial connection to the cluster.

See Also:

addContactPoints(Collection)

addContactEndPoints

@NonNull
public SelfT addContactEndPoints(@NonNull
                                          Collection<EndPoint> contactPoints)

Adds contact points to use for the initial connection to the cluster.

You only need this method if you use a custom EndPoint implementation. Otherwise, use addContactPoints(Collection).

addContactEndPoint

@NonNull
public SelfT addContactEndPoint(@NonNull
                                         EndPoint contactPoint)

Adds a contact point to use for the initial connection to the cluster.

You only need this method if you use a custom EndPoint implementation. Otherwise, use addContactPoint(InetSocketAddress).

addTypeCodecs

@NonNull
public SelfT addTypeCodecs(@NonNull
                                    TypeCodec<?>... typeCodecs)

Registers additional codecs for custom type mappings.

Parameters:

typeCodecs - neither the individual codecs, nor the vararg array itself, can be null.

withNodeStateListener

@NonNull
public SelfT withNodeStateListener(@Nullable
                                            NodeStateListener nodeStateListener)

Registers a node state listener to use with the session.

If the listener is specified programmatically with this method, it overrides the configuration (that is, the metadata.node-state-listener.class option will be ignored).

withSchemaChangeListener

@NonNull
public SelfT withSchemaChangeListener(@Nullable
                                               SchemaChangeListener schemaChangeListener)

Registers a schema change listener to use with the session.

If the listener is specified programmatically with this method, it overrides the configuration (that is, the metadata.schema-change-listener.class option will be ignored).

withRequestTracker

@NonNull
public SelfT withRequestTracker(@Nullable
                                         RequestTracker requestTracker)

Registers a request tracker to use with the session.

If the tracker is specified programmatically with this method, it overrides the configuration (that is, the request.tracker.class option will be ignored).

withAuthProvider

@NonNull
public SelfT withAuthProvider(@Nullable
                                       AuthProvider authProvider)

Registers an authentication provider to use with the session.

If the provider is specified programmatically with this method, it overrides the configuration (that is, the advanced.auth-provider.class option will be ignored).

withAuthCredentials

@NonNull
public SelfT withAuthCredentials(@NonNull
                                          String username,
                                          @NonNull
                                          String password)

Configures the session to use plaintext authentication with the given username and password.

This methods calls withAuthProvider(AuthProvider) to register a special provider implementation. Therefore calling it overrides the configuration (that is, the advanced.auth-provider.class option will be ignored).

Note that this approach holds the credentials in clear text in memory, which makes them vulnerable to an attacker who is able to perform memory dumps. If this is not acceptable for you, consider writing your own AuthProvider implementation (PlainTextAuthProviderBase is a good starting point), and providing it either with withAuthProvider(AuthProvider) or via the configuration (advanced.auth-provider.class).

withSslEngineFactory

@NonNull
public SelfT withSslEngineFactory(@Nullable
                                           SslEngineFactory sslEngineFactory)

Registers an SSL engine factory for the session.

If the factory is provided programmatically with this method, it overrides the configuration (that is, the advanced.ssl-engine-factory option will be ignored).

See Also:

ProgrammaticSslEngineFactory

withSslContext

@NonNull
public SelfT withSslContext(@Nullable
                                     SSLContext sslContext)

Configures the session to use SSL with the given context.

This is a convenience method for clients that already have an SSLContext instance. It wraps its argument into a ProgrammaticSslEngineFactory, and passes it to withSslEngineFactory(SslEngineFactory).

If you use this method, there is no way to customize cipher suites, or turn on host name validation. If you need finer control, use withSslEngineFactory(SslEngineFactory) directly and pass either your own implementation of SslEngineFactory, or a ProgrammaticSslEngineFactory created with custom cipher suites and/or host name validation.

Also, note that SSL engines will be created with advisory peer information (SSLContext.createSSLEngine(String, int)) whenever possible.

withLocalDatacenter

public SelfT withLocalDatacenter(@NonNull
                                 String profileName,
                                 @NonNull
                                 String localDatacenter)

Specifies the datacenter that is considered "local" by the load balancing policy.

This is a programmatic alternative to the configuration option basic.load-balancing-policy.local-datacenter. If this method is used, it takes precedence and overrides the configuration.

Note that this setting may or may not be relevant depending on the load balancing policy implementation in use. The driver's built-in DefaultLoadBalancingPolicy relies on it; if you use a third-party implementation, refer to their documentation.

withLocalDatacenter

public SelfT withLocalDatacenter(@NonNull
                                 String localDatacenter)

Alias to withLocalDatacenter(String, String) for the default profile.

withNodeFilter

@NonNull
public SelfT withNodeFilter(@NonNull
                                     String profileName,
                                     @NonNull
                                     Predicate<Node> nodeFilter)

Adds a custom filter to include/exclude nodes for a particular execution profile. This assumes that you're also using a dedicated load balancing policy for that profile.

The predicate's test() method will be invoked each time the LoadBalancingPolicy processes a topology or state change: if it returns false, the policy will suggest distance IGNORED (meaning the driver won't ever connect to it if all policies agree), and never included in any query plan.

Note that this behavior is implemented in the default load balancing policy. If you use a custom policy implementation, you'll need to explicitly invoke the filter.

If the filter is specified programmatically with this method, it overrides the configuration (that is, the load-balancing-policy.filter.class option will be ignored).

See Also:

withNodeFilter(Predicate)

withNodeFilter

@NonNull
public SelfT withNodeFilter(@NonNull
                                     Predicate<Node> nodeFilter)

Alias to withNodeFilter(String, Predicate) for the default profile.

withKeyspace

@NonNull
public SelfT withKeyspace(@Nullable
                                   CqlIdentifier keyspace)

Sets the keyspace to connect the session to.

Note that this can also be provided by the configuration; if both are defined, this method takes precedence.

withKeyspace

@NonNull
public SelfT withKeyspace(@Nullable
                                   String keyspaceName)

Shortcut for setKeyspace(CqlIdentifier.fromCql(keyspaceName))

withClassLoader

@NonNull
public SelfT withClassLoader(@Nullable
                                      ClassLoader classLoader)

The ClassLoader to use to reflectively load class names defined in configuration.

This is typically only needed when using OSGi or other in environments where there are complex class loading requirements.

If null, the driver attempts to use Thread.getContextClassLoader() of the current thread or the same ClassLoader that loaded the core driver classes.

withCloudSecureConnectBundle

@NonNull
public SelfT withCloudSecureConnectBundle(@NonNull
                                                   Path cloudConfigPath)

Configures this SessionBuilder for Cloud deployments by retrieving connection information from the provided Path.

To connect to a Cloud database, you must first download the secure database bundle from the DataStax Constellation console that contains the connection information, then instruct the driver to read its contents using either this method or one if its variants.

For more information, please refer to the DataStax Constellation documentation.

Parameters:

cloudConfigPath - Path to the secure connect bundle zip file.

See Also:

withCloudSecureConnectBundle(URL), withCloudSecureConnectBundle(InputStream)

withCloudSecureConnectBundle

@NonNull
public SelfT withCloudSecureConnectBundle(@NonNull
                                                   URL cloudConfigUrl)

Configures this SessionBuilder for Cloud deployments by retrieving connection information from the provided URL.

To connect to a Cloud database, you must first download the secure database bundle from the DataStax Constellation console that contains the connection information, then instruct the driver to read its contents using either this method or one if its variants.

For more information, please refer to the DataStax Constellation documentation.

Parameters:

cloudConfigUrl - URL to the secure connect bundle zip file.

See Also:

withCloudSecureConnectBundle(Path), withCloudSecureConnectBundle(InputStream)

withCloudSecureConnectBundle

@NonNull
public SelfT withCloudSecureConnectBundle(@NonNull
                                                   InputStream cloudConfigInputStream)

Configures this SessionBuilder for Cloud deployments by retrieving connection information from the provided InputStream.

To connect to a Cloud database, you must first download the secure database bundle from the DataStax Constellation console that contains the connection information, then instruct the driver to read its contents using either this method or one if its variants.

For more information, please refer to the DataStax Constellation documentation.

Note that the provided stream will be consumed and closed when either build() or buildAsync() are called; attempting to reuse it afterwards will result in an error being thrown.

Parameters:

cloudConfigInputStream - A stream containing the secure connect bundle zip file.

See Also:

withCloudSecureConnectBundle(Path), withCloudSecureConnectBundle(URL)

withCloudProxyAddress

@NonNull
public SelfT withCloudProxyAddress(@Nullable
                                            InetSocketAddress cloudProxyAddress)

Configures this SessionBuilder to use the provided Cloud proxy endpoint.

Normally, this method should not be called directly; the normal and easiest way to configure the driver for Cloud deployments is through a secure connect bundle.

Setting this option to any non-null address will make the driver use a special topology monitor tailored for Cloud deployments. This topology monitor assumes that the target cluster should be contacted through the proxy specified here, using SNI routing.

For more information, please refer to the DataStax Constellation documentation.

Parameters:

cloudProxyAddress - The address of the Cloud proxy to use.

See Also:

Server Name Indication

buildAsync

@NonNull
public CompletionStage<SessionT> buildAsync()

Creates the session with the options set by this builder.

Returns:

a completion stage that completes with the session when it is fully initialized.

build

@NonNull
public SessionT build()

Convenience method to call buildAsync() and block on the result.

This must not be called on a driver thread.

wrap

protected abstract SessionT wrap(@NonNull
                                 CqlSession defaultSession)

buildDefaultSessionAsync

@NonNull
protected final CompletionStage<CqlSession> buildDefaultSessionAsync()

buildContext

protected DriverContext buildContext(DriverConfigLoader configLoader,
                                     ProgrammaticArguments programmaticArguments)

This must return an instance of InternalDriverContext (it's not expressed directly in the signature to avoid leaking that type through the protected API).

buildContext

@Deprecated
protected DriverContext buildContext(DriverConfigLoader configLoader,
                                                 List<TypeCodec<?>> typeCodecs,
                                                 NodeStateListener nodeStateListener,
                                                 SchemaChangeListener schemaChangeListener,
                                                 RequestTracker requestTracker,
                                                 Map<String,String> localDatacenters,
                                                 Map<String,Predicate<Node>> nodeFilters,
                                                 ClassLoader classLoader)

Deprecated. this method only exists for backward compatibility (if a subclass written for driver 4.1.0 returns a non-null result, that value will be used). Please override buildContext(DriverConfigLoader, ProgrammaticArguments) instead.