content: /*
   * Licensed to the Apache Software Foundation (ASF) under one
   * or more contributor license agreements.  See the NOTICE file
   * distributed with this work for additional information
   * regarding copyright ownership.  The ASF licenses this file
   * to you under the Apache License, Version 2.0 (the
   * "License"); you may not use this file except in compliance
   * with the License.  You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package com.datastax.oss.driver.api.core.metadata;
  
  import com.datastax.oss.driver.api.core.CqlIdentifier;
  import com.datastax.oss.driver.api.core.ProtocolVersion;
  import com.datastax.oss.driver.api.core.config.DefaultDriverOption;
  import com.datastax.oss.driver.api.core.metadata.token.Token;
  import com.datastax.oss.driver.api.core.metadata.token.TokenRange;
  import com.datastax.oss.driver.api.core.session.Session;
  import com.datastax.oss.driver.api.core.type.codec.TypeCodec;
  import com.datastax.oss.driver.shaded.guava.common.collect.ImmutableSet;
  import edu.umd.cs.findbugs.annotations.NonNull;
  import java.nio.ByteBuffer;
  import java.util.Set;
  
  /**
   * Utility component to work with the tokens of a given driver instance.
   *
   * <p>Note that the methods that take a keyspace argument are based on schema metadata, which can be
   * disabled or restricted to a subset of keyspaces; therefore these methods might return empty
   * results for some or all of the keyspaces.
   *
   * @see DefaultDriverOption#METADATA_SCHEMA_ENABLED
   * @see Session#setSchemaMetadataEnabled(Boolean)
   * @see DefaultDriverOption#METADATA_SCHEMA_REFRESHED_KEYSPACES
   */
  public interface TokenMap {
  
    /** Builds a token from its string representation. */
    @NonNull
    Token parse(@NonNull String tokenString);
  
    /** Formats a token into a string representation appropriate for concatenation in a CQL query. */
    @NonNull
    String format(@NonNull Token token);
  
    /**
     * Builds a token from a partition key.
     *
     * @param partitionKey the partition key components, in their serialized form (which can be
     *     obtained with {@link TypeCodec#encode(Object, ProtocolVersion)}. Neither the individual
     *     components, nor the vararg array itself, can be {@code null}.
     */
    @NonNull
    Token newToken(@NonNull ByteBuffer... partitionKey);
  
    @NonNull
    TokenRange newTokenRange(@NonNull Token start, @NonNull Token end);
  
    /** The token ranges that define data distribution on the ring. */
    @NonNull
    Set<TokenRange> getTokenRanges();
  
    /** The token ranges for which a given node is the primary replica. */
    @NonNull
    Set<TokenRange> getTokenRanges(Node node);
  
    /**
     * The tokens owned by the given node.
     *
     * <p>This is functionally equivalent to {@code getTokenRanges(node).map(r -> r.getEnd())}. Note
     * that the set is rebuilt every time you call this method.
     */
    @NonNull
    default Set<Token> getTokens(@NonNull Node node) {
      ImmutableSet.Builder<Token> result = ImmutableSet.builder();
      for (TokenRange range : getTokenRanges(node)) {
        result.add(range.getEnd());
      }
      return result.build();
    }
  
    /** The token ranges that are replicated on the given node, for the given keyspace. */
    @NonNull
    Set<TokenRange> getTokenRanges(@NonNull CqlIdentifier keyspace, @NonNull Node replica);
  
    /**
     * Shortcut for {@link #getTokenRanges(CqlIdentifier, Node)
     * getTokenRanges(CqlIdentifier.fromCql(keyspaceName), replica)}.
     */
    @NonNull
    default Set<TokenRange> getTokenRanges(@NonNull String keyspaceName, @NonNull Node replica) {
      return getTokenRanges(CqlIdentifier.fromCql(keyspaceName), replica);
    }
  
    /** The replicas for a given partition key in the given keyspace. */
    @NonNull
    Set<Node> getReplicas(@NonNull CqlIdentifier keyspace, @NonNull ByteBuffer partitionKey);
  
    /**
     * Shortcut for {@link #getReplicas(CqlIdentifier, ByteBuffer)
     * getReplicas(CqlIdentifier.fromCql(keyspaceName), partitionKey)}.
     */
    @NonNull
    default Set<Node> getReplicas(@NonNull String keyspaceName, @NonNull ByteBuffer partitionKey) {
      return getReplicas(CqlIdentifier.fromCql(keyspaceName), partitionKey);
    }
  
    /** The replicas for a given token in the given keyspace. */
    @NonNull
    Set<Node> getReplicas(@NonNull CqlIdentifier keyspace, @NonNull Token token);
  
    /**
     * Shortcut for {@link #getReplicas(CqlIdentifier, Token)
     * getReplicas(CqlIdentifier.fromCql(keyspaceName), token)}.
     */
    @NonNull
    default Set<Node> getReplicas(@NonNull String keyspaceName, @NonNull Token token) {
      return getReplicas(CqlIdentifier.fromCql(keyspaceName), token);
    }
  
    /**
     * The replicas for a given range in the given keyspace.
     *
     * <p>It is assumed that the input range does not overlap across multiple node ranges. If the
     * range extends over multiple nodes, it only returns the nodes that are replicas for the last
     * token of the range. In other words, this method is a shortcut for {@code getReplicas(keyspace,
     * range.getEnd())}.
     */
    @NonNull
    default Set<Node> getReplicas(@NonNull CqlIdentifier keyspace, @NonNull TokenRange range) {
      return getReplicas(keyspace, range.getEnd());
    }
  
    /**
     * Shortcut for {@link #getReplicas(CqlIdentifier, TokenRange)
     * getReplicas(CqlIdentifier.fromCql(keyspaceName), range)}.
     */
    @NonNull
    default Set<Node> getReplicas(@NonNull String keyspaceName, @NonNull TokenRange range) {
      return getReplicas(CqlIdentifier.fromCql(keyspaceName), range);
    }
  
    /** The name of the partitioner class in use, as reported by the Cassandra nodes. */
    @NonNull
    String getPartitionerName();
  }
  