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 a SecureRandom value from 0-99 is chosen for the machine cluster id.

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()) that will return the date and time (to the millisecond) that they 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

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.

Field Summary

Fields

Modifier and Type	Field and Description
static String	JAVA_UTIL_CLUSTERID

Method Summary

Modifier and Type	Method and Description
static Date	getDate(long uniqueId) Find out when the ID was generated.
static Date	getDate19(long uniqueId) Find out when the ID was generated.
static long	getUniqueId() ID format will be 1234567890123.999.99 (no dots - only there for clarity - the number is a long).
static long	getUniqueId19() ID format will be 1234567890123.9999.99 (no dots - only there for clarity - the number is a long).

Methods inherited from class java.lang.Object

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

Field Detail

JAVA_UTIL_CLUSTERID

public static final String JAVA_UTIL_CLUSTERID

See Also:

Constant Field Values

Method Detail

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.

There is the possibility two machines could choose the same random number at start. Even still, collisions would be highly unlikely because for a collision to occur, a number would have to be chosen at the same millisecond with the count at the same position.

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 1,000 unique IDs per millisecond max.

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 cluster uniqueness.

There is the possibility two machines could choose the same random number at start. Even still, collisions would be highly unlikely because for a collision to occur, a number would have to be chosen at the same millisecond with the count at the same position.

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

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

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.