com.ibm.websphere.objectgrid.jpa.dbupdate
Class TimeBasedDBUpdater

java.lang.Object
  com.ibm.websphere.objectgrid.jpa.dbupdate.TimeBasedDBUpdater

public class TimeBasedDBUpdater
extends Object

A time-based database updater can be used to periodically get the latest inserts and updates to the ObjectGrid backend database. A time-based database updater interacts with Java Persistence API (JPA) to get the latest changes (inserts and updates) from the database using a specific timestamp field. Therefore, a JPA provider is required to use this feature. The database here can be any backend supported by the chosen JPA provider.

The time-based database updater periodically query the database using JPA interfaces to get the JPA entities which represent the newly inserted and updated records in the database. In order to do that, every record in the database should have a "timestamp" to identify the time or sequence when the record was last updated or inserted. The "timestamp" here does not have to be in a timestamp format. It can be in a an integer or long format, as long as it generates a unique increasing value.

Several commercial databases have provided this capability.

For example, in DB2 9.5, you can define a column using the ROW CHANGE TIMESTAMP format as follows:

 ROWCHGTS TIMESTAMP NOT NULL
      GENERATED ALWAYS
      FOR EACH ROW ON UPDATE AS
      ROW CHANGE TIMESTAMP
 

In Oracle, you can use the pseudo-column ora_rowscn, which represents the system change number of the record.

Using this timestamp, the time-based database updater utilize the following two queries to get the latest database changes:

1. The first query selects all the entities whose timestamp is greater than a timestamp: The query syntax is SELECT o FROM ENTITY o where o.TIMESTAMP > ?1.
2. The second query gets the maximum timestamp from all exsting JPA entities. The query syntax is SELECT MAX(o.TIMSTAMP) FROM ENTITY o.

In both queries, the "ENTITY" is the JPA entity name, and the "TIMESTAMP" is the JPA entity attribute which represents the timestamp column in database.

However, record removes to the backend database cannot be detected.

The time-based database updater can be launched in the following two ways:

1. For a distributed or local ObjectGrid, if a "timeBasedDBUpdate" element is configured for a backing map, a time-based database updater is automatically launched. For the distributed objectgrid, it will only be launched in partition 0.
2. For a distributed or local ObjectGrid, a user application can launch a time-based database updater using this TimeBasedDBUpdater interface by calling startDBUpdate.

Since:

XD 6.1.0.3

See Also:

Timestamp, BackingMap

Method Summary

static TimeBasedDBUpdater	instance()
void	startDBUpdate(ObjectGrid objectGrid, String mapName, String punitName, Class entityClass, String timestampField, TimeBasedDBUpdateConfig.DBUpdateMode mode) Start a time-base database update thread to keep the ObjectGrid data updated from the database back end
void	stopDBUpdate(ObjectGrid objectGrid, String mapName) Stop the time-based database update thread

Methods inherited from class java.lang.Object

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

Method Detail

instance

public static TimeBasedDBUpdater instance()

Returns:

an instance of TimeBasedDBUpdater.

startDBUpdate

public void startDBUpdate(ObjectGrid objectGrid,
                          String mapName,
                          String punitName,
                          Class entityClass,
                          String timestampField,
                          TimeBasedDBUpdateConfig.DBUpdateMode mode)

Start a time-base database update thread to keep the ObjectGrid data updated from the database back end

Parameters:

objectGrid - the ObjectGrid instance

mapName - the map name to be updated

punitName - the JPA persistence unit name

entityClass - the JPA entity class which represents the database table

timestampField - the timestamp field used by ObjectGrid to query the changes

mode - the database update mode.

Throws:

ObjectGridException

stopDBUpdate

public void stopDBUpdate(ObjectGrid objectGrid,
                         String mapName)

Stop the time-based database update thread

Parameters:

objectGrid - the ObjectGrid instance

mapName - the map name to be updated

Throws:

IllegalArgumentException - If there is no time-based database update thread started for this map.