The Carbon Java Framework  

Unique ID Module

Unique ID Service Usage

Printer Friendly Version

Author: Vivekanand Kirubanandan (vkirub at
Version: $Revision: 1.3 $($Author: araman $ / $Date: 2003/10/20 11:44:58 $)
Created: July 2002


The Unique ID Service solves the problem of generating data-representation- independent, unique IDs that may be used to identify and track data throughout a system. Such IDs can, for example, serve as key-values for database tables before the data is inserted into the table. Using generated or surrogate keys for business data allows changes to the underlying data that do not effect the nature or identity of the data so that it can continue to be tracked for the duration of its lifetime.

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.


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


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.


The Unique ID Service provides a simple API to retrieve unique IDs, namely, the method getNextValue(), provided by the service's functional interface.

Component Configuration

Properties which make up the configuration for unique id component are:
Property Data Type / Value Description
Configuration Interface
Defines the configuration Interface for the service
Functional Interface Functional Interface defines the programming contract, In this case, we have the  getNextID that returns the next unique ID
Functional Implementation
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="">
    <!-- Component Interface/Implementation Configuration -->
    <!-- Component Implementation specific properties -->
    <!-- Statement Factory to use -->

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.

Copyright © 2001-2003, Sapient Corporation