Package org.apache.torque.oid
Class IDBroker
- java.lang.Object
-
- org.apache.torque.oid.IDBroker
-
- All Implemented Interfaces:
Runnable
,IdGenerator
public class IDBroker extends Object implements 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 1870542 2019-11-28 09:32:40Z tv $
- Author:
- Frank Y. Kim, John D. McNally, Henning P. Schmiedehausen
-
-
Field Summary
Fields Modifier and Type Field Description static String
COL_NEXT_ID
Next_ID column namestatic String
COL_QUANTITY
Quantity column namestatic String
COL_TABLE_ID
ID column namestatic String
COL_TABLE_NAME
Table_Name column namestatic String
ID_TABLE
Name of the ID_TABLE = ID_TABLEstatic String
NEXT_ID
Fully qualified Next_ID column namestatic String
QUANTITY
Fully qualified Quantity column namestatic String
TABLE_ID
Fully qualified ID column namestatic String
TABLE_NAME
Fully qualified Table_Name column name
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
exists(String tableName)
BigDecimal
getIdAsBigDecimal(Connection connection, Object tableName)
Returns an id as a BigDecimal.int
getIdAsInt(Connection connection, Object tableName)
Returns an id as a primitive int.long
getIdAsLong(Connection connection, Object tableName)
Returns an id as a primitive long.String
getIdAsString(Connection connection, Object tableName)
Returns an id as a String.BigDecimal[]
getNextIds(String tableName, int numOfIdsToReturn)
This method returns x number of ids for the given table.BigDecimal[]
getNextIds(String tableName, int numOfIdsToReturn, Connection connection)
This method returns x number of ids for the given table.protected BigDecimal
getQuantity(String tableName)
Returns the quantity value for a table.boolean
isConnectionRequired()
A flag to determine whether a Connection is required to generate an id.boolean
isGetGeneratedKeysSupported()
A flag to determine whether Statement#getGeneratedKeys() should be used.boolean
isPostInsert()
A flag to determine the timing of the id generationboolean
isPriorToInsert()
A flag to determine the timing of the id generation *boolean
isThreadRunning()
Returns whether the idbroker thread is running.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.configuration2.Configuration configuration)
Set the configurationvoid
start()
Starts the idBroker.void
stop()
Shuts down the IDBroker thread.protected void
updateQuantity(Connection con, String tableName, BigDecimal quantity)
Helper method to update a row in the ID_TABLE.
-
-
-
Field Detail
-
ID_TABLE
public static final String ID_TABLE
Name of the ID_TABLE = ID_TABLE- See Also:
- Constant Field Values
-
COL_TABLE_NAME
public static final String COL_TABLE_NAME
Table_Name column name- See Also:
- Constant Field Values
-
TABLE_NAME
public static final String TABLE_NAME
Fully qualified Table_Name column name- See Also:
- Constant Field Values
-
COL_TABLE_ID
public static final String COL_TABLE_ID
ID column name- See Also:
- Constant Field Values
-
TABLE_ID
public static final String TABLE_ID
Fully qualified ID column name- See Also:
- Constant Field Values
-
COL_NEXT_ID
public static final String COL_NEXT_ID
Next_ID column name- See Also:
- Constant Field Values
-
NEXT_ID
public static final String NEXT_ID
Fully qualified Next_ID column name- See Also:
- Constant Field Values
-
COL_QUANTITY
public static final String COL_QUANTITY
Quantity column name- See Also:
- Constant Field Values
-
QUANTITY
public static final 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.
-
-
Method Detail
-
start
public void start()
Starts the idBroker.
-
setConfiguration
public void setConfiguration(org.apache.commons.configuration2.Configuration configuration)
Set the configuration- Parameters:
configuration
- the configuration
-
getIdAsInt
public int getIdAsInt(Connection connection, Object tableName) throws TorqueException
Description copied from interface:IdGenerator
Returns an id as a primitive int. If you use numeric identifiers, it's suggested thatIdGenerator.getIdAsLong(Connection, Object)
be used instead (due to the limited range of this method).- Specified by:
getIdAsInt
in interfaceIdGenerator
- Parameters:
connection
- A Connection.tableName
- an Object that contains additional info.- Returns:
- An int with the value for the id.
- Throws:
TorqueException
- Database error.- See Also:
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
-
getIdAsLong
public long getIdAsLong(Connection connection, Object tableName) throws TorqueException
Description copied from interface:IdGenerator
Returns an id as a primitive long.- Specified by:
getIdAsLong
in interfaceIdGenerator
- Parameters:
connection
- A Connection.tableName
- a String that identifies a table.- Returns:
- A long with the value for the id.
- Throws:
TorqueException
- Database error.- See Also:
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
-
getIdAsBigDecimal
public BigDecimal getIdAsBigDecimal(Connection connection, Object tableName) throws TorqueException
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 interfaceIdGenerator
- Parameters:
connection
- A Connection.tableName
- a String that identifies a table..- Returns:
- A BigDecimal id.
- Throws:
TorqueException
- Database error.
-
getIdAsString
public String getIdAsString(Connection connection, Object tableName) throws TorqueException
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 interfaceIdGenerator
- Parameters:
connection
- A Connection should be null.tableName
- a String that identifies a table.- Returns:
- A String id
- Throws:
TorqueException
- Database error.
-
isPriorToInsert
public boolean isPriorToInsert()
A flag to determine the timing of the id generation *- Specified by:
isPriorToInsert
in interfaceIdGenerator
- Returns:
- a
boolean
value
-
isPostInsert
public boolean isPostInsert()
A flag to determine the timing of the id generation- Specified by:
isPostInsert
in interfaceIdGenerator
- 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 interfaceIdGenerator
- Returns:
- a
boolean
value
-
isGetGeneratedKeysSupported
public boolean isGetGeneratedKeysSupported()
A flag to determine whether Statement#getGeneratedKeys() should be used.- Specified by:
isGetGeneratedKeysSupported
in interfaceIdGenerator
- Returns:
- a
boolean
value
-
isThreadRunning
public boolean isThreadRunning()
Returns whether the idbroker thread is running.- Returns:
- true if the thread is running, false otherwise.
-
getNextIds
public BigDecimal[] getNextIds(String tableName, int numOfIdsToReturn) throws 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:
Exception
- Database error.
-
getNextIds
public BigDecimal[] getNextIds(String tableName, int numOfIdsToReturn, Connection connection) throws TorqueException
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:
TorqueException
- on a database error.
-
exists
public boolean exists(String tableName) throws Exception
- Parameters:
tableName
- aString
value that is used to identify the row- Returns:
- a
boolean
value - Throws:
TorqueException
- if a Torque error occurs.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.
-
stop
public void stop()
Shuts down the IDBroker thread. Calling this method stops the thread that was started for this instance of the IDBroker.
-
updateQuantity
protected void updateQuantity(Connection con, String tableName, BigDecimal quantity) throws TorqueException
Helper method to update a row in the ID_TABLE.- Parameters:
con
- A Connection.tableName
- The properly escaped name of the table to identify the row.quantity
- An int with the value of the quantity.- Throws:
TorqueException
- Database error.
-
getQuantity
protected BigDecimal getQuantity(String tableName)
Returns the quantity value for a table.- Parameters:
tableName
- the name of the table.- Returns:
- the quantity value for the table, or null if the table is (still) unknown.
-
-