com.datastax.oss.driver.api.core.metadata.token

Interface TokenRange

All Superinterfaces:

Comparable<TokenRange>

public interface TokenRange
extends Comparable<TokenRange>

A range of tokens on the Cassandra ring.

A range is start-exclusive and end-inclusive. It is empty when start and end are the same token, except if that is the minimum token, in which case the range covers the whole ring (this is consistent with the behavior of CQL range queries).

Note that CQL does not handle wrapping. To query all partitions in a range, see unwrap().

Method Summary

Modifier and Type	Method and Description
boolean	contains(Token token) Checks whether this range contains a given token, i.e.
Token	getEnd() The end of the range (inclusive).
Token	getStart() The start of the range (exclusive).
boolean	intersects(TokenRange that) Whether this range intersects another one.
List<TokenRange>	intersectWith(TokenRange that) Computes the intersection of this range with another one, producing one or more ranges.
boolean	isEmpty() Whether this range is empty.
boolean	isFullRing() Whether this range represents the full ring.
boolean	isWrappedAround() Whether this range wraps around the end of the ring.
TokenRange	mergeWith(TokenRange that) Merges this range with another one.
List<TokenRange>	splitEvenly(int numberOfSplits) Splits this range into a number of smaller ranges of equal "size" (referring to the number of tokens, not the actual amount of data).
List<TokenRange>	unwrap() Splits this range into a list of two non-wrapping ranges.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getStart

@NonNull
Token getStart()

The start of the range (exclusive).

getEnd

@NonNull
Token getEnd()

The end of the range (inclusive).

splitEvenly

@NonNull
List<TokenRange> splitEvenly(int numberOfSplits)

Splits this range into a number of smaller ranges of equal "size" (referring to the number of tokens, not the actual amount of data).

Splitting an empty range is not permitted. But note that, in edge cases, splitting a range might produce one or more empty ranges.

Throws:

IllegalArgumentException - if the range is empty or if numberOfSplits < 1.

isEmpty

boolean isEmpty()

Whether this range is empty.

A range is empty when getStart() and getEnd() are the same token, except if that is the minimum token, in which case the range covers the whole ring (this is consistent with the behavior of CQL range queries).

isWrappedAround

boolean isWrappedAround()

Whether this range wraps around the end of the ring.

isFullRing

boolean isFullRing()

Whether this range represents the full ring.

unwrap

@NonNull
List<TokenRange> unwrap()

Splits this range into a list of two non-wrapping ranges. This will return the range itself if it is non-wrapping, or two ranges otherwise.

For example:

• ]1,10] unwraps to itself;
• ]10,1] unwraps to ]10,min_token] and ]min_token,1].

This is useful for CQL range queries, which do not handle wrapping:

 List<Row> rows = new ArrayList<Row>();
 for (TokenRange subRange : range.unwrap()) {
     ResultSet rs = session.execute(
         "SELECT * FROM mytable WHERE token(pk) > ? and token(pk) <= ?",
         subRange.getStart(), subRange.getEnd());
     rows.addAll(rs.all());
 }
 

intersects

boolean intersects(@NonNull
                   TokenRange that)

Whether this range intersects another one.

For example:

• ]3,5] intersects ]1,4], ]4,5]...
• ]3,5] does not intersect ]1,2], ]2,3], ]5,7]...

intersectWith

@NonNull
List<TokenRange> intersectWith(@NonNull
                                        TokenRange that)

Computes the intersection of this range with another one, producing one or more ranges.

If either of these ranges overlap the the ring, they are unwrapped and the unwrapped ranges are compared to one another.

This call will fail if the two ranges do not intersect, you must check by calling intersects(TokenRange) first.

Parameters:

that - the other range.

Returns:

the range(s) resulting from the intersection.

Throws:

IllegalArgumentException - if the ranges do not intersect.

contains

boolean contains(@NonNull
                 Token token)

Checks whether this range contains a given token, i.e. range.start < token <= range.end.

mergeWith

@NonNull
TokenRange mergeWith(@NonNull
                              TokenRange that)

Merges this range with another one.

The two ranges should either intersect or be adjacent; in other words, the merged range should not include tokens that are in neither of the original ranges.

For example:

• merging ]3,5] with ]4,7] produces ]3,7];
• merging ]3,5] with ]4,5] produces ]3,5];
• merging ]3,5] with ]5,8] produces ]3,8];
• merging ]3,5] with ]6,8] fails.

Throws:

IllegalArgumentException - if the ranges neither intersect nor are adjacent.