9.5 Undoing Pending Changes to an Entity Using the Refresh Method

You can use the refresh(int flag) method on any Row to refresh pending changes it might have. The refresh() method's behavior depends on the flag that you pass as a parameter. The three key flag values that control its behavior are the following constants in the Row interface.

• REFRESH_WITH_DB_FORGET_CHANGES forgets modifications made to the row in the current transaction and the row's data is refreshed from database. The latest data from database replaces data in the row regardless of whether the row was modified or not.

• REFRESH_WITH_DB_ONLY_IF_UNCHANGED works just like REFRESH_WITH_DB_FORGET_CHANGES, but for unmodified rows. If a row was already modified by this transaction, the row is not refreshed.

• REFRESH_UNDO_CHANGES works the same as REFRESH_WITH_DB_FORGET_CHANGES for unmodified rows. For a modified row, this mode refreshes the row with attribute values at the beginning of this transaction. The row remains in a modified state.

9.5.1 Controlling What Happens to New Rows During a Refresh

By default, any entity rows with New status that you refresh() are reverted back to blank rows in the Initialized state. Declarative defaults are reset, as well as programmatic defaults coded in the initDefaults() method, but the entity object's create() method is not invoked during this blanking-out process.

You can change this default behavior by combining one of the following two flags with one from the above section (using the bitwise-OR operator):

• REFRESH_REMOVE_NEW_ROWS, new rows are removed during refresh.

• REFRESH_FORGET_NEW_ROWS, new rows are marked Dead.

9.5.2 Cascading Refresh to Composed Children Entity Rows

You can cause a refresh() operation to cascade to composed child entity rows by bitwise-OR'ing the REFRESH_CONTAINEES flag with any of the valid flag combinations above. This causes the entity to invoke refresh() using the same mode on any composed child entities it contains.