Package com.cedarsoftware.util

Class UniqueIdGenerator

java.lang.Object
com.cedarsoftware.util.UniqueIdGenerator
public class UniqueIdGenerator extends Object
Generate a unique ID that fits within a long value. The ID will be unique for the given JVM, and it makes a solid attempt to ensure uniqueness in a clustered environment. An environment variable JAVA_UTIL_CLUSTERID can be set to a value 0-99 to mark this JVM uniquely in the cluster. If this environment variable is not set, then hostname, cluster id, and finally a SecureRandom value from 0-99 is chosen for the machine's id within cluster.

There is an API [getUniqueId()] to get a unique ID that will work through the year 5138. This API will generate unique IDs at a rate of up to 1 million per second. There is another API [getUniqueId19()] that will work through the year 2286, however this API will generate unique IDs at a rate up to 10 million per second. The trade-off is the faster API will generate positive IDs only good for about 286 years [after 2000].

The IDs are guaranteed to be strictly increasing. There is an API you can call (getDate(unique)) that will return the date and time (to the millisecond) that the ID was created.
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()
      ID format will be 1234567890123.999.99 (no dots - only there for clarity - the number is a long). There are 13 digits for time - good until 2286, and then it will be 14 digits (good until 5138) for time - milliseconds since Jan 1, 1970. This is followed by a count that is 000 through 999. This is followed by a random 2 digit number. This number is chosen when the JVM is started and then stays fixed until next restart. This is to ensure cluster uniqueness.

      Because there is the possibility two machines could choose the same random number and be at the same count, at the same time, a unique machine index is chosen to provide a 00 to 99 value for machine instance within a cluster. To set the unique machine index value, set the environment variable JAVA_UTIL_CLUSTERID to a unique two-digit number on each machine in the cluster. If the machines are in a managed container, the uniqueId will use the hash of the hostname, first byte of hash, modulo 100 to provide unique machine ID. If neither of these environment variables are set, will it resort to using a secure random number from 00 to 99 for the machine instance number portion of the unique ID.

      This API is slower than the 19 digit API. Grabbing a bunch of IDs in a tight loop for example, could cause delays while it waits for the millisecond to tick over. This API can return up to 1,000 unique IDs per millisecond.

      The IDs returned are guaranteed to be strictly increasing.
      Returns:
      long unique ID

    • getUniqueId19

      public static long getUniqueId19()
      ID format will be 1234567890123.9999.99 (no dots - only there for clarity - the number is a long). There are 13 digits for time - milliseconds since Jan 1, 1970. This is followed by a count that is 0000 through 9999. This is followed by a random 2 digit number. This number is chosen when the JVM is started and then stays fixed until next restart. This is to ensure uniqueness within cluster.

      Because there is the possibility two machines could choose the same random number and be at the same count, at the same time, a unique machine index is chosen to provide a 00 to 99 value for machine instance within a cluster. To set the unique machine index value, set the environment variable JAVA_UTIL_CLUSTERID to a unique two-digit number on each machine in the cluster. If the machines are in a managed container, the uniqueId will use the hash of the hostname, first byte of hash, modulo 100 to provide unique machine ID. If neither of these environment variables are set, will it resort to using a secure random number from 00 to 99 for the machine instance number portion of the unique ID.

      The returned ID will be 19 digits and this API will work through 2286. After then, it will return negative numbers (still unique).

      This API is faster than the 18 digit API. This API can return up to 10,000 unique IDs per millisecond.

      The IDs returned are guaranteed to be strictly increasing.
      Returns:
      long unique ID

    • getDate

      public static Date getDate(long uniqueId)
      Find out when the ID was generated.
      Parameters:
      uniqueId - long unique ID that was generated from the .getUniqueId() API
      Returns:
      Date when the ID was generated, with the time portion accurate to the millisecond. The time is measured in milliseconds, between the time the id was generated and midnight, January 1, 1970 UTC.

    • getDate19

      public static Date getDate19(long uniqueId)
      Find out when the ID was generated. "19" version.
      Parameters:
      uniqueId - long unique ID that was generated from the .getUniqueId19() API
      Returns:
      Date when the ID was generated, with the time portion accurate to the millisecond. The time is measured in milliseconds, between the time the id was generated and midnight, January 1, 1970 UTC.