Package com.datastax.driver.core

Class Metadata

  • public class Metadata
extends Object
    Keeps metadata on the connected cluster, including known nodes and schema definitions.

    • Method Detail

      • quoteIfNecessary

        public static String quoteIfNecessary​(String id)
        Quotes a CQL identifier if necessary.

        This is similar to quote(String), except that it won't quote the input string if it can safely be used as-is. For example:

        • quoteIfNecessary("foo").equals("foo") (no need to quote).
        • quoteIfNecessary("Foo").equals("\"Foo\"") (identifier is mixed case so case sensitivity is required)
        • quoteIfNecessary("foo bar").equals("\"foo bar\"") (identifier contains special characters)
        • quoteIfNecessary("table").equals("\"table\"") (identifier is a reserved CQL keyword)
        Parameters:
        id - the "internal" form of the identifier. That is, the identifier as it would appear in Cassandra system tables (such as system_schema.tables, system_schema.columns, etc.)
        Returns:
        the identifier as it would appear in a CQL query string. This is also how you need to pass it to public driver methods, such as getKeyspace(String).

      • isReservedCqlKeyword

        public static boolean isReservedCqlKeyword​(String id)
        Checks whether an identifier is a known reserved CQL keyword or not.

        The check is case-insensitive, i.e., the word "KeYsPaCe" would be considered as a reserved CQL keyword just as "keyspace".

        Note: The list of reserved CQL keywords is subject to change in future versions of Cassandra. As a consequence, this method is provided solely as a convenience utility and should not be considered as an authoritative source of truth for checking reserved CQL keywords.

        Parameters:
        id - the identifier to check; should not be null.
        Returns:
        true if the given identifier is a known reserved CQL keyword, false otherwise.

      • getTokenRanges

        public Set<TokenRange> getTokenRanges()
        Returns the token ranges that define data distribution in the ring.

        Note that this information is refreshed asynchronously by the control connection, when schema or ring topology changes. It might occasionally be stale.

        Returns:
        the token ranges. Note that the result might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • getTokenRanges

        public Set<TokenRange> getTokenRanges​(String keyspace,
                                      Host host)
        Returns the token ranges that are replicated on the given host, for the given keyspace.

        Note that this information is refreshed asynchronously by the control connection, when schema or ring topology changes. It might occasionally be stale (or even empty).

        Parameters:
        keyspace - the name of the keyspace to get token ranges for.
        host - the host.
        Returns:
        the (immutable) set of token ranges for host as known by the driver. Note that the result might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • getReplicas

        @Deprecated
@Beta
public Set<Host> getReplicas​(String keyspace,
                             String table,
                             com.datastax.driver.core.Token.Factory partitioner,
                             ByteBuffer partitionKey)
        Deprecated.
        use getReplicasList(String, String, Token.Factory, ByteBuffer)
        Extension of legacy method getReplicas(String, Token.Factory, ByteBuffer). Tablets model requires knowledge of the table name to determine the replicas. This method will first try to lookup replicas through known tablets metadata. It will default to TokenMap lookup if either null was passed as table name or the tablet lookup is unsuccessful for any other reason.

        Returns the set of hosts that are replica for a given partition key. Partitioner can be null and then a cluster-wide partitioner will be invoked.

        Note that this information is refreshed asynchronously by the control connection, when schema or ring topology changes. It might occasionally be stale (or even empty).

        Parameters:
        keyspace - the name of the keyspace to get replicas for.
        table - the name of the table to get replicas for. Necessary for distinction for tablets. Unnecessary for regular TokenMap
        partitioner - the partitioner to use or @{code null} for cluster-wide partitioner.
        partitionKey - the partition key for which to find the set of replica.
        Returns:
        the (immutable) set of replicas for partitionKey as known by the driver. Note that the result might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • getReplicasList

        @Beta
public List<Host> getReplicasList​(String keyspace,
                                  String table,
                                  com.datastax.driver.core.Token.Factory partitioner,
                                  ByteBuffer partitionKey)
        Extension of legacy method getReplicas(String, Token.Factory, ByteBuffer). Tablets model requires knowledge of the table name to determine the replicas. This method will first try to lookup replicas through known tablets metadata. It will default to TokenMap lookup if either null was passed as table name or the tablet lookup is unsuccessful for any other reason.

        Returns the list of hosts that are replica for a given partition key. Partitioner can be null and then a cluster-wide partitioner will be invoked.

        Note that this information is refreshed asynchronously by the control connection, when schema or ring topology changes. It might occasionally be stale (or even empty).

        Parameters:
        keyspace - the name of the keyspace to get replicas for.
        table - the name of the table to get replicas for. Necessary for distinction for tablets. Unnecessary for regular TokenMap
        partitioner - the partitioner to use or @{code null} for cluster-wide partitioner.
        partitionKey - the partition key for which to find the list of replica.
        Returns:
        the (immutable) list of replicas for partitionKey as known by the driver. Note that the result might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • getReplicas

        @Deprecated
public Set<Host> getReplicas​(String keyspace,
                             com.datastax.driver.core.Token.Factory partitioner,
                             ByteBuffer partitionKey)
        Deprecated.
        use getReplicasList(String, Token.Factory, ByteBuffer)
        Returns the set of hosts that are replica for a given partition key. Partitioner can be null and then a cluster-wide partitioner will be invoked.

        Note that this information is refreshed asynchronously by the control connection, when schema or ring topology changes. It might occasionally be stale (or even empty).

        Parameters:
        keyspace - the name of the keyspace to get replicas for.
        partitioner - the partitioner to use or @{code null} for cluster-wide partitioner.
        partitionKey - the partition key for which to find the set of replica.
        Returns:
        the (immutable) set of replicas for partitionKey as known by the driver. Note that the result might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • getReplicasList

        public List<Host> getReplicasList​(String keyspace,
                                  com.datastax.driver.core.Token.Factory partitioner,
                                  ByteBuffer partitionKey)
        Returns the immutable list of hosts that are replica for a given partition key. Partitioner can be null and then a cluster-wide partitioner will be invoked.

        Note that this information is refreshed asynchronously by the control connection, when schema or ring topology changes. It might occasionally be stale (or even empty).

        Parameters:
        keyspace - the name of the keyspace to get replicas for.
        partitioner - the partitioner to use or @{code null} for cluster-wide partitioner.
        partitionKey - the partition key for which to find the set of replica.
        Returns:
        the (immutable) list of replicas for partitionKey as known by the driver. Note that the result might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • getReplicas

        public Set<Host> getReplicas​(String keyspace,
                             TokenRange range)
        Deprecated.
        use getReplicasList(String, TokenRange)
        Returns the set of hosts that are replica for a given token range.

        Note that it is assumed that the input range does not overlap across multiple host ranges. If the range extends over multiple hosts, it only returns the replicas for those hosts that are replicas for the last token of the range. This behavior may change in a future release, see JAVA-1355.

        Also note that this information is refreshed asynchronously by the control connection, when schema or ring topology changes. It might occasionally be stale (or even empty).

        Parameters:
        keyspace - the name of the keyspace to get replicas for.
        range - the token range.
        Returns:
        the (immutable) set of replicas for range as known by the driver. Note that the result might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • getReplicasList

        public List<Host> getReplicasList​(String keyspace,
                                  TokenRange range)
        Returns the list of hosts that are replica for a given token range.

        Note that it is assumed that the input range does not overlap across multiple host ranges. If the range extends over multiple hosts, it only returns the replicas for those hosts that are replicas for the last token of the range. This behavior may change in a future release, see JAVA-1355.

        Also note that this information is refreshed asynchronously by the control connection, when schema or ring topology changes. It might occasionally be stale (or even empty).

        Parameters:
        keyspace - the name of the keyspace to get replicas for.
        range - the token range.
        Returns:
        the list of replicas for range as known by the driver. Note that the result might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • getClusterName

        public String getClusterName()
        The Cassandra name for the cluster connect to.
        Returns:
        the Cassandra name for the cluster connect to.

      • getPartitioner

        public String getPartitioner()
        The partitioner in use as reported by the Cassandra nodes.
        Returns:
        the partitioner in use as reported by the Cassandra nodes.

      • getAllHosts

        public Set<Host> getAllHosts()
        Returns the known hosts of this cluster.
        Returns:
        A set will all the know host of this cluster.

      • checkSchemaAgreement

        public boolean checkSchemaAgreement()
        Checks whether hosts that are currently up agree on the schema definition.

        This method performs a one-time check only, without any form of retry; therefore Cluster.Builder.withMaxSchemaAgreementWaitSeconds(int) does not apply in this case.

        Returns:
        true if all hosts agree on the schema; false if they don't agree, or if the check could not be performed (for example, if the control connection is down).

      • getKeyspace

        public KeyspaceMetadata getKeyspace​(String keyspace)
        Returns the metadata of a keyspace given its name.
        Parameters:
        keyspace - the name of the keyspace for which metadata should be returned.
        Returns:
        the metadata of the requested keyspace or null if keyspace is not a known keyspace. Note that the result might be stale or null if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

      • exportSchemaAsString

        public String exportSchemaAsString()
        Returns a String containing CQL queries representing the schema of this cluster.

        In other words, this method returns the queries that would allow to recreate the schema of this cluster.

        Note that the returned String is formatted to be human readable (for some definition of human readable at least).

        It might be stale or empty if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean).

        Returns:
        the CQL queries representing this cluster schema as a {code String}.

      • newTupleType

        public TupleType newTupleType​(DataType... types)
        Creates a tuple type given a list of types.
        Parameters:
        types - the types for the tuple type.
        Returns:
        the newly created tuple type.

      • newTupleType

        public TupleType newTupleType​(List<DataType> types)
        Creates a tuple type given a list of types.
        Parameters:
        types - the types for the tuple type.
        Returns:
        the newly created tuple type.

      • newToken

        public Token newToken​(String tokenStr)
        Builds a new Token from its string representation, according to the partitioner reported by the Cassandra nodes.
        Parameters:
        tokenStr - the string representation.
        Returns:
        the token.
        Throws:
        IllegalStateException - if the token factory was not initialized. This would typically happen if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean) before startup.

      • newToken

        public Token newToken​(com.datastax.driver.core.Token.Factory partitioner,
                      ByteBuffer... components)
        Builds a new Token from a partition key. Partitioner can be null and then a cluster-wide partitioner will be invoked.
        Parameters:
        partitioner - the partitioner to use or @{code null} for cluster-wide partitioner.
        components - the components of the partition key, in their serialized form (obtained with TypeCodec.serialize(Object, ProtocolVersion)).
        Returns:
        the token.
        Throws:
        IllegalStateException - if the token factory was not initialized. This would typically happen if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean) before startup.

      • getShardForTabletToken

        @Beta
public int getShardForTabletToken​(String keyspace,
                                  String table,
                                  com.datastax.driver.core.Token.TokenLong64 token,
                                  Host host)