biz.chitec.quarterback.util
Class Sequencer

java.lang.Object
  biz.chitec.quarterback.util.Sequencer

public final class Sequencer

extends java.lang.Object

Class with methods to handle unique numbers tables using a database that doesn't support this on its own. This class consists only of static methods that operate on a JDBC-Statement to access a table "sequencertable". In MySQL, that table would have to be created like this:

create table sequencertable(
  name char(40) not null default "",
  value int not null default 0,
  accessors int not null default 0,
  unique(name)
);

The class itself implements all element functions that should be implemented to operate with the unique number generator.

Note that this class cannot be instantiated.

Version:

$Id: df100e9016497f81b082e5daaab305ceec31a5d1 $

Author:

Dirk Hillbrecht 1997-1999, chitec/Dirk Hillbrecht 2000,2002, cantamen/Dirk Hillbrecht 2004 Distributed under the terms of the GNU LGPL.

Field Summary

private static java.util.Random	rndgen
static java.lang.String	TABLENAME

Constructor Summary

private

Sequencer()

Method Summary

static int	checkIntegrity(java.sql.Statement stmt) Checks and restores the integrity of the unique number generators' table.
static boolean	create(java.sql.Statement stmt, java.lang.String name) Create a new unique number generator with the given name.
static void	drop(java.sql.Statement stmt, java.lang.String name) Drops the unique number generator with the given name.
static boolean	exists(java.sql.Statement stmt, java.lang.String name) Checks whether there is a unique number generator with the given name.
static int	getNext(java.sql.Statement stmt, java.lang.String name) Returns next unique number of the given generator.
static int	getNext(java.sql.Statement stmt, java.lang.String name, java.lang.String tablename, java.lang.String column, java.lang.String addwhere) Returns the next unique number from generator and guarantees that it does not already exist in tablenames column.
static int	getThis(java.sql.Statement stmt, java.lang.String name) Returns the last returned number of the generator.
private static void	lock(java.sql.Statement stmt, java.lang.String name) Locking method.
static void	store(java.sql.Statement stmt, java.lang.String name, int value) Stores a new value in the unique number generator.
static boolean	storeIfGreater(java.sql.Statement stmt, java.lang.String name, int value) Stores a new value in the generator, but only if it is greater than the currently stored number.
private static void	unlock(java.sql.Statement stmt, java.lang.String name) Releases monitor for generator.

Methods inherited from class java.lang.Object

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

Field Detail

TABLENAME

public static final java.lang.String TABLENAME

See Also:

Constant Field Values

rndgen

private static final java.util.Random rndgen

Constructor Detail

Sequencer

private Sequencer()

Method Detail

create

public static final boolean create(java.sql.Statement stmt,
                                   java.lang.String name)
                            throws java.sql.SQLException

Create a new unique number generator with the given name. If there is already a unique number generator with the given name, nothing happens.

Returns:

true if number generator has been created, false if it already existed

Throws:

java.sql.SQLException

exists

public static final boolean exists(java.sql.Statement stmt,
                                   java.lang.String name)
                            throws java.sql.SQLException

Checks whether there is a unique number generator with the given name.

Throws:

java.sql.SQLException

drop

public static final void drop(java.sql.Statement stmt,
                              java.lang.String name)
                       throws java.sql.SQLException

Drops the unique number generator with the given name. If is doesn't exist, nothing happens.

Throws:

java.sql.SQLException

checkIntegrity

public static final int checkIntegrity(java.sql.Statement stmt)
                                throws java.sql.SQLException

Checks and restores the integrity of the unique number generators' table. Returns the number of generators whose table entries had to be repaired.

Throws:

java.sql.SQLException

getNext

public static final int getNext(java.sql.Statement stmt,
                                java.lang.String name)
                         throws java.sql.SQLException

Returns next unique number of the given generator. This method is absolutely thread safe. Any number of threads may call it concurrently. It is always guaranteed that each thread will get different number.

Throws:

java.sql.SQLException

getNext

public static final int getNext(java.sql.Statement stmt,
                                java.lang.String name,
                                java.lang.String tablename,
                                java.lang.String column,
                                java.lang.String addwhere)
                         throws java.sql.SQLException

Returns the next unique number from generator and guarantees that it does not already exist in tablenames column. Additionally to being unique within the generator, this method checks also a uniqueness of the value among the already inserted values in a certain table column. This can be of great usefulness if it is possible to feed the table column not only through the generator, but also independently.

The method is also completely threadsafe when it comes to the generator. To close all loopholes for other threads which add the number on their own, there should also be an additional locking of the table in question for insertions in general. Otherwise, the external insertion thread could insert an entry with a number which just has been identified as "free" by this method - before it sets the number itself. This method does itself not impose any locks on the other table.

The method's efficiency decreases if there are huge blocks of contiguous numbers which have been assigned from outside the generator.

Parameters:

stmt - The database statement

name - Name of the sequencer to take the unique number from

tablename - Table in which the number is inserted

column - Row in which the number can be found later

addwhere - Additional constraints for the uniqueness test. Null if not applicable.

Returns:

Unique number

Throws:

java.sql.SQLException

getThis

public static final int getThis(java.sql.Statement stmt,
                                java.lang.String name)
                         throws java.sql.SQLException

Returns the last returned number of the generator. In case of concurrent generator changing accesses the result of this method cannot be predicted.

Throws:

java.sql.SQLException

store

public static final void store(java.sql.Statement stmt,
                               java.lang.String name,
                               int value)
                        throws java.sql.SQLException

Stores a new value in the unique number generator. The next returned number will be the successor of the stored number.

Throws:

java.sql.SQLException

storeIfGreater

public static final boolean storeIfGreater(java.sql.Statement stmt,
                                           java.lang.String name,
                                           int value)
                                    throws java.sql.SQLException

Stores a new value in the generator, but only if it is greater than the currently stored number.

Throws:

java.sql.SQLException

lock

private static final void lock(java.sql.Statement stmt,
                               java.lang.String name)
                        throws java.sql.SQLException

Locking method. Obtains monitor for the given generator. Returns only when monitor has been obtained.

Throws:

java.sql.SQLException

unlock

private static final void unlock(java.sql.Statement stmt,
                                 java.lang.String name)
                          throws java.sql.SQLException

Releases monitor for generator.

Throws:

java.sql.SQLException