"What's the difference between an Entity Object's post-state and entity-state?"
An entity object in the BC4J framework has methods to getPostState() as well as methods for getEntityState(). They both return a byte-valued constant from the list STATUS_NEW, STATUS_MODIFIED, STATUS_UNMODIFIED, etc. which are defined in the oracle.jbo.server.Entity interface. The difference between the two is this. Post state tells the state of the entity object with regard to the most recent postChanges() operation. Entity state is the state with respect to the whole transaction. This dichotomy exists because an entity object may be written to the database many times in one transaction before it is committed (via programmatic calls to postChanges() without calling commit() on the transaction interface).
So, after a post, the post-state may go to UNMODIFIED but entity-state may remain MODIFIED. Here is an example. Suppose you're reading a row in:
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 */
One of the motivations for introducing two different statuses was to support the ability to write business logic that conditionally executed when the status of an entity was new, regardless of how many times it might be posted during the transaction. Consider a business rule that needs to enforce a check or execute some logic only when an Order is first created. By checking for a getEntityStatus() == STATUS_NEW the code will execute correctly even if the newly created order was posted as part of its business logic.