There are lots of blog posts on this but all copy and paste the content of EntityImpl javadoc, which is very obscure. I finally found a sensible explanation in Dive into Oracle ADF, but that is usually buried deep in Google results.
I will restate the Dive into Oracle ADF post here, and will add few finer details.
In DB you can run the DML queries as many times as you want without committing them. When we are saving data to DB the call chain is like –
transaction.postChanges() -> entity.postChanges() -> entity.prepareForDML() -> entity.doDML(). The entity’s DML operations depend on the post-state. So,
transaction.postChanges() effectively make all entities to write their data to DB. They do that by checking their internal post-states and creating appropriate DML queries based on those states. After the DML action the post-state is updated. So, if before
postChanges() if the post-state was
STATUS_NEW, then after that it would be
STATUS_UNMODIFIED, so that on next
postChanges() call it doesn’t try to insert the row again.
Entity-state on the other hand represents the entity’s state irrespective of the fact that the changes has been posted (written) to the DB. So, even if all changes in entity are posted, the entity-state remains
STATUS_MODIFIED. Entity-state changes only after commit is invoked on the transaction. Unless and until a transaction is committed the changes done in the transaction is not visible in other transactions (this is a feature of relational DB), so, when entity-state changes we know that those changes are now visible to all transactions.
#!java row = vo.first(); /* read a row in from DB. Both EO states are UNMODIFIED */ row.setAttribute("SomeAttr", someValue); /* After this, both states are MODIFIED */ am.getTransaction().postChanges(); /* Changes are written to DB. Trans not committed yet */ /* After this, post-state is UNMODIFIED. Entity-state is MODIFIED */ am.getTransaction().commit(); /* Transaction committed. After this, both states are UNMODIFIED */
If you see EntityImpl’s javadoc then you will notice that we have one extra post-state –
STATUS_INITIALIZED. Entities have this post-state only when it is newly created. The moment one of its attribute is set, this changes to
postChanges() is invoked then DML action is skipped if post-state is
STATUS_INITIALIZED. This prevents blank rows from getting inserted. Entity-state never has this value since entity-state is meant to be used for writing business logic, and from that perspective
STATUS_INITIALIZED makes no difference.