Starting the JPA time-based updater

When you start the Java™ Persistence API (JPA) time-based updater, the ObjectGrid maps are updated with the latest changes in the database.

• Start a time-based database updater.
  • Automatically for distributed eXtreme Scale:

    If you create the timeBasedDBUpdate configuration for the backing map, the time-based database updater is automatically started when a distributed ObjectGrid primary shard is activated. For an ObjectGrid that has multiple partitions, the time-based database updater only starts at partition 0.

  • Automatically for local eXtreme Scale:

    If you create the timeBasedDBUpdate configuration for the backing map, the time-based database updater is automatically started when the local map is activated.

  • Manually:
    You can also manually start or stop a time-based database updater using the TimeBasedDBUpdater API.

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

    1. ObjectGrid: the ObjectGrid instance (local or client).
    2. mapName: the name of the backing map for which the time-based database updater is started.
    3. punitName: the JPA persistence unit name for creating a JPA entity manager factory; the default value is the name of the first persistence unit defined in the persistence.xml file.
    4. entityClass: The entity class name used to interact with the Java Persistence API (JPA) provider; the entity class name is used to get JPA entities using entity queries.
    5. timestampField: A timestamp field of the entity class to identify the time or sequence when a database back end record was last updated or inserted.
    6. mode: The time-based database update mode; an INVALIDATE_ONLY type causes it to invalidate the entries in the ObjectGrid map if the corresponding records in the database have changed; an UPDATE_ONLY type indicates to update the existing entries in the ObjectGrid map with the latest values from the database; however, all the newly inserted records to the database are ignored; an INSERT_UPDATE type indicates to update the existing entries in the ObjectGrid map with the latest values from the database; also, all the newly inserted records to the database are inserted into the ObjectGrid map.

    If you want to stop the time-based database updater, you can call the following method to stop the updater:

    public synchronized void stopDBUpdate(ObjectGrid objectGrid, String mapName)

    The ObjectGrid and mapName parameters should be the same as those passed in the startDBUpdate method.

• Create the timestamp field in your database.
  • DB2®

    As a part of the optimistic locking feature, DB2 9.5 provides a row change timestamp feature. You can define a column ROWCHGTS using the ROW CHANGE TIMESTAMP format as follows:

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

    Then you can indicate the entity field which corresponds to this column as the timestamp field by either annotation or configuration. An example follows:

    @Entity(name = "USER_DB2")
    @Table(name = "USER1")
    public class User_DB2 implements Serializable {
    
        private static final long serialVersionUID = 1L;
    
        public User_DB2() {
        }
    
        public User_DB2(int id, String firstName, String lastName) {
            this.id = id;
            this.firstName = firstName;
            this.lastName = lastName;
        }
    
        @Id
        @Column(name = "ID")
        public int id;
    
        @Column(name = "FIRSTNAME")
        public String firstName;
    
        @Column(name = "LASTNAME")
        public String lastName;
    
        @com.ibm.websphere.objectgrid.jpa.dbupdate.annotation.Timestamp
        @Column(name = "ROWCHGTS", updatable = false, insertable = false)
        public Timestamp rowChgTs;
    }
    

  • Oracle

    In Oracle, there is a pseudo-column ora_rowscn for the system change number of the record. You can use this column for the same purpose. An example of the entity that uses the ora_rowscn field as the time-based database update timestamp field follows:

    @Entity(name = "USER_ORA")
    @Table(name = "USER1")
    public class User_ORA implements Serializable  {
    
        private static final long serialVersionUID = 1L;
    
        public User_ORA() {
        }
    
        public User_ORA(int id, String firstName, String lastName) {
            this.id = id;
            this.firstName = firstName;
            this.lastName = lastName;
        }
    
        @Id
        @Column(name = "ID")
        public int id;
    
        @Column(name = "FIRSTNAME")
        public String firstName;
    
        @Column(name = "LASTNAME")
        public String lastName;
    
        @com.ibm.websphere.objectgrid.jpa.dbupdate.annotation.Timestamp
        @Column(name = "ora_rowscn", updatable = false, insertable = false)
        public long rowChgTs;
    }

  • Other databases

    For other types of databases, you can create a table column to track the changes. The column values have to be manually managed by the application that updates the table.

    Take an Apache Derby database as an example: You can create a column "ROWCHGTS" to track the change numbers. Also, a latest change number is tracked for this table. Every time a record is inserted or updated, the latest change number for the table is incremented, and the ROWCHGTS column value for the record is updated with this incremented number.

    @Entity(name = "USER_DER")
    @Table(name = "USER1")
    public class User_DER implements Serializable {
    
        private static final long serialVersionUID = 1L;
    
        public User_DER() {
        }
    
        public User_DER(int id, String firstName, String lastName) {
            this.id = id;
            this.firstName = firstName;
            this.lastName = lastName;
        }
    
        @Id
        @Column(name = "ID")
        public int id;
    
        @Column(name = "FIRSTNAME")
        public String firstName;
    
        @Column(name = "LASTNAME")
        public String lastName;
    
        @com.ibm.websphere.objectgrid.jpa.dbupdate.annotation.Timestamp
        @Column(name = "ROWCHGTS", updatable = true, insertable = true)
        public long rowChgTs;
    }