Package org.apache.polaris.persistence.nosql.nodeids.api

Interface NodeManagement

All Superinterfaces:
AutoCloseable
public interface NodeManagement extends AutoCloseable
API to lease node IDs, primarily to generate snowflake IDs.

The default configuration for the snowflake IDs allows generation of 4096 IDs per millisecond (12 sequence bits), which should be more than enough. As a consequence, it is very likely enough to have only one ID generator per JVM, across all realms and catalogs.

Implementation is provided as an @ApplicationScoped bean

  • Method Summary

    Modifier and Type
    Method
    Description
    org.apache.polaris.ids.api.IdGenerator
    buildIdGenerator(@NonNull NodeLease leasedNode)
    Build a new and independent ID generator instance of a leased node using the given clock.
    Optional<Node>
    getNodeInfo(int nodeId)
    Retrieve information about a specific node.
    @NonNull NodeLease
    lease()
    Lease a node.
    int
    maxNumberOfNodes()
    The maximum number of concurrently leased nodes that are supported.
    long
    systemIdForNode(int nodeId)
    Get the persistence ID for a node by its ID.

    Methods inherited from interface java.lang.AutoCloseable

    close

  • Method Details

    • buildIdGenerator

      org.apache.polaris.ids.api.IdGenerator buildIdGenerator(@NonNull NodeLease leasedNode)
      Build a new and independent ID generator instance of a leased node using the given clock.

      Calling this method more than once for the same live lease can create multiple generators that emit overlapping Snowflake IDs. A lease must therefore back at most one long-lived ID generator instance.

      This function must only be called from @ApplicationScoped CDI producers providing the same IdGenerator for the lifetime of the given NodeLease, aka at most once per lease.

    • maxNumberOfNodes

      int maxNumberOfNodes()
      The maximum number of concurrently leased nodes that are supported.

    • getNodeInfo

      Optional<Node> getNodeInfo(int nodeId)
      Retrieve information about a specific node.

    • systemIdForNode

      long systemIdForNode(int nodeId)
      Get the persistence ID for a node by its ID.

    • lease

      @NonNull NodeLease lease()
      Lease a node.

      The implementation takes care of periodically renewing the lease. It is not necessary to explicitly call NodeLease.renew().

      It is possible that the ID of the leased node changes over time.

      Each invocation returns a new, independent lease.

      Returns:
      the leased node
      Throws:
      IllegalStateException - if no node ID could be leased