TokenMetadata (apache-cassandra API)
Date: 2018-02-12

org.apache.cassandra.locator

## Class TokenMetadata

- java.lang.Object
- - org.apache.cassandra.locator.TokenMetadata

-     public class TokenMetadata
      extends java.lang.Object

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TokenMetadata.Topology` Tracks the assignment of racks and endpoints in each datacenter for all the "normal" endpoints in this TokenMetadata.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TokenMetadata()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addBootstrapToken(Token token, java.net.InetAddress endpoint)` Deprecated.
    `void` | `addBootstrapTokens(java.util.Collection<Token> tokens, java.net.InetAddress endpoint)`
    `void` | `addLeavingEndpoint(java.net.InetAddress endpoint)`
    `void` | `addMovingEndpoint(Token token, java.net.InetAddress endpoint)` Add a new moving endpoint
    `void` | `addReplaceTokens(java.util.Collection<Token> replacingTokens, java.net.InetAddress newNode, java.net.InetAddress oldNode)`
    `TokenMetadata` | `cachedOnlyTokenMap()` Return a cached TokenMetadata with only tokenToEndpointMap, i.e., the same as cloneOnlyTokenMap but uses a cached copy that is invalided when the ring changes, so in the common case no extra locking is required.
    `void` | `calculatePendingRanges(AbstractReplicationStrategy strategy, java.lang.String keyspaceName)` Calculate pending ranges according to bootsrapping and leaving nodes.
    `void` | `clearUnsafe()` used by tests
    `TokenMetadata` | `cloneAfterAllLeft()` Create a copy of TokenMetadata with tokenToEndpointMap reflecting situation after all current leave operations have finished.
    `TokenMetadata` | `cloneAfterAllSettled()` Create a copy of TokenMetadata with tokenToEndpointMap reflecting situation after all current leave, and move operations have finished.
    `TokenMetadata` | `cloneOnlyTokenMap()` Create a copy of TokenMetadata with only tokenToEndpointMap.
    `static Token` | `firstToken(java.util.ArrayList<Token> ring, Token start)`
    `static int` | `firstTokenIndex(java.util.ArrayList ring, Token start, boolean insertMin)`
    `java.util.Set<java.net.InetAddress>` | `getAllEndpoints()`
    `BiMultiValMap<Token,java.net.InetAddress>` | `getBootstrapTokens()`
    `java.net.InetAddress` | `getEndpoint(Token token)`
    `java.net.InetAddress` | `getEndpointForHostId(java.util.UUID hostId)` Return the end-point for a unique host ID
    `java.util.Map<java.net.InetAddress,java.util.UUID>` | `getEndpointToHostIdMapForReading()`
    `com.google.common.collect.Multimap<java.net.InetAddress,Token>` | `getEndpointToTokenMapForReading()`
    `java.util.UUID` | `getHostId(java.net.InetAddress endpoint)` Return the unique host ID for an end-point.
    `java.util.Set<java.net.InetAddress>` | `getLeavingEndpoints()` caller should not modify leavingEndpoints
    `java.util.Set<Pair<Token,java.net.InetAddress>>` | `getMovingEndpoints()` Endpoints which are migrating to the new tokens
    `java.util.Map<Token,java.net.InetAddress>` | `getNormalAndBootstrappingTokenToEndpointMap()`
    `PendingRangeMaps` | `getPendingRanges(java.lang.String keyspaceName)` a mutable map may be returned but caller should not modify it
    `java.util.List<Range<Token>>` | `getPendingRanges(java.lang.String keyspaceName, java.net.InetAddress endpoint)`
    `com.google.common.collect.Multimap<Range<Token>,java.net.InetAddress>` | `getPendingRangesMM(java.lang.String keyspaceName)`
    `Token` | `getPredecessor(Token token)`
    `Range<Token>` | `getPrimaryRangeFor(Token right)` Deprecated.
    `java.util.Collection<Range<Token>>` | `getPrimaryRangesFor(java.util.Collection<Token> tokens)`
    `com.google.common.base.Optional<java.net.InetAddress>` | `getReplacementNode(java.net.InetAddress endpoint)`
    `com.google.common.base.Optional<java.net.InetAddress>` | `getReplacingNode(java.net.InetAddress endpoint)`
    `long` | `getRingVersion()`
    `Token` | `getSuccessor(Token token)`
    `Token` | `getToken(java.net.InetAddress endpoint)` Deprecated.
    `java.util.Collection<Token>` | `getTokens(java.net.InetAddress endpoint)`
    `TokenMetadata.Topology` | `getTopology()`
    `java.util.Collection<java.net.InetAddress>` | `getWriteEndpoints(Token token, java.lang.String keyspaceName, java.util.Collection<java.net.InetAddress> naturalEndpoints)` Deprecated. retained for benefit of old tests
    `void` | `invalidateCachedRings()`
    `boolean` | `isLeaving(java.net.InetAddress endpoint)`
    `boolean` | `isMember(java.net.InetAddress endpoint)`
    `boolean` | `isMoving(java.net.InetAddress endpoint)`
    `java.util.Collection<java.net.InetAddress>` | `pendingEndpointsFor(Token token, java.lang.String keyspaceName)`
    `int` | `pendingRangeChanges(java.net.InetAddress source)`
    `void` | `removeBootstrapTokens(java.util.Collection<Token> tokens)`
    `void` | `removeEndpoint(java.net.InetAddress endpoint)`
    `void` | `removeFromMoving(java.net.InetAddress endpoint)` Remove pair of token/address from moving endpoints
    `static java.util.Iterator<Token>` | `ringIterator(java.util.ArrayList<Token> ring, Token start, boolean includeMin)` iterator over the Tokens in the given ring, starting with the token for the node owning start (which does not have to be a Token in the ring)
    `java.util.ArrayList<Token>` | `sortedTokens()`
    `java.lang.String` | `toString()`
    `void` | `updateHostId(java.util.UUID hostId, java.net.InetAddress endpoint)` Store an end-point to host ID mapping.
    `void` | `updateNormalToken(Token token, java.net.InetAddress endpoint)` Update token map with a single token/endpoint pair in normal state.
    `void` | `updateNormalTokens(java.util.Collection<Token> tokens, java.net.InetAddress endpoint)`
    `void` | `updateNormalTokens(com.google.common.collect.Multimap<java.net.InetAddress,Token> endpointTokens)` Update token map with a set of token/endpoint pairs in normal state.
    `void` | `updateTopology()` This is called when the snitch properties for many endpoints are updated, it will update the topology mappings of any endpoints whose snitch has changed, see CASSANDRA-10238.
    `void` | `updateTopology(java.net.InetAddress endpoint)` This is called when the snitch properties for this endpoint are updated, see CASSANDRA-10238.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### TokenMetadata

          public TokenMetadata()

  - ### Method Detail

    - #### pendingRangeChanges

          public int pendingRangeChanges(java.net.InetAddress source)

      Returns:
        the number of nodes bootstrapping into source's primary range

    - #### updateNormalToken

          public void updateNormalToken(Token token,
                                        java.net.InetAddress endpoint)

      Update token map with a single token/endpoint pair in normal state.

    - #### updateNormalTokens

          public void updateNormalTokens(java.util.Collection<Token> tokens,
                                         java.net.InetAddress endpoint)

    - #### updateNormalTokens

          public void updateNormalTokens(com.google.common.collect.Multimap<java.net.InetAddress,Token> endpointTokens)

      Update token map with a set of token/endpoint pairs in normal state. Prefer this whenever there are multiple pairs to update, as each update (whether a single or multiple) is expensive (CASSANDRA-3831).

    - #### updateHostId

          public void updateHostId(java.util.UUID hostId,
                                   java.net.InetAddress endpoint)

      Store an end-point to host ID mapping. Each ID must be unique, and cannot be changed after the fact.

    - #### getHostId

          public java.util.UUID getHostId(java.net.InetAddress endpoint)

      Return the unique host ID for an end-point.

    - #### getEndpointForHostId

          public java.net.InetAddress getEndpointForHostId(java.util.UUID hostId)

      Return the end-point for a unique host ID

    - #### getEndpointToHostIdMapForReading

          public java.util.Map<java.net.InetAddress,java.util.UUID> getEndpointToHostIdMapForReading()

      Returns:
        a copy of the endpoint-to-id map for read-only operations

    - #### addBootstrapToken

          @Deprecated
          public void addBootstrapToken(Token token,
                                                    java.net.InetAddress endpoint)

      Deprecated.

    - #### addBootstrapTokens

          public void addBootstrapTokens(java.util.Collection<Token> tokens,
                                         java.net.InetAddress endpoint)

    - #### addReplaceTokens

          public void addReplaceTokens(java.util.Collection<Token> replacingTokens,
                                       java.net.InetAddress newNode,
                                       java.net.InetAddress oldNode)

    - #### getReplacementNode

          public com.google.common.base.Optional<java.net.InetAddress> getReplacementNode(java.net.InetAddress endpoint)

    - #### getReplacingNode

          public com.google.common.base.Optional<java.net.InetAddress> getReplacingNode(java.net.InetAddress endpoint)

    - #### removeBootstrapTokens

          public void removeBootstrapTokens(java.util.Collection<Token> tokens)

    - #### addLeavingEndpoint

          public void addLeavingEndpoint(java.net.InetAddress endpoint)

    - #### addMovingEndpoint

          public void addMovingEndpoint(Token token,
                                        java.net.InetAddress endpoint)

      Add a new moving endpoint
      Parameters:
        `token` - token which is node moving to
        `endpoint` - address of the moving node

    - #### removeEndpoint

          public void removeEndpoint(java.net.InetAddress endpoint)

    - #### updateTopology

          public void updateTopology(java.net.InetAddress endpoint)

      This is called when the snitch properties for this endpoint are updated, see CASSANDRA-10238.

    - #### updateTopology

          public void updateTopology()

      This is called when the snitch properties for many endpoints are updated, it will update the topology mappings of any endpoints whose snitch has changed, see CASSANDRA-10238.

    - #### removeFromMoving

          public void removeFromMoving(java.net.InetAddress endpoint)

      Remove pair of token/address from moving endpoints
      Parameters:
        `endpoint` - address of the moving node

    - #### getTokens

          public java.util.Collection<Token> getTokens(java.net.InetAddress endpoint)

    - #### getToken

          @Deprecated
          public Token getToken(java.net.InetAddress endpoint)

      Deprecated.

    - #### isMember

          public boolean isMember(java.net.InetAddress endpoint)

    - #### isLeaving

          public boolean isLeaving(java.net.InetAddress endpoint)

    - #### isMoving

          public boolean isMoving(java.net.InetAddress endpoint)

    - #### cloneOnlyTokenMap

          public TokenMetadata cloneOnlyTokenMap()

      Create a copy of TokenMetadata with only tokenToEndpointMap. That is, pending ranges, bootstrap tokens and leaving endpoints are not included in the copy.

    - #### cachedOnlyTokenMap

          public TokenMetadata cachedOnlyTokenMap()

      Return a cached TokenMetadata with only tokenToEndpointMap, i.e., the same as cloneOnlyTokenMap but uses a cached copy that is invalided when the ring changes, so in the common case no extra locking is required. Callers must *NOT* mutate the returned metadata object.

    - #### cloneAfterAllLeft

          public TokenMetadata cloneAfterAllLeft()

      Create a copy of TokenMetadata with tokenToEndpointMap reflecting situation after all current leave operations have finished.
      Returns:
        new token metadata

    - #### cloneAfterAllSettled

          public TokenMetadata cloneAfterAllSettled()

      Create a copy of TokenMetadata with tokenToEndpointMap reflecting situation after all current leave, and move operations have finished.
      Returns:
        new token metadata

    - #### getEndpoint

          public java.net.InetAddress getEndpoint(Token token)

    - #### getPrimaryRangesFor

          public java.util.Collection<Range<Token>> getPrimaryRangesFor(java.util.Collection<Token> tokens)

    - #### getPrimaryRangeFor

          @Deprecated
          public Range<Token> getPrimaryRangeFor(Token right)

      Deprecated.

    - #### sortedTokens

          public java.util.ArrayList<Token> sortedTokens()

    - #### getPendingRangesMM

          public com.google.common.collect.Multimap<Range<Token>,java.net.InetAddress> getPendingRangesMM(java.lang.String keyspaceName)

    - #### getPendingRanges

          public PendingRangeMaps getPendingRanges(java.lang.String keyspaceName)

      a mutable map may be returned but caller should not modify it

    - #### getPendingRanges

          public java.util.List<Range<Token>> getPendingRanges(java.lang.String keyspaceName,
                                                               java.net.InetAddress endpoint)

    - #### calculatePendingRanges

          public void calculatePendingRanges(AbstractReplicationStrategy strategy,
                                             java.lang.String keyspaceName)

      Calculate pending ranges according to bootsrapping and leaving nodes. Reasoning is: (1) When in doubt, it is better to write too much to a node than too little. That is, if there are multiple nodes moving, calculate the biggest ranges a node could have. Cleaning up unneeded data afterwards is better than missing writes during movement. (2) When a node leaves, ranges for other nodes can only grow (a node might get additional ranges, but it will not lose any of its current ranges as a result of a leave). Therefore we will first remove _all_ leaving tokens for the sake of calculation and then check what ranges would go where if all nodes are to leave. This way we get the biggest possible ranges with regard current leave operations, covering all subsets of possible final range values. (3) When a node bootstraps, ranges of other nodes can only get smaller. Without doing complex calculations to see if multiple bootstraps overlap, we simply base calculations on the same token ring used before (reflecting situation after all leave operations have completed). Bootstrapping nodes will be added and removed one by one to that metadata and checked what their ranges would be. This will give us the biggest possible ranges the node could have. It might be that other bootstraps make our actual final ranges smaller, but it does not matter as we can clean up the data afterwards. NOTE: This is heavy and ineffective operation. This will be done only once when a node changes state in the cluster, so it should be manageable.

    - #### getPredecessor

          public Token getPredecessor(Token token)

    - #### getSuccessor

          public Token getSuccessor(Token token)

    - #### getBootstrapTokens

          public BiMultiValMap<Token,java.net.InetAddress> getBootstrapTokens()

      Returns:
        a copy of the bootstrapping tokens map

    - #### getAllEndpoints

          public java.util.Set<java.net.InetAddress> getAllEndpoints()

    - #### getLeavingEndpoints

          public java.util.Set<java.net.InetAddress> getLeavingEndpoints()

      caller should not modify leavingEndpoints

    - #### getMovingEndpoints

          public java.util.Set<Pair<Token,java.net.InetAddress>> getMovingEndpoints()

      Endpoints which are migrating to the new tokens
      Returns:
        set of addresses of moving endpoints

    - #### firstTokenIndex

          public static int firstTokenIndex(java.util.ArrayList ring,
                                            Token start,
                                            boolean insertMin)

    - #### firstToken

          public static Token firstToken(java.util.ArrayList<Token> ring,
                                         Token start)

    - #### ringIterator

          public static java.util.Iterator<Token> ringIterator(java.util.ArrayList<Token> ring,
                                                               Token start,
                                                               boolean includeMin)

      iterator over the Tokens in the given ring, starting with the token for the node owning start (which does not have to be a Token in the ring)
      Parameters:
        `includeMin` - True if the minimum token should be returned in the ring even if it has no owner.

    - #### clearUnsafe

          public void clearUnsafe()

      used by tests

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### pendingEndpointsFor

          public java.util.Collection<java.net.InetAddress> pendingEndpointsFor(Token token,
                                                                                java.lang.String keyspaceName)

    - #### getWriteEndpoints

          public java.util.Collection<java.net.InetAddress> getWriteEndpoints(Token token,
                                                                              java.lang.String keyspaceName,
                                                                              java.util.Collection<java.net.InetAddress> naturalEndpoints)

      Deprecated. retained for benefit of old tests

    - #### getEndpointToTokenMapForReading

          public com.google.common.collect.Multimap<java.net.InetAddress,Token> getEndpointToTokenMapForReading()

      Returns:
        an endpoint to token multimap representation of tokenToEndpointMap (a copy)

    - #### getNormalAndBootstrappingTokenToEndpointMap

          public java.util.Map<Token,java.net.InetAddress> getNormalAndBootstrappingTokenToEndpointMap()

      Returns:
        a (stable copy, won't be modified) Token to Endpoint map for all the normal and bootstrapping nodes in the cluster.

    - #### getTopology

          public TokenMetadata.Topology getTopology()

      Returns:
        the Topology map of nodes to DCs + Racks This is only allowed when a copy has been made of TokenMetadata, to avoid concurrent modifications when Topology methods are subsequently used by the caller.

    - #### getRingVersion

          public long getRingVersion()

    - #### invalidateCachedRings

          public void invalidateCachedRings()

Copyright © 2018 The Apache Software Foundation