Package com.datastax.driver.core

Class DelegatingCluster

  • All Implemented Interfaces:
    Closeable, AutoCloseable
    public abstract class DelegatingCluster
extends Cluster
    Base class for custom Cluster implementations that wrap another instance (delegate / decorator pattern).

    • Constructor Detail

      • DelegatingCluster

        protected DelegatingCluster()
        Builds a new instance.

    • Method Detail

      • delegate

        protected abstract Cluster delegate()
        Returns the delegate instance where all calls will be forwarded.
        Returns:
        the delegate.

      • init

        public Cluster init()
        Description copied from class: Cluster
        Initialize this Cluster instance.

        This method creates an initial connection to one of the contact points used to construct the 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.

        Overrides:
        init in class Cluster
        Returns:
        this Cluster object.

      • newSession

        public Session newSession()
        Description copied from class: Cluster
        Creates a new session on this cluster but does not initialize it.

        Because this method does not perform any initialization, it cannot fail. The initialization of the session (the connection of the Session to the Cassandra nodes) will occur if either the 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.

        Overrides:
        newSession in class Cluster
        Returns:
        a new, non-initialized session on this cluster.

      • connect

        public Session connect()
        Description copied from class: Cluster
        Creates a new session on this cluster and initialize it.

        Note that this method will initialize the newly created session, trying to connect to the Cassandra nodes before returning. If you only want to create a Session object without initializing it right away, see Cluster.newSession().

        Overrides:
        connect in class Cluster
        Returns:
        a new session on this cluster sets to no keyspace.

      • connect

        public Session connect​(String keyspace)
        Description copied from class: Cluster
        Creates a new session on this cluster, initialize it and sets the keyspace to the provided one.

        Note that this method will initialize the newly created session, trying to connect to the Cassandra nodes before returning. If you only want to create a Session object without initializing it right away, see Cluster.newSession().

        Overrides:
        connect in class Cluster
        Parameters:
        keyspace - The name of the keyspace to use for the created Session.
        Returns:
        a new session on this cluster sets to keyspace keyspaceName.

      • connectAsync

        public ListenableFuture<Session> connectAsync()
        Description copied from class: Cluster
        Creates a new session on this cluster and initializes it asynchronously.

        This will also initialize the 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.

        Note that if a default keyspace has been configured for use with a DBaaS cluster, this method will attempt to set the session keyspace to that keyspace, effectively behaving like Cluster.connect(String).

        Overrides:
        connectAsync in class Cluster
        Returns:
        a future that will complete when the session is fully initialized.
        See Also:
        Cluster.connect()

      • connectAsync

        public ListenableFuture<Session> connectAsync​(String keyspace)
        Description copied from class: Cluster
        Creates a new session on this cluster, and initializes it to the given keyspace asynchronously.

        This will also initialize the 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.

        Overrides:
        connectAsync in class Cluster
        Parameters:
        keyspace - The name of the keyspace to use for the created Session.
        Returns:
        a future that will complete when the session is fully initialized.

      • getMetadata

        public Metadata getMetadata()
        Description copied from class: Cluster
        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. Since this return metadata on the connected cluster, this method may trigger the creation of a connection if none has been established yet (neither init() nor connect() has been called yet).

        Overrides:
        getMetadata in class Cluster
        Returns:
        the cluster metadata.

      • register

        public Cluster register​(Host.StateListener listener)
        Description copied from class: Cluster
        Registers the provided listener to be notified on hosts up/down/added/removed events.

        Registering the same listener multiple times is a no-op.

        This method should be used to register additional listeners on an already-initialized cluster. To add listeners to a cluster object prior to its initialization, use Cluster.Builder.withInitialListeners(Collection). Calling this method on a non-initialized cluster will result in the listener being notified twice of cluster registration: once inside this method, and once at cluster initialization.

        Overrides:
        register in class Cluster
        Parameters:
        listener - the new Host.StateListener to register.
        Returns:
        this Cluster object;

      • unregister

        public Cluster unregister​(Host.StateListener listener)
        Description copied from class: Cluster
        Unregisters the provided listener from being notified on hosts events.

        This method is a no-op if listener hasn't previously been registered against this Cluster.

        Overrides:
        unregister in class Cluster
        Parameters:
        listener - the Host.StateListener to unregister.
        Returns:
        this Cluster object;

      • register

        public Cluster register​(LatencyTracker tracker)
        Description copied from class: Cluster
        Registers the provided tracker to be updated with hosts read latencies.

        Registering the same tracker multiple times is a no-op.

        Beware that the registered tracker's update method will be called 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 to allow load balancing policies to implement latency awareness. For example, LatencyAwarePolicy registers it's own internal LatencyTracker (automatically, you don't have to call this method directly).

        Overrides:
        register in class Cluster
        Parameters:
        tracker - the new LatencyTracker to register.
        Returns:
        this Cluster object;

      • unregister

        public Cluster unregister​(LatencyTracker tracker)
        Description copied from class: Cluster
        Unregisters the provided latency tracking from being updated with host read latencies.

        This method is a no-op if tracker hasn't previously been registered against this Cluster.

        Overrides:
        unregister in class Cluster
        Parameters:
        tracker - the LatencyTracker to unregister.
        Returns:
        this Cluster object;

      • register

        public Cluster register​(SchemaChangeListener listener)
        Description copied from class: Cluster
        Registers the provided listener to be updated with schema change events.

        Registering the same listener multiple times is a no-op.

        Overrides:
        register in class Cluster
        Parameters:
        listener - the new SchemaChangeListener to register.
        Returns:
        this Cluster object;

      • unregister

        public Cluster unregister​(SchemaChangeListener listener)
        Description copied from class: Cluster
        Unregisters the provided schema change listener from being updated with schema change events.

        This method is a no-op if listener hasn't previously been registered against this Cluster.

        Overrides:
        unregister in class Cluster
        Parameters:
        listener - the SchemaChangeListener to unregister.
        Returns:
        this Cluster object;

      • closeAsync

        public CloseFuture closeAsync()
        Description copied from class: Cluster
        Initiates a shutdown of this cluster instance.

        This method is asynchronous and return a future on the completion of the shutdown process. As soon a the cluster is shutdown, no new request will be accepted, but already submitted queries are allowed to complete. This method closes all connections from all sessions and reclaims all resources used by this Cluster instance.

        If for some reason you wish to expedite this process, the 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).

        Overrides:
        closeAsync in class Cluster
        Returns:
        a future on the completion of the shutdown process.

      • close

        public void close()
        Description copied from class: Cluster
        Initiates a shutdown of this cluster instance and blocks until that shutdown completes.

        This method is a shortcut for closeAsync().get().

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable
        Overrides:
        close in class Cluster

      • isClosed

        public boolean isClosed()
        Description copied from class: Cluster
        Whether this Cluster instance has been closed.

        Note that this method returns true as soon as one of the close methods (Cluster.closeAsync() or Cluster.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).

        Overrides:
        isClosed in class Cluster
        Returns:
        true if this Cluster instance has been closed, false otherwise.