ADF Faces RC: af:document uncommittedDataWarning property

Thanks to some assistance from Richard Wright from Oracle Corp on the OTN forums a week or so ago, I learnt about the uncommittedDataWarning property in the af:document tag, which I'd like to describe in this post.

This property is useful in the following scenario. Imagine you have a page as follows:


As you can see the page allows the user to change values of the current employee, and behind the scenes this is based on the usual ADFm bindings. In turn note the 3 buttons and their labels. For this screen there is a strict requirement for the developer to either Commit their changes or Undo them, before navigating back to the Home page.

Before the introduction of the uncommittedDataWarning property, the user could select the Go Home button and bypass this requirement. A workaround would be to set the Go Home button's disabled property such that the user couldn't navigate through the button if there were changes to be saved. However this is easily defeated by the user hitting the browser's back button, with the ensuing "JBO-35007: Row currency has changed since the user interface was rendered" mess that confuses users and developers no end.

With the introduction of the uncommitedDataWarning property for the af:document tag, and setting it to "on", if the user selects either the Go Home button (assuming we haven't disabled it) or the browser's back button without committing or undoing their work, they'll see the following browser error:


The dialog gives the user the option to Cancel, which leaves them on the current page, or Ok, which allows them to complete their action.

This is definitely an interesting feature, especially with its browser back button support.

One thing to note is that it only works for data that goes through the ADF binding layer. As such if you've JSF components based on a bean that isn't exposed to the ADF layer through a data control, it won't capture the data change. Thus this is another reason to ensure you don't hack code into the JSF layer, but expose it all through ADF Business Components or the other supported business service layer in ADF.

Also at this time the feature has a couple of limitations worth mentioning:

1) If the dialog displays and the user selects ok, the dialog will continue to display on each further page navigation until the user either commits or rolls back their changes. I can imagine this will become confusing or frustrating for some users, especially if you don't provide commit/rollback buttons on other pages.

2) As noted in this OTN post, I note that it is a warning mechanism and not an error mechanism (or at least, it doesn't have an option to enforce no navigation). It would seem ideal, especially with its back button functionality, to display an error only, leaving the user on the same page and forcing them to do a commit. Obviously this wouldn't be ideal in all cases, but certainly in some. I've raised ER 9299581 with Oracle Support for this.

3) As Richard Wright points out in the same post, "for a similar use case there has been a request to allow the user to continue with either a commit or rollback from the dialog. It would be analogous to the "Save" dialog received when exiting a native app (e.g., Word, Excel, JDev)." Hopefully we'll see these ERs in a future release.

I'm not overly sure when this property became available but I'm guessing the original JDev 11g release. It's definitely available in 11gR1 which this post was written against.