Package org.apache.torque.oid

# Klasse IDBroker

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

Alle implementierten Schnittstellen:
  `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 1917245 2024-04-21 14:06:23Z tv $
Autor:
  Frank Y. Kim, John D. McNally, Henning P. Schmiedehausen

- ## Feldübersicht

  Felder
  Modifizierer und Typ
  Feld
  Beschreibung
  `static final String`
  `COL_NEXT_ID`
  Next_ID column name
  `static final String`
  `COL_QUANTITY`
  Quantity column name
  `static final String`
  `COL_TABLE_ID`
  ID column name
  `static final String`
  `COL_TABLE_NAME`
  Table_Name column name
  `static final String`
  `ID_TABLE`
  Name of the ID_TABLE = ID_TABLE
  `static final String`
  `NEXT_ID`
  Fully qualified Next_ID column name
  `static final String`
  `QUANTITY`
  Fully qualified Quantity column name
  `static final String`
  `TABLE_ID`
  Fully qualified ID column name
  `static final String`
  `TABLE_NAME`
  Fully qualified Table_Name column name

- ## Konstruktorübersicht

  Konstruktoren
  Konstruktor
  Beschreibung
  `IDBroker(Database database)`
  Constructs an IdBroker for the given Database.

- ## Methodenübersicht

  Modifizierer und Typ
  Methode
  Beschreibung
  `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 generation
  `boolean`
  `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 configuration
  `void`
  `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.

  ### Von Klasse geerbte Methoden java.lang.Object

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

- ## Felddetails

  - ### ID_TABLE

    public static final String ID_TABLE
    Name of the ID_TABLE = ID_TABLE
    Siehe auch:
      - Konstantenfeldwerte

  - ### COL_TABLE_NAME

    public static final String COL_TABLE_NAME
    Table_Name column name
    Siehe auch:
      - Konstantenfeldwerte

  - ### TABLE_NAME

    public static final String TABLE_NAME
    Fully qualified Table_Name column name
    Siehe auch:
      - Konstantenfeldwerte

  - ### COL_TABLE_ID

    public static final String COL_TABLE_ID
    ID column name
    Siehe auch:
      - Konstantenfeldwerte

  - ### TABLE_ID

    public static final String TABLE_ID
    Fully qualified ID column name
    Siehe auch:
      - Konstantenfeldwerte

  - ### COL_NEXT_ID

    public static final String COL_NEXT_ID
    Next_ID column name
    Siehe auch:
      - Konstantenfeldwerte

  - ### NEXT_ID

    public static final String NEXT_ID
    Fully qualified Next_ID column name
    Siehe auch:
      - Konstantenfeldwerte

  - ### COL_QUANTITY

    public static final String COL_QUANTITY
    Quantity column name
    Siehe auch:
      - Konstantenfeldwerte

  - ### QUANTITY

    public static final String QUANTITY
    Fully qualified Quantity column name
    Siehe auch:
      - Konstantenfeldwerte

- ## Konstruktordetails

  - ### IDBroker

    public IDBroker(Database database)
    Constructs an IdBroker for the given Database.
    Parameter:
      `database` - the database where this IdBroker is running in.

- ## Methodendetails

  - ### start

    public void start()
    Starts the idBroker.

  - ### setConfiguration

    public void setConfiguration(org.apache.commons.configuration2.Configuration configuration)
    Set the configuration
    Parameter:
      `configuration` - the configuration

  - ### getIdAsInt

    public int getIdAsInt(Connection connection, Object tableName) throws TorqueException
    Beschreibung aus Schnittstelle kopiert: `IdGenerator`
    Returns an id as a primitive int. If you use numeric identifiers, it's suggested that `IdGenerator.getIdAsLong(Connection, Object)` be used instead (due to the limited range of this method).
    Angegeben von:
      `getIdAsInt` in Schnittstelle `IdGenerator`
    Parameter:
      `connection` - A Connection.
      `tableName` - an Object that contains additional info.
    Gibt zurück:
      An int with the value for the id.
    Löst aus:
      `TorqueException` - Database error.
    Siehe auch:
      - `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
    Beschreibung aus Schnittstelle kopiert: `IdGenerator`
    Returns an id as a primitive long.
    Angegeben von:
      `getIdAsLong` in Schnittstelle `IdGenerator`
    Parameter:
      `connection` - A Connection.
      `tableName` - a String that identifies a table.
    Gibt zurück:
      A long with the value for the id.
    Löst aus:
      `TorqueException` - Database error.
    Siehe auch:
      - `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
    Angegeben von:
      `getIdAsBigDecimal` in Schnittstelle `IdGenerator`
    Parameter:
      `connection` - A Connection.
      `tableName` - a String that identifies a table..
    Gibt zurück:
      A BigDecimal id.
    Löst aus:
      `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
    Angegeben von:
      `getIdAsString` in Schnittstelle `IdGenerator`
    Parameter:
      `connection` - A Connection should be null.
      `tableName` - a String that identifies a table.
    Gibt zurück:
      A String id
    Löst aus:
      `TorqueException` - Database error.

  - ### isPriorToInsert

    public boolean isPriorToInsert()
    A flag to determine the timing of the id generation *
    Angegeben von:
      `isPriorToInsert` in Schnittstelle `IdGenerator`
    Gibt zurück:
      a `boolean` value

  - ### isPostInsert

    public boolean isPostInsert()
    A flag to determine the timing of the id generation
    Angegeben von:
      `isPostInsert` in Schnittstelle `IdGenerator`
    Gibt zurück:
      a `boolean` value

  - ### isConnectionRequired

    public boolean isConnectionRequired()
    A flag to determine whether a Connection is required to generate an id.
    Angegeben von:
      `isConnectionRequired` in Schnittstelle `IdGenerator`
    Gibt zurück:
      a `boolean` value

  - ### isGetGeneratedKeysSupported

    public boolean isGetGeneratedKeysSupported()
    A flag to determine whether Statement#getGeneratedKeys() should be used.
    Angegeben von:
      `isGetGeneratedKeysSupported` in Schnittstelle `IdGenerator`
    Gibt zurück:
      a `boolean` value

  - ### isThreadRunning

    public boolean isThreadRunning()
    Returns whether the idbroker thread is running.
    Gibt zurück:
      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.
    Parameter:
      `tableName` - The name of the table for which we want an id.
      `numOfIdsToReturn` - The desired number of ids.
    Gibt zurück:
      A BigDecimal.
    Löst aus:
      `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
    Parameter:
      `tableName` - The name of the table for which we want an id.
      `numOfIdsToReturn` - The desired number of ids.
      `connection` - A Connection.
    Gibt zurück:
      A BigDecimal.
    Löst aus:
      `TorqueException` - on a database error.

  - ### exists

    public boolean exists(String tableName) throws Exception
    Parameter:
      `tableName` - a `String` value that is used to identify the row
    Gibt zurück:
      a `boolean` value
    Löst aus:
      `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.
    Angegeben von:
      `run` in Schnittstelle `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.

  - ### updateQuantity

    protected void updateQuantity(Connection con, String tableName, BigDecimal quantity) throws TorqueException
    Helper method to update a row in the ID_TABLE.
    Parameter:
      `con` - A Connection.
      `tableName` - The properly escaped name of the table to identify the row.
      `quantity` - An int with the value of the quantity.
    Löst aus:
      `TorqueException` - Database error.

  - ### getQuantity

    protected BigDecimal getQuantity(String tableName)
    Returns the quantity value for a table.
    Parameter:
      `tableName` - the name of the table.
    Gibt zurück:
      the quantity value for the table, or null if the table is (still) unknown.