org.apache.commons.id.serial
Class TimeBasedAlphanumericIdentifierGenerator

java.lang.Object
  org.apache.commons.id.AbstractStringIdentifierGenerator
      org.apache.commons.id.serial.TimeBasedAlphanumericIdentifierGenerator

All Implemented Interfaces:

java.io.Serializable, IdentifierGenerator, StringIdentifierGenerator

public class TimeBasedAlphanumericIdentifierGenerator
extends AbstractStringIdentifierGenerator
implements java.io.Serializable

TimeBasedAlphanumericIdentifierGenerator is an identifier generator that generates an alphanumeric identifier in base 36 as a String object from the current UTC time and an internal counter.

The generator guarantees that all generated ids have an increasing natural sort order (even if the time internally has an overflow). The implementation additionally guarantees, that all instances within the same process do generate unique ids. All generated ids have the same length (padding with 0's on the left), which is determined by the maximum size of a long value and the postfixSize parameter passed to the constructor.

Note: To ensure unique ids that are created within the same millisecond (or maximum time resolution of the system), the implementation uses an internal counter. The maximum value of this counter is determined by the postfixSize parameter i.e. the largest value that can be represented in base 36. If the counter exceeds this value, an IllegalStateException is thrown.

Note: The uniqueness of the generated ids cannot be guaranteed if the system performs time shifts of more than a second, that affect the running processes.

Version:

$Id: TimeBasedAlphanumericIdentifierGenerator.java 480488 2006-11-29 08:57:26Z bayard $

Author:

Commons-Id team

See Also:

Serialized Form

Field Summary

Fields inherited from class org.apache.commons.id.AbstractStringIdentifierGenerator

ALPHA_NUMERIC_CHARSET_SIZE, DEFAULT_ALPHANUMERIC_IDENTIFIER_SIZE, MAX_INT_ALPHANUMERIC_VALUE_LENGTH, MAX_INT_NUMERIC_VALUE_LENGTH, MAX_LONG_ALPHANUMERIC_VALUE_LENGTH, MAX_LONG_NUMERIC_VALUE_LENGTH

Fields inherited from interface org.apache.commons.id.StringIdentifierGenerator

INFINITE_MAX_LENGTH

Constructor Summary

TimeBasedAlphanumericIdentifierGenerator()
Construct a TimeBasedAlphanumericIdentifierGenerator with a default size of the postfix of 3.

TimeBasedAlphanumericIdentifierGenerator(int postfixSize)
Construct a TimeBasedAlphanumericIdentifierGenerator with a defined size of the postfix.

TimeBasedAlphanumericIdentifierGenerator(int postfixSize, long offset)
Construct a TimeBasedAlphanumericIdentifierGenerator with a defined size of the postfix and an offset for the time value.

Method Summary

long	getMillisecondsFromId(java.lang.Object id, long offset) Retrieve the number of milliseconds since 1st Jan 1970 that were the base for the given id.
long	maxLength() Returns the maximum length (number or characters) for an identifier from this sequence.
long	minLength() Returns the minimum length (number of characters) for an identifier from this sequence.
java.lang.String	nextStringIdentifier() Gets the next identifier in the sequence.

Methods inherited from class org.apache.commons.id.AbstractStringIdentifierGenerator

nextIdentifier

Methods inherited from class java.lang.Object

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

Constructor Detail

TimeBasedAlphanumericIdentifierGenerator

public TimeBasedAlphanumericIdentifierGenerator(int postfixSize,
                                                long offset)

Construct a TimeBasedAlphanumericIdentifierGenerator with a defined size of the postfix and an offset for the time value. The offset can be used to manipulate the representation of the time value in the generated id. If a TimeBasedAlphanumericIdentifierGenerator is constructed with an offset of the current number of milliseconds since 1st Jan 1970 the first generated id in the same millisecond will have an id consisting of a sequence of '0' characters.

Parameters:

postfixSize - the size of the postfix

offset - the offset taken into account for the time value

Throws:

java.lang.IllegalArgumentException - if postfixSize is negative or exceeds the maximum size for representing Long.MAX_VALUE in base 36

TimeBasedAlphanumericIdentifierGenerator

public TimeBasedAlphanumericIdentifierGenerator(int postfixSize)

Construct a TimeBasedAlphanumericIdentifierGenerator with a defined size of the postfix.

Parameters:

postfixSize - the size of the postfix defining the maximum number of possible ids generated within the same millisecond (depending on the time resolution of the running system)

Throws:

java.lang.IllegalArgumentException - if postfixSize is negative or exceeds the maximum size for representing Long.MAX_VALUE in base 36

TimeBasedAlphanumericIdentifierGenerator

public TimeBasedAlphanumericIdentifierGenerator()

Construct a TimeBasedAlphanumericIdentifierGenerator with a default size of the postfix of 3.

Method Detail

maxLength

public long maxLength()

Description copied from class: AbstractStringIdentifierGenerator

Returns the maximum length (number or characters) for an identifier from this sequence.

The default implementation returns StringIdentifierGenerator.INFINITE_MAX_LENGTH. Implementations with bounded length identifiers should override this method to return the maximum length of a generated identifier.

Specified by:

maxLength in interface StringIdentifierGenerator

Overrides:

maxLength in class AbstractStringIdentifierGenerator

Returns:

the maximum identifier length, or StringIdentifierGenerator.INFINITE_MAX_LENGTH if there is no upper bound

minLength

public long minLength()

Description copied from class: AbstractStringIdentifierGenerator

Returns the minimum length (number of characters) for an identifier from this sequence.

The default implementation returns 0. Implementations with identifiers having a postive minimum length should override this method to return the maximum length of a generated identifier.

Specified by:

minLength in interface StringIdentifierGenerator

Overrides:

minLength in class AbstractStringIdentifierGenerator

Returns:

the minimum identifier length

nextStringIdentifier

public java.lang.String nextStringIdentifier()

Description copied from interface: StringIdentifierGenerator

Gets the next identifier in the sequence.

Specified by:

nextStringIdentifier in interface StringIdentifierGenerator

Specified by:

nextStringIdentifier in class AbstractStringIdentifierGenerator

Returns:

the next String identifier in sequence

getMillisecondsFromId

public long getMillisecondsFromId(java.lang.Object id,
                                  long offset)

Retrieve the number of milliseconds since 1st Jan 1970 that were the base for the given id.

Parameters:

id - the id to use

offset - the offset used to create the id

Returns:

the number of milliseconds

Throws:

java.lang.IllegalArgumentException - if id is not a valid id from this type of generator