EJB 3.0 Java Persistence API – "Refresh After Insert": Using EntityListeners to absorb the effects from Database Triggers

4

While preparing an article for JDJ as well as a presentation for
Oracle Open World next week, I finally got round to finding a proper
solution for a challenge I set myself during the JavaPolis 2005
University presentation by Mike Keith on EJB 3.0 Java Persistence API:
how do I get my entities to absorb any changes applied to the database
records during Insert (and Update) as a result of the action of
Database Triggers?....

We at AMIS are Oracle database experts. We
know that database inside and out. Where some Java development shops
tend to shy away from the database apart from storing and retrieving
data in the plainest possible way, we are not afraid to use the
database for what it is good at. And we know that in many circumstances
our Java (Web) Application will not be the only application accessing
our database. Data Integrity for example must be implemented at the
database level to guarantee true data integrity. Along these same lines
lies the use of Database Triggers for several actions complementing
Insert, Update and Delete operations. An example of such a database
action is the derivation of (complex) default values and the
maintenance of auditing columns and denormalized values. Note that such
database triggers are not necessarily the consequence of our love for
the database, they may be a given in any situation you too might get
into.

The challenge we are facing in this situation: after
persisting a new entity, at some point in time the (EJB 3.0)
Persistency Provider will send the insert statement to the database;
typically this will happen when the flush() method is executed on the
EntityManager or the transaction on the EntityManager is committed –
though it may also happen at some earlier point in time if the provider
decides that is opportune. When the flush() is done or the transaction
is comitted, our – still managed – entity ideally is synchronized with
the database. However: if there are database triggers that fire on the
Insert operation to set additional (default) values or manipulate the
values that are inserted, we will have an aysnchronicity between database and entity even right after it was created in the first place. How do we have our entity refreshed?

How to refresh an entity in order to synchronize with the database?

Well, the JPA provides an EntityManager interface with a refresh method that takes an entity as input. We could use it. The question now is: when do we use it and who takes responsibility for calling it?

when: The call to refresh should take place no sooner than the database insert has taken place – and preferably not too long after it.

who: we would like to keep our entities free from intrusion by the framework or even the concept of persistence – at least apart from the necessary meta-data annotations. So we do not want to put the call to refresh inside the entity. What we need is an "entity watcher" who starts acting when an entity is in need of a refresh.

Enter the concept of the EntityListener (rather than an entity watcher). We can specify through the @EntityListeners annotation that one or more classes are interested in things happening to entities. Such classes are perfectly normal classes with one or more methods with the following signature:

public void anyNameYouLike( Entity entity)  <br />// or instead of the Entity class, one of the interfaces implemented by the entity <br />// or one of the superclasses - even Object will do

To hook an entity listener to specific events, we have to add annotations in the entity listener to the methods that trigger on those events. For example to have a listener respond to the deletion of an entity’s associated record from the database, we can add the @PostRemove annotation to our ‘listener’ method.

In the example of ‘synchronizing the entity with database to absorb the effect of database triggers upon insert of the database record’ we need to use the @PostPersist annotation that specifies our listener to get called immediately after the actual insert into the database has taken place. Note: that can be when flush() is called on the entity manager, it can be when the transaction on the entity manager gets committed or whenever after the persist on the entity the persistence provider feels like sending the insert to the database.

The ‘refresh entity immediately after insert’ method could look like this:

    @PostPersist<br />    public void insertEntity(Object entity) {<br />        em.refresh(entity);<br />    }<br /> <br />

A real example – well, a working one anyway…

This is another one of those Employee examples… But it demonstrates nicely how the refresh-after-insert might be set up. So please bear with me…

First of all – there was a database table called STAFF. It was created with the following DDL statements:

CREATE TABLE STAFF <br />( EMPNO NUMBER(4,0) NOT NULL ENABLE, <br />  ENAME VARCHAR2(10), <br />  JOB VARCHAR2(9) DEFAULT 'WORKER', <br />  MGR NUMBER(4,0), <br />  HIREDATE DATE DEFAULT sysdate, <br />  SAL NUMBER(12,2), <br />  COMM NUMBER(7,2), <br />  DEPTNO NUMBER(2,0), <br />  CONSTRAINT STAFF_PK PRIMARY KEY (EMPNO)<br />) <br />&nbsp;

Then there were a sequence and a trigger:

CREATE SEQUENCE  STAFF_SEQ  <br />MINVALUE 1 MAXVALUE 9999 <br />INCREMENT BY 1 START WITH 1 <br />/<br /><br />create or replace TRIGGER STAFF_INS BEFORE INSERT ON STAFF <br />FOR EACH ROW <br />begin<br />  if :new.empno is null or :new.empno =0 -- 0 gets assigned by EJB 3.0 JPA when no value is explicitly set on Entity<br />  then <br />    select staff_seq.nextval<br />    into   :new.empno<br />    from dual<br />    ;<br />  end if;<br />  if :new.job is null<br />  then<br />      :new.job:='WORKER';<br />  end if;<br />  if :new.hiredate is null<br />  then<br />      :new.hiredate:= sysdate;<br />  end if;<br />end;<br />/<br />   &nbsp;<br />

This trigger is fired whenever a record gets inserted into the STAFF table. When that happens, if EMPNO has no value yet, it will set the primary key (EMPNO) to the next value from the STAFF_SEQ sequence. If job is null, it will assign WORKER as default JOB value and if HIREDATE is empty, it will assign the current date as new hiredate.

Note: the Oracle database allows us to specify default values on columns. However, these will never play any part in records inserted by an EJB 30 JPA persistence provider (except for columns not mapped to the entities): the provider will insert values for all columns, inserting NULLs into columns for which the corresponding attributes were never set – causing no defaults to be applied. If you want to have default values applied you either have to set them in the entity itself (as part of the constructor or as initial values for the private fields) or you apply them through database triggers, as is done in this case. However, in the latter case you are perhaps assuming too much: the application may have had good reasons to set/leave the attribute value empty: who is the database to override that decision? Whatever is proper in your case, only you can decide.

Creating the Employee entity – mapped to the STAFF table

Our Java application needs to work with Employee objects and since we will make them persistent, mapped to the STAFF table, we will call them not just objects but entities.

The initial class definition for the Employee is as simple as can be(an):

package nl.amis.hrm.dao;<br /><br />import java.io.Serializable;<br />import java.sql.Date;<br /><br />public class Employee implements Serializable {<br />   <br />    private int empno;<br />    private String name;<br />    private String job;<br />    private float salalary;<br />    private Date hiredate;<br />   <br />    public Employee() {<br />    }<br /><br />    public void setEmpno(int empno) {<br />        this.empno = empno;<br />    }<br /><br />    public int getEmpno() {<br />        return empno;<br />    }<br /><br />    public void setName(String name) {<br />        this.name = name;<br />    }<br /><br />    public String getName() {<br />        return name;<br />    }<br /><br />    public void setJob(String job) {<br />        this.job = job;<br />    }<br /><br />    public String getJob() {<br />        return job;<br />    }<br /><br />    public void setSalalary(float salalary) {<br />        this.salalary = salalary;<br />    }<br /><br />    public float getSalalary() {<br />        return salalary;<br />    }<br /><br />    public void setHiredate(Date hiredate) {<br />        this.hiredate = hiredate;<br />    }<br /><br />    public Date getHiredate() {<br />        return hiredate;<br />    }<br />}<br />&nbsp;

We then add the necessary annotations to turn the bean into an entity; this will not change any of the accessor methods (getters and setters) so I only show the top part of the class definition:

package nl.amis.hrm.dao;<br /><br />import java.io.Serializable;<br /><br />import java.sql.Date;<br /><br />import javax.persistence.Column;<br />import javax.persistence.Entity;<br />import javax.persistence.EntityListeners;<br />import javax.persistence.GeneratedValue;<br />import javax.persistence.GenerationType;<br />import javax.persistence.Id;<br />import javax.persistence.NamedQuery;<br />import javax.persistence.SequenceGenerator;<br />import javax.persistence.Table;<br /><br />import nl.amis.hrm.EntityRefresher;<br /><br /><br />@Entity <br />@EntityListeners({EntityRefresher.class})<br />@Table(name=&quot;Staff&quot;)<br />@NamedQuery(name = &quot;Employee.findAll&quot;, query = &quot;select o from Employee o&quot;)<br />public class Employee implements Serializable {<br />   <br />    @SequenceGenerator(sequenceName=&quot;Staff_Seq&quot;, name=&quot;StaffGen&quot; , initialValue=1, allocationSize=1)<br />   <br />    @Id<br />    @GeneratedValue(generator=&quot;StaffGen&quot;, strategy=GenerationType.SEQUENCE)  <br />    private int empno;<br />    @Column(name=&quot;ename&quot;)<br />    private String name;<br />    private String job;

<br />    @Column(name=&quot;sal&quot;)<br />    private float salalary;<br />    private Date hiredate;<br />&nbsp;

Note the special annotation for EMPNO where we instruct our persistency provider to derive a value for EMPNO for newly persisted Employees from the database sequence STAFF_SEQ. You probably know about "configuration by exception": the principle that allows us to only annotate what deviates from the default. Since the columns that the attributes hiredate and job are mapped to have the same name as the attributes, no additional @Column annotation is needed; they are still mapped – because of the fact that they belong to an @Entity and have names corresponding to columns in the @Table sitting underneath the entity. Since the name attribute is mapped to a column with a different name  – ENAME – we need to provide the @Column annotation, to specify the exception to the rule.

Right under the @Entity annotation, there is the @EntityListeners annotation. It contains a comma-separated (Array) list of class-names for all listener to events on this particular entity. In this case, there is just the one: EntityRefresher. So for any of the events that can be listened for – pre and post persist, update and remove as well as post load – the EntityRefresher class will be inspected for the corresponding @Pre… and @Post… annotations and when found get instantiated and called.

The EntityListener class: EntityRefresher

The Entity Listener class has one or more methods with a @PreEvent and or @PostEvent annotation. Note that a single method can be called for multiple events. It has no way though of finding out which event is taking place (or not that I know of). The method needs to take a single input parameter. The Entity Manager will pass the entity that triggered the listener for that input parameter. So the parameter must be of the entity type (or one of its superclasses) or be an interface that is implemented by the entity.

In this example, I have decided to create a generic entity listener class, one that can refresh any entity after it was inserted. The code is quite simple:

package nl.amis.hrm;<br /><br />import javax.persistence.EntityManager;<br />import javax.persistence.PostPersist;<br />import nl.amis.hrm.dao.Employee;<br /><br />public class EntityRefresher {<br />    public EntityRefresher() {<br />    }<br /><br />    private static EntityManager em = null;<br /><br />    public static void setEm(EntityManager entityManager) {<br />        em = entityManager;<br />    }<br /><br />    @PostPersist<br />    public void insertEntity(Object entity) {<br />        em.refresh(entity);<br />        if (entity instanceof Employee) {<br />          System.out.println(&quot;Inserted staff &quot; + ((Employee)entity).getName());<br />            System.out.println(&quot;Job = &quot; + ((Employee)entity).getJob());<br />            System.out.println(&quot;Hiredate = &quot; + ((Employee)entity).getHiredate());<br />        }<br />    }<br /><br />}<br />&nbsp;

Note that I have allowed a little bit of code for demonstration purposes. The EntityRefresher gets injected the EntityManager from somewhere at some point in time prior to the actual insert taking place. When the entities listened for are inserted, the insertEntity() method is called by the EntityManager. It uses the EntityManager handle em to refresh the entity that was just inserted.

Putting it to work…

In order to try this out, we need a persistence-unit in a persistence.xml file and some sort of service class that does the communication with the EntityManager. Well, the simplest piece of code for demonstrating the entity callbacks is something like this:

package nl.amis.hrm;<br /><br />import javax.persistence.EntityManager;<br />import javax.persistence.EntityManagerFactory;<br />import javax.persistence.Persistence;<br /><br />import javax.persistence.PostPersist;<br /><br />import nl.amis.hrm.dao.Employee;<br /><br />public class HrmService {<br />    static EntityManager em =null;<br />    public HrmService() {<br />    }<br />    <br />    <br />    public static void main(String[] args) {<br />        EntityManagerFactory emf = Persistence.createEntityManagerFactory(&quot;Hrm&quot;);<br />        em = emf.createEntityManager();<br />        EntityRefresher.setEm(em);<br />        <br />        Employee emp = new Employee();<br />        emp.setName(&quot;Tobias&quot;);<br />        emp.setSalalary(1000);<br />        em.getTransaction().begin();<br />        em.persist(emp);<br />        em.getTransaction().commit();<br />    }<br />}<br /><br />

When we run this code – with logging turned on – the output contains the following:

07:06:33.369--ServerSession(22528701)--Thread(Thread[main,5,main])--client acquired<br />07:06:33.409--ServerSession(22528701)--Connection(14069849)--Thread(Thread[main,5,main])<br />  --SELECT Staff_Seq.NEXTVAL FROM DUAL<br />07:06:33.729--UnitOfWork(5156931)--Thread(Thread[main,5,main])<br />  --begin unit of work commit<br />07:06:33.729--ClientSession(30254491)--Connection(33341602)--Thread(Thread[main,5,main])<br />  --begin transaction<br />07:06:33.739--ClientSession(30254491)--Connection(33341602)--Thread(Thread[main,5,main])<br />  --INSERT INTO Staff (EMPNO, JOB, sal, ename, HIREDATE) VALUES (?, ?, ?, ?, ?)<br />	bind =&gt; [21, null, 1000.0, Tobias, null]<br />07:06:34.430--ClientSession(30254491)--Connection(33341602)--Thread(Thread[main,5,main])<br />  --SELECT EMPNO, JOB, sal, ename, HIREDATE FROM Staff WHERE (EMPNO = ?)<br />	bind =&gt; [21]<br />Inserted staff Tobias<br />Job = WORKER<br />Hiredate = 2006-10-17<br />07:06:34.480--ClientSession(30254491)--Connection(33341602)--Thread(Thread[main,5,main])<br />  --commit transaction<br />07:06:34.480--UnitOfWork(5156931)--Thread(Thread[main,5,main])<br />  --end unit of work commit<br />07:06:34.490--UnitOfWork(5156931)--Thread(Thread[main,5,main])--resume unit of work <br />

The sequence is used as soon as the persist is called for the new Employee entity. When the transaction is committed, the INSERT into the database takes place. Immediately after that, we see the refresh() method in action: select from staff where emp = 21. Next we see our own output: the new Employee is a WORKER – even though we never set the value for the Job attribute. Clearly this is the effect of the database triggers.

Note: this refresh from database relies on the value of the primary key. We cannot use this mechanism to have database triggers derive the value of the primary key from a sequence: this value must be known to the EntityManager before the persist/insert is performed.

Resources

Pro EJB 3: Java Persistence API By Mike Keith Merrick Schincariol ISBN: 1-59059-645-5

Blog by Raghu Kodali looking for the ‘refresh after insert trigger functionality in the JPA – EJB 3.0 – Refreshing entity with values populated from database triggers

Article on the presentation by Mike Keith (EJB 3.0 Specification Lead and Oracle TopLink expert) on EJB 3.0 JPA EJB 3.0 Reference Implementation with teeth – Open Source EJB 3.0 by Sun and Oracle (Report from JavaPolis)

JPA Annotations Reference for Oracle Toplink 

Share.

About Author

Lucas Jellema, active in IT (and with Oracle) since 1994. Oracle ACE Director for Fusion Middleware. Consultant, trainer and instructor on diverse areas including Oracle Database (SQL & PLSQL), Service Oriented Architecture, BPM, ADF, Java in various shapes and forms and many other things. Author of the Oracle Press book: Oracle SOA Suite 11g Handbook. Frequent presenter on conferences such as JavaOne, Oracle OpenWorld, ODTUG Kaleidoscope, Devoxx and OBUG. Presenter for Oracle University Celebrity specials.

4 Comments

  1. Section 3.4 of the spec states:

    The following rules apply to callbacks:

    Callbacks can invoke JNDI, JDBC, JMS, and enterprise beans, but NOT the EntityManager. (emphasis mine)

    You stated, “The EntityRefresher gets injected the EntityManager from somewhere at some point in time prior to the actual insert taking place.” via the setEm method? Can you be more specific as to the “from somewhere” and “at some point in time prior to” ?

    The idea is exactly what I need; I guess I need to play around with a little more to get it working.

  2. I’ve just re-read the “EJB 3.0 – Persistence” specification,
    in “3.5 Entity Listeners and Callback Methods” it say:

    “In general, portable applications should not invoke EntityManager or Query operations,
    access other entity instances, or modify relationships in a lifecycle callback method.”
    (page 58)

    This means that it is not portable to use em.refresh(), em.find(), em.createQuery(), etc. operations in @PostPersist handler.

    So, the example above works well in this concrete implementation, but it is not guaranteed to work everywhere… So, a better way would be to use @PrePersist and set entity fields there instead of trigger.

  3. Hi Duke,

    The JPA will not get back control before the database has completed the set of statements that were flushed or the transaction has been executed. In an Oracle database at least, row-level triggers (as well as statement level trigers by the way) will complete before the JPA regains control. That means that when the EntityListener is called (back), the full trigger effect will be there.

    regards

    Lucas

  4. Duke Javastein on

    Hi,

    What if when the JPA engine called the insertEntity method the trigger was not completed? Is it guaranteed that the trigger completes in the same transaction that the insert is performed?

    – Duke