Unique ID Module

Who needs it and why

All applications that require unique, but not necessarily sequential data identifiers, e.g as database-table key fields, unique counter values or transaction confirmation numbers can leverage this service. The Unique ID Service provides a solution that can be easily integrated into any Java application using JDBC and a JDBC-compliant database.

Dependencies

The Unique ID Service depends on the SQL Service and the Connection Service.

Solution

The default implementation of this service generates unique ids by reserving a range of values from a jdbc compliant database. On startup, each instance of this service queries the table and blocks a range of ids. All subsequent calls to this instance, returns value from this blocked range. The default implementation is multi instance safe. Meaning that there can be more than one instances of the unique id service, generating ids for the same sequence name and they will continue to generate unique ids. Once an instance uses all the blocked ids, it queries the database for a fresh block. This approach helps in reducing the network traffic and improving performance.

Component Configuration

Properties which make up the configuration for unique id component are:

Property	Data Type / Value	Description
Configuration Interface	org.sape.carbon.services.uniqueid. UniqueIDServiceConfiguration	Defines the configuration Interface for the service
Functional Interface	org.sape.carbon.services.uniqueid.UniqueIDService	Functional Interface defines the programming contract, In this case, we have the  getNextID that returns the next unique ID
Functional Implementation	org.sape.carbon.services.uniqueid. DefaultUniqueIDServiceImpl	Default implementation for this service
StatementFactory	Required: reference to the statement factory	Reference to the statement factory which contains all the statements executed by the unique id service. e.g. ref:///uniqueid/UIDStatementFactoryForOracle
ConnectionFactory	Required: reference to the connection factory	Though the sql statement factory also mentions a connection factory, it is necessary to configure a connection factory for the unique id service. This is necessary because the unique id service maintains all the transaction isolation. e.g. ref:///sql/connection/StandaloneConnectionFactory
InitialBlockStart	optional long value defaults to 0 if not specified	InitialBlockStart is used to define the starting value of the ID in the case that the ID is automatically created by the service
IDName	Required: String parameter	IDName identifies the UniqueID in the database. Each instance of this service is associated with one unique id sequence name
BlockSize	Required: long parameter	BlockSize is the number of IDs that is reserved upon each call to the database.  This should be optimized to minimize hits to the database
AutoCreate	Optional: boolean parameter defaults to true	AutoCreate specifies whether or not the ID should be created if it does not exist.  If this is true, the ID will be automatically created.
RetrieveStatementName	Optional: String defaults to RetrieveUniqueID	Name of a PreparedStatement configured within the StatementFactory used to get the starting value of the next available block of IDs.
UpdateStatementName	Optional: String defaults to UpdateUniqueID	Name of a PreparedStatement configured within the StatementFactory used to update the starting value of the next available block of IDs
CreateStatementName	Optional: String defaults to CreateUniqueID	Name of a PreparedStatement configured within the StatementFactory used to create a new ID

A sample configuration for the Unique ID Service is provided below.

<Configuration ConfigurationInterface="org.sape.carbon.services.uniqueid.UniqueIDServiceConfiguration">
    <!-- Component Interface/Implementation Configuration -->
    <FunctionalInterface>org.sape.carbon.services.uniqueid.UniqueIDService</FunctionalInterface>
    <FunctionalImplementationClass>org.sape.carbon.services.uniqueid.DefaultUniqueIDServiceImpl</FunctionalImplementationClass>
    <!-- Component Implementation specific properties -->
    <ConnectionFactory>ref:///sql/connection/test/StandaloneConnectionFactory</ConnectionFactory>
    <InitialBlockStart>0</InitialBlockStart>
    <IDName>myPrimaryKey</IDName>
    <BlockSize>200</BlockSize>
    <AutoCreate>true</AutoCreate>
    <!-- Statement Factory to use -->
    <StatementFactory>ref:///uniqueid/test/UIDStatementFactoryForOracle</StatementFactory>
</Configuration>

Code Example

    /**
     * Example code to show how to use the uniqueid service
     */

    public static final String COMPONENT_CONFIG = "/uniqueid/test/testuniqueid";

    UniqueIDService uniqueIDService =
              (UniqueIDService) Lookup.getInstance().fetchComponent(COMPONENT_CONFIG);

    try {
        long nextId = uniqueIDService.getNextID();
        System.out.println("Unique ID obtained: " + nextId);
    } catch (UniqueIDServiceException uidse) {
        fail( "Caught UniqueIDServiceException: " + uidse
                + ExceptionUtility.captureStackTrace(uidse));
    }

Best and Worst Practices

This service does not produce sequential IDs and should not be used for tracking the order of entity creation. This type of functionality is better-fulfilled by on insert sequences. As of now, this may require the use of an additional key; however, JDBC 3.0 promises to provide a mechanism to access such database sequences.