org.apache.torque.oid
Class IDBroker

java.lang.Object
  org.apache.torque.oid.IDBroker

All Implemented Interfaces:

java.lang.Runnable, IdGenerator

public class IDBroker
extends java.lang.Object
implements java.lang.Runnable, IdGenerator

This method of ID generation is used to ensure that code is more database independent. For example, MySQL has an auto-increment feature while Oracle uses sequences. It caches several ids to avoid needing a Connection for every request. This class uses the table ID_TABLE defined in conf/master/id-table-schema.xml. The columns in ID_TABLE are used as follows:
ID_TABLE_ID - The PK for this row (any unique int).
TABLE_NAME - The name of the table you want ids for.
NEXT_ID - The next id returned by IDBroker when it queries the database (not when it returns an id from memory).
QUANTITY - The number of ids that IDBroker will cache in memory.

Use this class like this:

 int id = dbMap.getIDBroker().getNextIdAsInt(null, "TABLE_NAME");
  - or -
 BigDecimal[] ids = ((IDBroker)dbMap.getIDBroker())
     .getNextIds("TABLE_NAME", numOfIdsToReturn);
 

NOTE: When the ID_TABLE must be updated we must ensure that IDBroker objects running in different JVMs do not overwrite each other. This is accomplished using using the transactional support occuring in some databases. Using this class with a database that does not support transactions should be limited to a single JVM.

Version:

$Id: IDBroker.java 552333 2007-07-01 16:24:19Z tv $

Author:

Frank Y. Kim, John D. McNally, Henning P. Schmiedehausen

Field Summary

static java.lang.String	COL_NEXT_ID Next_ID column name
static java.lang.String	COL_QUANTITY Quantity column name
static java.lang.String	COL_TABLE_ID ID column name
static java.lang.String	COL_TABLE_NAME Table_Name column name
static java.lang.String	ID_TABLE Name of the ID_TABLE = ID_TABLE
static java.lang.String	NEXT_ID Fully qualified Next_ID column name
static java.lang.String	QUANTITY Fully qualified Quantity column name
static java.lang.String	TABLE_ID Fully qualified ID column name
static java.lang.String	TABLE_NAME Fully qualified Table_Name column name

Constructor Summary

IDBroker(Database database)
constructs an IdBroker for the given Database.

IDBroker(TableMap tMap)
Deprecated. Use IDBroker(DatabaseInfo) instead. Will be removed in a future version of Torque.

Method Summary

boolean	exists(java.lang.String tableName)
java.math.BigDecimal	getIdAsBigDecimal(java.sql.Connection connection, java.lang.Object tableName) Returns an id as a BigDecimal.
int	getIdAsInt(java.sql.Connection connection, java.lang.Object tableName) Returns an id as a primitive int.
long	getIdAsLong(java.sql.Connection connection, java.lang.Object tableName) Returns an id as a primitive long.
java.lang.String	getIdAsString(java.sql.Connection connection, java.lang.Object tableName) Returns an id as a String.
java.math.BigDecimal[]	getNextIds(java.lang.String tableName, int numOfIdsToReturn) This method returns x number of ids for the given table.
java.math.BigDecimal[]	getNextIds(java.lang.String tableName, int numOfIdsToReturn, java.sql.Connection connection) This method returns x number of ids for the given table.
boolean	isConnectionRequired() A flag to determine whether a Connection is required to generate an id.
boolean	isPostInsert() A flag to determine the timing of the id generation
boolean	isPriorToInsert() A flag to determine the timing of the id generation *
void	run() A background thread that tries to ensure that when someone asks for ids, that there are already some loaded and that the database is not accessed.
void	setConfiguration(org.apache.commons.configuration.Configuration configuration) Set the configuration
void	stop() Shuts down the IDBroker thread.

Methods inherited from class java.lang.Object

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

Field Detail

ID_TABLE

public static final java.lang.String ID_TABLE

Name of the ID_TABLE = ID_TABLE

See Also:

Constant Field Values

COL_TABLE_NAME

public static final java.lang.String COL_TABLE_NAME

Table_Name column name

See Also:

Constant Field Values

TABLE_NAME

public static final java.lang.String TABLE_NAME

Fully qualified Table_Name column name

See Also:

Constant Field Values

COL_TABLE_ID

public static final java.lang.String COL_TABLE_ID

ID column name

See Also:

Constant Field Values

TABLE_ID

public static final java.lang.String TABLE_ID

Fully qualified ID column name

See Also:

Constant Field Values

COL_NEXT_ID

public static final java.lang.String COL_NEXT_ID

Next_ID column name

See Also:

Constant Field Values

NEXT_ID

public static final java.lang.String NEXT_ID

Fully qualified Next_ID column name

See Also:

Constant Field Values

COL_QUANTITY

public static final java.lang.String COL_QUANTITY

Quantity column name

See Also:

Constant Field Values

QUANTITY

public static final java.lang.String QUANTITY

Fully qualified Quantity column name

See Also:

Constant Field Values

Constructor Detail

IDBroker

public IDBroker(Database database)

constructs an IdBroker for the given Database.

Parameters:

database - the database where this IdBroker is running in.

IDBroker

public IDBroker(TableMap tMap)

Deprecated. Use IDBroker(DatabaseInfo) instead. Will be removed in a future version of Torque.

Creates an IDBroker for the ID table.

Parameters:

tMap - A TableMap.

Method Detail

setConfiguration

public void setConfiguration(org.apache.commons.configuration.Configuration configuration)

Set the configuration

Parameters:

configuration - the configuration

getIdAsInt

public int getIdAsInt(java.sql.Connection connection,
                      java.lang.Object tableName)
               throws java.lang.Exception

Returns an id as a primitive int. Note this method does not require a Connection, it just implements the KeyGenerator interface. if a Connection is needed one will be requested. To force the use of the passed in connection set the configuration property torque.idbroker.usenewconnection = false

Specified by:

getIdAsInt in interface IdGenerator

Parameters:

connection - A Connection.

tableName - an Object that contains additional info.

Returns:

An int with the value for the id.

Throws:

java.lang.Exception - Database error.

getIdAsLong

public long getIdAsLong(java.sql.Connection connection,
                        java.lang.Object tableName)
                 throws java.lang.Exception

Returns an id as a primitive long. Note this method does not require a Connection, it just implements the KeyGenerator interface. if a Connection is needed one will be requested. To force the use of the passed in connection set the configuration property torque.idbroker.usenewconnection = false

Specified by:

getIdAsLong in interface IdGenerator

Parameters:

connection - A Connection.

tableName - a String that identifies a table.

Returns:

A long with the value for the id.

Throws:

java.lang.Exception - Database error.

getIdAsBigDecimal

public java.math.BigDecimal getIdAsBigDecimal(java.sql.Connection connection,
                                              java.lang.Object tableName)
                                       throws java.lang.Exception

Returns an id as a BigDecimal. Note this method does not require a Connection, it just implements the KeyGenerator interface. if a Connection is needed one will be requested. To force the use of the passed in connection set the configuration property torque.idbroker.usenewconnection = false

Specified by:

getIdAsBigDecimal in interface IdGenerator

Parameters:

connection - A Connection.

tableName - a String that identifies a table..

Returns:

A BigDecimal id.

Throws:

java.lang.Exception - Database error.

getIdAsString

public java.lang.String getIdAsString(java.sql.Connection connection,
                                      java.lang.Object tableName)
                               throws java.lang.Exception

Returns an id as a String. Note this method does not require a Connection, it just implements the KeyGenerator interface. if a Connection is needed one will be requested. To force the use of the passed in connection set the configuration property torque.idbroker.usenewconnection = false

Specified by:

getIdAsString in interface IdGenerator

Parameters:

connection - A Connection should be null.

tableName - a String that identifies a table.

Returns:

A String id

Throws:

java.lang.Exception - Database error.

isPriorToInsert

public boolean isPriorToInsert()

A flag to determine the timing of the id generation *

Specified by:

isPriorToInsert in interface IdGenerator

Returns:

a boolean value

isPostInsert

public boolean isPostInsert()

A flag to determine the timing of the id generation

Specified by:

isPostInsert in interface IdGenerator

Returns:

a boolean value

isConnectionRequired

public boolean isConnectionRequired()

A flag to determine whether a Connection is required to generate an id.

Specified by:

isConnectionRequired in interface IdGenerator

Returns:

a boolean value

getNextIds

public java.math.BigDecimal[] getNextIds(java.lang.String tableName,
                                         int numOfIdsToReturn)
                                  throws java.lang.Exception

This method returns x number of ids for the given table.

Parameters:

tableName - The name of the table for which we want an id.

numOfIdsToReturn - The desired number of ids.

Returns:

A BigDecimal.

Throws:

java.lang.Exception - Database error.

getNextIds

public java.math.BigDecimal[] getNextIds(java.lang.String tableName,
                                         int numOfIdsToReturn,
                                         java.sql.Connection connection)
                                  throws java.lang.Exception

This method returns x number of ids for the given table. Note this method does not require a Connection. If a Connection is needed one will be requested. To force the use of the passed in connection set the configuration property torque.idbroker.usenewconnection = false

Parameters:

tableName - The name of the table for which we want an id.

numOfIdsToReturn - The desired number of ids.

connection - A Connection.

Returns:

A BigDecimal.

Throws:

java.lang.Exception - Database error.

exists

public boolean exists(java.lang.String tableName)
               throws java.lang.Exception

Parameters:

tableName - a String value that is used to identify the row

Returns:

a boolean value

Throws:

TorqueException - if a Torque error occurs.

java.lang.Exception - if another error occurs.

run

public void run()

A background thread that tries to ensure that when someone asks for ids, that there are already some loaded and that the database is not accessed.

Specified by:

run in interface java.lang.Runnable

stop

public void stop()

Shuts down the IDBroker thread. Calling this method stops the thread that was started for this instance of the IDBroker. This method should be called during MapBroker Service shutdown.