Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> apache >> torque >> [ oid overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

org.apache.torque.oid
Class IDBroker  

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

All Implemented Interfaces:

IdGenerator, java.lang.Runnable

---

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,v 1.27.2.4 2004/08/26 16:49:33 henning Exp $

---

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
private  org.apache.commons.configuration.Configuration	configuration           the configuration
private static java.lang.String	DB_IDBROKER_CLEVERQUANTITY           property name
private static java.lang.String	DB_IDBROKER_PREFETCH           property name
private static java.lang.String	DB_IDBROKER_USENEWCONNECTION           property name
private static int	DEFAULT_SIZE           The default size of the per-table meta data Hashtable objects.
private  java.lang.Thread	houseKeeperThread           The houseKeeperThread thread
static java.lang.String	ID_TABLE           Name of the ID_TABLE = ID_TABLE
private  java.util.Hashtable	ids           The cached IDs for each table.
private  java.util.Hashtable	lastQueryTime           The last time this IDBroker queried the database for ids.
private  org.apache.commons.logging.Log	log           the log
static java.lang.String	NEXT_ID           Fully qualified Next_ID column name
private static java.math.BigDecimal	ONE           The value of ONE!
static java.lang.String	QUANTITY           Fully qualified Quantity column name
private  java.util.Hashtable	quantityStore           The quantity of ids to grab for each table.
private static float	SAFETY_MARGIN           The safety Margin
private static int	SLEEP_PERIOD           Amount of time for the thread to sleep
static java.lang.String	TABLE_ID           Fully qualified ID column name
static java.lang.String	TABLE_NAME           Fully qualified Table_Name column name
private  org.apache.torque.map.TableMap	tableMap           The TableMap referencing the ID_TABLE for this IDBroker.
private  boolean	transactionsSupported           Are transactions supported?

 

Constructor Summary

IDBroker(org.apache.torque.map.TableMap tMap)           Creates an IDBroker for the ID table.

 

Method Summary
private  void	checkTiming(java.lang.String tableName)           Check the frequency of retrieving new ids from the database.
boolean	exists(java.lang.String tableName)           Describe exists method here.
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.
private  java.math.BigDecimal	getQuantity(java.lang.String tableName, java.sql.Connection connection)           This method allows you to get the number of ids that are to be cached in memory.
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.
private  java.math.BigDecimal[]	selectRow(java.sql.Connection con, java.lang.String tableName)           Helper method to select a row in the ID_TABLE.
void	setConfiguration(org.apache.commons.configuration.Configuration configuration)           Set the configuration
void	stop()           Shuts down the IDBroker thread.
private  void	storeIDs(java.lang.String tableName, boolean adjustQuantity, java.sql.Connection connection)           Grabs more ids from the id_table and stores it in the ids Hashtable.
private  void	updateNextId(java.sql.Connection con, java.lang.String tableName, java.lang.String id)           Helper method to update a row in the ID_TABLE.
private  void	updateQuantity(java.sql.Connection con, java.lang.String tableName, java.math.BigDecimal quantity)           Helper method to update a row in the ID_TABLE.

 

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

---

tableMap

private org.apache.torque.map.TableMap tableMap

The TableMap referencing the ID_TABLE for this IDBroker.

---

DEFAULT_SIZE

private static final int DEFAULT_SIZE

The default size of the per-table meta data Hashtable objects.

See Also:

Constant Field Values

---

ids

private java.util.Hashtable ids

The cached IDs for each table. Key: String table name. Value: List of Integer IDs.

---

quantityStore

private java.util.Hashtable quantityStore

The quantity of ids to grab for each table. Key: String table name. Value: Integer quantity.

---

lastQueryTime

private java.util.Hashtable lastQueryTime

The last time this IDBroker queried the database for ids. Key: String table name. Value: Date of last id request.

---

SLEEP_PERIOD

private static final int SLEEP_PERIOD

Amount of time for the thread to sleep

See Also:

Constant Field Values

---

SAFETY_MARGIN

private static final float SAFETY_MARGIN

The safety Margin

See Also:

Constant Field Values

---

houseKeeperThread

private java.lang.Thread houseKeeperThread

The houseKeeperThread thread

---

transactionsSupported

private boolean transactionsSupported

Are transactions supported?

---

ONE

private static final java.math.BigDecimal ONE

The value of ONE!

---

configuration

private org.apache.commons.configuration.Configuration configuration

the configuration

---

DB_IDBROKER_CLEVERQUANTITY

private static final java.lang.String DB_IDBROKER_CLEVERQUANTITY

property name

See Also:

Constant Field Values

---

DB_IDBROKER_PREFETCH

private static final java.lang.String DB_IDBROKER_PREFETCH

property name

See Also:

Constant Field Values

---

DB_IDBROKER_USENEWCONNECTION

private static final java.lang.String DB_IDBROKER_USENEWCONNECTION

property name

See Also:

Constant Field Values

---

log

private org.apache.commons.logging.Log log

the log

Constructor Detail

IDBroker

public IDBroker(org.apache.torque.map.TableMap tMap)

Creates an IDBroker for the ID table.

Method Detail

setConfiguration

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

Set 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

---

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

---

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

---

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

---

isPriorToInsert

public boolean isPriorToInsert()

A flag to determine the timing of the id generation *

Specified by:

isPriorToInsert in interface IdGenerator

---

isPostInsert

public boolean isPostInsert()

A flag to determine the timing of the id generation

Specified by:

isPostInsert in interface IdGenerator

---

isConnectionRequired

public boolean isConnectionRequired()

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

Specified by:

isConnectionRequired in interface IdGenerator

---

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.

---

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

---

exists

public boolean exists(java.lang.String tableName)
               throws org.apache.torque.TorqueException,
                      java.lang.Exception

Describe exists method here.

---

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.

---

checkTiming

private void checkTiming(java.lang.String tableName)

Check the frequency of retrieving new ids from the database. If the frequency is high then we increase the amount (i.e. quantity column) of ids retrieved on each access. Tries to alter number of keys grabbed so that IDBroker retrieves a new set of ID's prior to their being needed.

---

storeIDs

private void storeIDs(java.lang.String tableName,
                      boolean adjustQuantity,
                      java.sql.Connection connection)
               throws java.lang.Exception

Grabs more ids from the id_table and stores it in the ids Hashtable. If adjustQuantity is set to true the amount of id's retrieved for each call to storeIDs will be adjusted.

---

getQuantity

private java.math.BigDecimal getQuantity(java.lang.String tableName,
                                         java.sql.Connection connection)

This method allows you to get the number of ids that are to be cached in memory. This is either stored in quantityStore or read from the db. (ie the value in ID_TABLE.QUANTITY). Though this method returns a BigDecimal for the quantity, it is unlikey the system could withstand whatever conditions would lead to really needing a large quantity, it is retrieved as a BigDecimal only because it is going to be added to another BigDecimal.

---

selectRow

private java.math.BigDecimal[] selectRow(java.sql.Connection con,
                                         java.lang.String tableName)
                                  throws java.lang.Exception

Helper method to select a row in the ID_TABLE.

---

updateNextId

private void updateNextId(java.sql.Connection con,
                          java.lang.String tableName,
                          java.lang.String id)
                   throws java.lang.Exception

Helper method to update a row in the ID_TABLE.

---

updateQuantity

private void updateQuantity(java.sql.Connection con,
                            java.lang.String tableName,
                            java.math.BigDecimal quantity)
                     throws java.lang.Exception

Helper method to update a row in the ID_TABLE.

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> apache >> torque >> [ oid overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---