com.datastax.driver.core

Class Metadata

java.lang.Object

com.datastax.driver.core.Metadata

public class Metadata
extends Object

Keeps metadata on the connected cluster, including known nodes and schema definitions.

Method Summary

Modifier and Type	Method and Description
boolean	checkSchemaAgreement() Checks whether hosts that are currently up agree on the schema definition.
String	exportSchemaAsString() Returns a String containing CQL queries representing the schema of this cluster.
Set<Host>	getAllHosts() Returns the known hosts of this cluster.
String	getClusterName() The Cassandra name for the cluster connect to.
KeyspaceMetadata	getKeyspace(String keyspace) Returns the metadata of a keyspace given its name.
List<KeyspaceMetadata>	getKeyspaces() Returns a list of all the defined keyspaces.
String	getPartitioner() The partitioner in use as reported by the Cassandra nodes.
Set<Host>	getReplicas(String keyspace, com.datastax.driver.core.Token.Factory partitioner, ByteBuffer partitionKey) Returns the set of hosts that are replica for a given partition key.
Set<Host>	getReplicas(String keyspace, TokenRange range) Returns the set of hosts that are replica for a given token range.
Set<TokenRange>	getTokenRanges() Returns the token ranges that define data distribution in the ring.
Set<TokenRange>	getTokenRanges(String keyspace, Host host) Returns the token ranges that are replicated on the given host, for the given keyspace.
static boolean	isReservedCqlKeyword(String id) Checks whether an identifier is a known reserved CQL keyword or not.
Token	newToken(String tokenStr) Builds a new Token from its string representation, according to the partitioner reported by the Cassandra nodes.
Token	newToken(com.datastax.driver.core.Token.Factory partitioner, ByteBuffer... components) Builds a new Token from a partition key.
TokenRange	newTokenRange(Token start, Token end) Builds a new TokenRange.
TupleType	newTupleType(DataType... types) Creates a tuple type given a list of types.
TupleType	newTupleType(List<DataType> types) Creates a tuple type given a list of types.
static String	quote(String id) Quote a keyspace, table or column identifier to make it case sensitive.
static String	quoteIfNecessary(String id) Quotes a CQL identifier if necessary.

Methods inherited from class java.lang.Object

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

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

quote

public static String quote(String id)

Quote a keyspace, table or column identifier to make it case sensitive.

CQL identifiers, including keyspace, table and column ones, are case insensitive by default. Case sensitive identifiers can however be provided by enclosing the identifier in double quotes (see the CQL documentation for details). If you are using case sensitive identifiers, this method can be used to enclose such identifiers in double quotes, making them case sensitive.

Note that reserved CQL keywords should also be quoted. You can check if a given identifier is a reserved keyword by calling isReservedCqlKeyword(String).

Parameters:

id - the keyspace or table identifier.

Returns:

id enclosed in double-quotes, for use in methods like getReplicas(java.lang.String, com.datastax.driver.core.Token.Factory, java.nio.ByteBuffer), getKeyspace(java.lang.String), KeyspaceMetadata.getTable(java.lang.String) or even Cluster.connect(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

public Set<Host> getReplicas(String keyspace,
                             com.datastax.driver.core.Token.Factory partitioner,
                             ByteBuffer partitionKey)

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

getReplicas

public Set<Host> getReplicas(String keyspace,
                             TokenRange range)

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

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

getKeyspaces

public List<KeyspaceMetadata> getKeyspaces()

Returns a list of all the defined keyspaces.

Returns:

a list of all the defined keyspaces. Note that the result might be stale or empty 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.

newTokenRange

public TokenRange newTokenRange(Token start,
                                Token end)

Builds a new TokenRange.

Parameters:

start - the start token.

end - the end token.

Returns:

the range.

Throws:

IllegalStateException - if the token factory was not initialized. This would typically happen if metadata was explicitly disabled with QueryOptions.setMetadataEnabled(boolean) before startup.