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 name
    `static String` | `COL_QUANTITY` | Quantity column name
    `static String` | `COL_TABLE_ID` | ID column name
    `static String` | `COL_TABLE_NAME` | Table_Name column name
    `static String` | `ID_TABLE` | Name of the ID_TABLE = ID_TABLE
    `static String` | `NEXT_ID` | Fully qualified Next_ID column name
    `static String` | `QUANTITY` | Fully qualified Quantity column name
    `static String` | `TABLE_ID` | Fully qualified ID column name
    `static String` | `TABLE_NAME` | Fully qualified Table_Name column name

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `IDBroker​(Database database)` | Constructs an IdBroker for the given Database.

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

    - ### 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 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 that `IdGenerator.getIdAsLong(Connection, Object)` be used instead (due to the limited range of this method).
      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:
        `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 interface `IdGenerator`
      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 interface `IdGenerator`
      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 interface `IdGenerator`
      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 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

    - #### isGetGeneratedKeysSupported

          public boolean isGetGeneratedKeysSupported()

      A flag to determine whether Statement#getGeneratedKeys() should be used.
      Specified by:
        `isGetGeneratedKeysSupported` in interface `IdGenerator`
      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` - a `String` 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.
      Specified by:
        `run` in interface `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.
      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.