org.josef.jpa

Class SequentialIdGenerator

java.lang.Object

org.josef.jpa.SequentialIdGenerator

public final class SequentialIdGenerator
extends Object

Generator of sequence IDs.
Supports the creation of unique IDs that are numbered sequentially. You can use it for example to generate sequential invoice numbers. Each sequence that you need is identified by a unique name that you specify, hence multiple sequences can be used simultaneously.
This class can be used in the context of a transaction! This guarantees that no holes in the sequences can occur. It can also be used outside a transaction if you want to allow holes in the sequence numbering. This may have the advantage of having less locks in a multi-threaded program!
This class assumes that a properties file exists with the same name as this class. The properties files should have the following keys:

Key	Value
dataSourceName	Name of the non-transaction aware data source
txDataSourceName	Name of the transaction aware data source
tableName	Name of the table used to store sequence IDs
sequenceColumnName	Name of the column that stores the name of the sequence
currentIDColumnName	Name of the column that stores the current value of the sequence

Note: This class only functions correctly in a multi-threaded environment when the underlying database supports the: 'SELECT FOR UPDATE' clause. When the 'SELECT FOR UPDATE' clause is not supported than this class can only be used safely in a single-threaded environment.

Version:

1.0 $Revision: 6488 $

Author:

Kees Schotanus

Method Summary

Modifier and Type	Method and Description
long	fetchNextSequentialID(String sequenceName) Fetches the current sequence id for the supplied sequenceName, increments it and stores it in the database.
long	fetchNextSequentialID(String sequenceName, int numberOfIds) Fetches the current sequence id for the supplied sequenceName, increments it by the supplied numberOfIds and stores it in the database.
static SequentialIdGenerator	getInstance(boolean useTransaction) Simply returns one of two (transaction aware or not) sequential ID generator objects.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static SequentialIdGenerator getInstance(boolean useTransaction)
                                         throws NamingException

Simply returns one of two (transaction aware or not) sequential ID generator objects.
Note: different classloaders may return different instances, even though it's hard to speak of a singleton it really doesn't matter since the database's lock mechanism is used for synchronization.

Parameters:

useTransaction - Supply true to construct a transaction aware generator, otherwise supply false.
Normally you should supply a value of true since this prevents holes in the IDs due to rolled back transactions.
ObjectIdDispenser is an example of a class that specifies false. Using false has the advantage of not locking the sequence during the entire transaction.

Returns:

A single instance of either a transaction aware sequential ID generator or a non transaction aware sequential ID generator, depending on the supplied useTransaction parameter.

Throws:

MissingResourceException - When one of the required resources does not exist.
See the class header for details.

NamingException - When an initial context is not available or when the Transaction capable datasource could not be looked up.

fetchNextSequentialID

public long fetchNextSequentialID(String sequenceName)
                           throws SequentialIdGeneratorException

Fetches the current sequence id for the supplied sequenceName, increments it and stores it in the database.
When the supplied sequenceName does not exist in the database table, it will be inserted into the database sequences table.

Parameters:

sequenceName - Name of the sequence for which the next ID should be fetched.

Returns:

The next ID in sequence.
1 is returned for sequences that previous to a call of this method did not exist.

Throws:

IllegalArgumentException - When the supplied sequenceName is empty.

NullPointerException - When the supplied sequenceName is null.

SequentialIdGeneratorException - When a database related error occurs.

fetchNextSequentialID

public long fetchNextSequentialID(String sequenceName,
                                  int numberOfIds)
                           throws SequentialIdGeneratorException

Fetches the current sequence id for the supplied sequenceName, increments it by the supplied numberOfIds and stores it in the database.
Use this method when you know in advance how many sequential ID's you are going to need. The advantage of reserving more than one ID is that all ID's are reserved in a single transaction, instead of multiple transactions.
When the supplied sequenceName does not exist in the database table, it will be inserted into the database sequences table.

Parameters:

sequenceName - Name of the sequence for which the next ID should be fetched.

numberOfIds - The number of sequential ID's to reserve.

Returns:

The next ID in sequence.
1 is returned for sequences that previous to a call of this method did not exist.

Throws:

IllegalArgumentException - When the supplied sequenceName is empty or when numberOfIds is less than 1.

NullPointerException - When the supplied sequenceName is null.

SequentialIdGeneratorException - When a database related error occurs.