org.apache.commons.id.serial
Class TimeBasedAlphanumericIdentifierGenerator

java.lang.Object
  extended by org.apache.commons.id.AbstractStringIdentifierGenerator
      extended by 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


Copyright 2003-2008 The Apache Software Foundation. All Rights Reserved.