org.apache.turbine.util.db
Class IDBroker

java.lang.Object
  |
  +--org.apache.turbine.util.db.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.3 2001/10/18 22:00:31 dlr Exp $
Author:
Frank Y. Kim, John D. McNally

Field Summary
private static int DEFAULT_SIZE
          The default size of the per-table meta data Hashtable objects.
private  java.lang.Thread houseKeeperThread
          The houseKeeperThread thread
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.
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 safetyMargin
          The safety Margin
private static int sleepPeriod
          Amount of time for the thread to sleep
static java.lang.String TABLE_NAME
          Fully qualified Table_Name column name
private  TableMap tableMap
          The TableMap referencing the ID_TABLE for this IDBroker.
private  boolean transactionsSupported
          Are transactions supported?
 
Constructor Summary
IDBroker(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.
 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.
private  java.math.BigDecimal getQuantity(java.lang.String tableName)
          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 stop()
          Shuts down the IDBroker thread.
private  void storeIDs(java.lang.String tableName, boolean adjustQuantity)
          Grabs more ids from the id_table and stores it in the ids Hashtable.
private  void updateRow(java.sql.Connection con, java.lang.String tableName, java.lang.String id)
          Helper method to update a row in the ID_TABLE.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

TABLE_NAME

public static final java.lang.String TABLE_NAME
Fully qualified Table_Name column name

NEXT_ID

public static final java.lang.String NEXT_ID
Fully qualified Next_ID column name

QUANTITY

public static final java.lang.String QUANTITY
Fully qualified Quantity column name

tableMap

private 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.

ids

private java.util.Hashtable ids
The cached IDs for each table. Key: String table name. Value: Vector 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.

sleepPeriod

private static final int sleepPeriod
Amount of time for the thread to sleep

safetyMargin

private static final float safetyMargin
The safety Margin

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!
Constructor Detail

IDBroker

public IDBroker(TableMap tMap)
Creates an IDBroker for the ID table.
Parameters:
tMap - A TableMap.
Method Detail

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.
Specified by:
getIdAsInt in interface IdGenerator
Parameters:
connection - A Connection.
keyInfo, - 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.
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.
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.
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.

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.
Parameters:
tableName - The name of the table for which we want an id.

storeIDs

private void storeIDs(java.lang.String tableName,
                      boolean adjustQuantity)
               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.
Parameters:
tableName - The name of the table for which we want an id.
adjustQuantity - True if amount should be adjusted.
Throws:
Exception, - a generic exception.

getQuantity

private java.math.BigDecimal getQuantity(java.lang.String tableName)
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.
Parameters:
tableName - The name of the table we want to query.
Returns:
An int with the number of ids cached in memory.

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.
Parameters:
con - A Connection.
tableName - The properly escaped name of the table to identify the row.
Returns:
A BigDecimal[].
Throws:
Exception, - a generic exception.

updateRow

private void updateRow(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.
Parameters:
con - A Connection.
tableName - The properly escaped name of the table to identify the row.
id - An int with the value to set for the id.
Throws:
java.lang.Exception - Database error.


Copyright © 2000-2002 Apache Software Foundation. All Rights Reserved.