Package com.cedarsoftware.util

Class UniqueIdGenerator

java.lang.Object
com.cedarsoftware.util.UniqueIdGenerator
public final class UniqueIdGenerator extends Object
Generates guaranteed unique, time-based, strictly monotonically increasing IDs for distributed systems. Each ID encodes:
  • Timestamp - milliseconds since epoch
  • Sequence number - counter for multiple IDs within the same millisecond
  • Server ID - a 2-digit node identifier (00–99) appended to the ID

Cluster Support

Server IDs are determined in the following priority order (0–99):
  1. Environment variable JAVA_UTIL_CLUSTERID
  2. Indirect environment variable via SystemUtilities.getExternalVariable(JAVA_UTIL_CLUSTERID) (value is another env var name)
  3. Kubernetes pod ordinal (last dash-separated token of HOSTNAME)
  4. VMware Tanzu instance ID (VMWARE_TANZU_INSTANCE_ID)
  5. Cloud Foundry instance index (CF_INSTANCE_INDEX)
  6. Hash of HOSTNAME modulo 100
  7. Secure random (fallback)

Available APIs

Two ID generation methods are provided: 
 getUniqueId()
 - Layout: [timestampMs][sequence-3-digits][serverId-2-digits]
 - Capacity: up to 1,000 IDs per millisecond
 - Positive range: until 4892-10-07T21:52:48.547Z

 getUniqueId19()
 - Layout: [timestampMs][sequence-4-digits][serverId-2-digits]
 - Capacity: up to 10,000 IDs per millisecond
 - Positive range: until 2262-04-11T23:47:16.854Z

Guarantees

  • IDs are strictly monotonically increasing within a process.
  • Clock regressions are handled by not allowing time to go backwards in the ID stream.
  • When per-millisecond capacity is exhausted, generation waits for the next millisecond (no “future” timestamps).
  • Server ID is preserved in the last two digits of every ID; no arithmetic “+1” leaks into serverId.
  • Note: Strict uniqueness across JVM restarts on the same machine is best-effort unless you persist the last seen millisecond and restart from max(persistedMs, now).

Extraction

Author:
John DeRegnaucourt ([email protected]), Roger Judd (@HonorKnight on GitHub) for adding code to ensure increasing order Copyright (c) Cedar Software LLC

Licensed 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

License

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.

  • Field Details

  • Method Details

    • getUniqueId

      public static long getUniqueId()
      Generates a unique, strictly monotonically increasing ID with millisecond precision.

      Layout: [timestampMs][sequence-3-digits][serverId-2-digits]. Supports up to 1,000 IDs per millisecond. When capacity is exhausted, waits for the next millisecond.

      Positive range until 4892-10-07T21:52:48.547Z.

      Returns:
      unique time-based ID as a long

    • getUniqueId19

      public static long getUniqueId19()
      Generates a unique, strictly monotonically increasing 19-digit ID optimized for higher throughput.

      Layout: [timestampMs][sequence-4-digits][serverId-2-digits]. Supports up to 10,000 IDs per millisecond. When capacity is exhausted, waits for the next millisecond.

      Positive range until 2262-04-11T23:47:16.854Z.

      Returns:
      unique time-based ID as a long

    • getDate

      public static Date getDate(long uniqueId)
      Extract timestamp as Date from getUniqueId() values.

    • getDate19

      public static Date getDate19(long uniqueId19)
      Extract timestamp as Date from getUniqueId19() values.

    • getInstant

      public static Instant getInstant(long uniqueId)
      Extract timestamp as Instant from getUniqueId() values.
      Throws:
      IllegalArgumentException - if uniqueId is negative (out of supported range)

    • getInstant19

      public static Instant getInstant19(long uniqueId19)
      Extract timestamp as Instant from getUniqueId19() values.
      Throws:
      IllegalArgumentException - if uniqueId19 is negative (out of supported range)

    • getServerIdConfigured

      public static int getServerIdConfigured()
      Returns the configured server ID (00–99).