Java Developer

ORACLE ADF BY FRANK NIMPHIUS

ORACLE APPLICATION DEVELOPMENT FRAMEWORK AND ORACLE JDEVELOPER

Catch Me If You Can

Manage error handling in Oracle ADF applications.

GIL ADAMS

ava EE applications such as those you build

with Oracle Application Development
Framework (Oracle ADF) are based on a
layered architecture following the modelview-controller paradigm. In such a layered
architecture, each layer can become the
origin of an application error that requires
handling. As a consequence, error handling
should be designed and implemented in all
application layers.
Error handling is a large knowledge area,
and complete coverage of the topic exceeds
the Oracle Magazine article format. To fit
the available format, this article covers an
overview of error handling in Oracle ADF,
followed by hands-on instructions on how
to implement custom error handlers on the
Oracle ADF Controller layer.
ORACLE ADF ERROR HANDLING
ARCHITECTURE
As shown in Figure 1, the Oracle ADF application architecture consists of four layers:
business service, Model, Controller, and
View. Errors can occur in any of these application layers.
The business service layer contains the
business logic and handles the datasource
interaction required for querying data and
persisting changes. This layer can produce
validation errorsincluding database
errorsand informational warnings.
The Oracle ADF Model (referred to in the
sample application as ADFm) layer consists
of two parts, the business-service-specific
data control that connects Oracle ADF to
data bindings and services such as Oracle
ADF Business Components, Pojo, Web
services, or Enterprise JavaBeans (EJB). The
data binding definition for a view is defined
in metadata and is referred to as the ADF
Binding Layer at runtime. The responsibility of the binding layer is to connect user
interface components with the data and
business logic exposed by the business

service through the data control. Binding

errors occur in cases of row key issues,
client component binding failures, malformed expression language (EL) expressions, and so on. If validation rules are
defined on a binding container, validation
errors can also occur.
The Oracle ADF Controller (referred to in
the sample application as ADFc) layer handles
application navigation and the client request
lifecycle. Oracle ADF Controller errors occur
in case of metadata configuration problems,
missing user authorization, mismatches in
task flow transaction settings, invalid input
parameter objects, and so on.
The Oracle ADF View (referred to in the
sample application as ADFv) layer, represented by Oracle ADF Faces in Oracle ADF,
provides a set of UI components for building
GUIs and temporarily holding user data input
until the data is written to the model. View
layer errors include client-side validation
problems, datatype conversion failure, view
expiry, EL reference problems, and so on.
Figure 1 shows the various Oracle ADF

architecture layers introduced earlier. Using

Oracle ADF, applications facilitate the Oracle
ADF Model for querying or updating data
exposed through business services such as
Oracle ADF Business Components. Errors
that occur in the business service during
data query or update propagate to the
Oracle ADF Model if the business service
doesnt handle them by, for example, using
a Java try/catch block surrounding validation or business logic.
The Oracle ADF Model error handler
and Oracle ADF Controller error handler
activity defined for a task flow are central
in the overall Oracle ADF application error
handling.
Errors that occur in a context outside
of the Oracle ADF Model or during the
JavaServer Faces (JSF) render response
phase must be handled manually by developers, who can use a try/catch block in
Java or implement a custom Oracle ADF
Controller exception handler class.
As a last resort, you can configure the
web.xml file so that specific error types and

Servlet container

Unhandled exceptions

Oracle ADF Faces

Render
response

Oracle ADF Controller

Propagates exceptions
Oracle ADF Model

Oracle ADF Binding Layer

Data Control

Unhandled exceptions
Oracle ADF Business Components

Java

JAX-WS

EJB/JPA

Business service layer

Figure 1: Oracle ADF error handling architecture

ORACLE MAGAZINE MARCH/APRIL 2013

37

38

ORACLE ADF

HTTP error codes are handled by the Java EE

Servlet container.
In Oracle ADF, your best option for handling application errors is to ensure that the
business service is always accessed through
the Oracle ADF Model layer. Direct access of
the business service from managed beans
should be banned in your Oracle ADF developer guidelines.
The Oracle ADF base exception class,
oracle.jbo.JboException, extends java
.lang.RuntimeException. JboException or
any of its subclasses can be called from
anywhere in an application without the
need to declare the call as part of a method
signature. Developers who want to build
and call custom exceptions should extend
JboException or one of its subclasses for best
integration with Oracle ADF.
GETTING READY
To follow the hands-on steps in this article,
youll need the studio edition of Oracle
JDeveloper 11g Release 2 (11.1.2.3), available
as a free download on Oracle Technology
Network at bit.ly/LRlg7k. You also need
access to an Oracle Database instance
with an unlocked HR schema. Get started
by downloading the o23adf-1896561.zip
sample application at bit.ly/10mJLA6 and
unzipping the file.
To prepare for the hands-on steps, change
the database connection used by the Oracle
ADF Business Components Model project to
point to your HR database schema:
1. Launch Oracle JDeveloper 11g Release 2.
From the Oracle JDeveloper menu bar,
select File -> Open, and then navigate to
the directory containing the unpacked
sample application.
2. Open the ErrorHandling folder, select the
ErrorHandling.jws file, and click Open.
The workspace opens.
3. Select View -> Database -> Database
Navigator, and expand the ErrorHandling
node to display the hrconn node.
4. Right-click hrconn, and select Properties
from the context menu. Edit the database connection information to work
with your setup. Test the changes, and
click OK.
As another preliminary task, start the
Oracle WebLogic Server instance inte-

MARCH/APRIL 2013 ORACLE.COM/ORACLEMAGAZINE

Figure 2: Sample application screen for department 30

grated with Oracle JDeveloper. To start

the Oracle WebLogic Server instance,
select Run -> Start Server Instance
(IntegratedWebLogicServer).
If this is the first time youve run the
integrated Oracle WebLogic Server instance,
a Create Default Domain dialog box will
open. Create a password for the default
Oracle WebLogic Server domain, and select
an address from those listed for Listen
Address. For example, choose localhost
rather than leaving the address empty.
Click OK to save the password and
address, create the default domain, and
configure it for Oracle ADF.
SAMPLE APPLICATION OVERVIEW
The sample application contains five Oracle
JDeveloper projects:
ADfErrorHandlingUtil contains the Oracle
ADF Controller and Oracle ADF Model
error handler code you will use during the
hands-on steps in this article and is referenced as a dependency in other projects.
BoundedTaskFlowUtil contains a task
flow template for you to use to configure
a method activity as an error handler to
be used by all bounded task flows in the
sample application.
Model contains view objects for querying
department and dependent employee data.
It exposes client methods on the application module to simulate exceptions thrown
when youre working with Oracle ADF. The
Employees entity has a validation rule
defined to prevent the last name field from
being updated to King.
UnboundedTaskFlowUtil is precreated
for you and contains an unbounded adfc-

config.xml file with an error handler activity.

ViewController contains the task flows and
the binding context to which you will add
error handling in the hands-on steps.
Disclaimer: For your convenience, all projects in this sample application are created in
a single Oracle JDeveloper workspace and all
bounded task flows are in one ViewController
project. Note that this is not necessarily
best-practice design.
Run the sample application by selecting
the Oracle JDeveloper Application
(Navigator) tab, selecting View Controller ->
Web Content -> pages -> DeptEmp.jsf, rightclicking the DeptEmp.jsf file, and choosing
Run from the context menu.
When the application starts, click Next
twice to display information for department
30. Figure 2 shows the sample application running in a browser and the result for
department 30.
The departments UI and its command
buttons are located in the unbounded task
flow. The employee detail table and its
buttons are within a bounded task flow.
The Edit Employee button navigates from
the bounded task flow to a subtask flow
showing an edit form.
Note that command buttons with ADFc
in their labels invoke a method activity
for throwing an exception when the business service is being accessed through
the Oracle ADF Binding Layer. Oracle ADF
Controller exceptions are handled by the
Oracle ADF Controller exception handler.
Buttons with ADFm in their labels access
the business service directly through the
Oracle ADF Binding Layer to demonstrate
error handling through the Oracle ADF

39

Model error handler.

To explore the default error handling,
follow these steps in the application running
in your browser:
1. Click ADFc Custom Exceptionbelow
the department datato see the default
error handling in Oracle ADF Controller
unbounded task flows if no exception
handler is set up.
2. Click ADFm Throw Nested Exception
to see how the Oracle ADF Model error
handler, which is configured by default,
handles exceptions in the business
service (and so much more nicely than
when no exception handler is set up).
3. Click Edit Employee to navigate to the edit
form for the currently selected employee
ID, which should be 114 (Den Raphealy).
Change the Email field from DRAPHAELY
to SKING, and click Commit. The error you
see is a unique key constraint validation
thrown by the database. The error propagates from the business service to the
binding layer for handling.
4. Change the value back to DRAPHAELY,
and click Commit.
5. Click ADFm Custom Exception to see a
custom application exception handled
by the Oracle ADF Model error handler.
6. Click ADFc JboException to see how
business service errors propagate to the
Oracle ADF Controller if no error handling is set up.
7. Click Return to Browse View.
Note: All exceptions other than validation and database constraint exceptions in
this sample application are generated by
code in the AppModuleImpl file, located in
the oramag.marapr.thirteen.sample.model
.bc.services package of the Model project.
UNBOUNDED TASK FLOW: ORACLE ADF
CONTROLLER ERROR HANDLING
As you have seen when running the sample,
the display of Oracle ADF Controller errors
is not user-friendly or localized. This is
because no error handler has been set up.
In the following steps, you will configure a
task flow activity as the error handler for the
unbounded task flow.
1. In the Oracle JDeveloper
Application Navigator, expand
UnboundedTaskFlowUtil and select

2.

3.
4.
5.

6.
7.

8.
9.

10.

11.

12.

Web Content -> Page Flows -> adfcconfig. Right-click adfc-config, and
choose Open from the context menu.
The unbounded task flow configuration file contains a method activity
UnboundedTaskFlowErrorHandler
configured as an error handler (indicated
by the exclamation mark overlay icon).
The method activity references the
showAdfcErrorMessageInDialog method
of the AdfcSampleErrorHandlerImpl class
in ADfErrorHandlingUtil to show a dialog
box for displaying controller errors.
Right-click the UnboundedTaskFlowUtil
node, and choose Deploy ->
UnboundedTaskFlowUtilLib from the
context menu to deploy the Oracle ADF
library containing the error handler.
Click Finish (because you are not making
changes to the deployment directory).
In the Application Navigator, select the
ViewController project.
Choose View -> Resource Palette.
In the Resource Palette, create a new file
system connection by clicking the menu
button with the folder icon and choosing
New Connection -> File System from the
menu (as shown in Figure 3).
Name the new connection Unbounded
Task Flow Error Handler.
Click Browse to navigate to
and select the deploy folder
located in the ErrorHandling ->
UnboundedTaskFlowUtil folderin
the directory to which you unzipped the
downloaded sample zip file.
Click Select and then OK.
In the Resource Palette, expand the IDE
Connections panel and then the File
System -> Unbounded Task Flow Error
Handler node.
With the ViewController project selected
in the Application Navigator, right-click
the UnboundedTaskFlowUtilLib.jar file,
displayed in the Resource Palette under
the Unbounded Task Flow Error Handler
node, and choose Add to Project from
the context menu.
Click Add Library in the dialog box
to configure the library for the
ViewController project.
Save your work, and test the application by selecting View Controller ->

Figure 3: Creating a new file system connection

Web Content -> pages -> DeptEmp.jsf,

right-clicking the DeptEmp.jsf file, and
choosing Run from the context menu.
Try the command buttons that have
ADFc in the labels to see the difference
in the behavior.
At any time in Oracle ADF, there is only
one unbounded task flow instance. In cases
in which there are multiple adfc-config.xml
files in the class path for an application, the
Oracle ADF Controller merges them into a
single configuration at runtime.
The Oracle ADF library you just added to
the ViewController project contains an adfcconfig.xml file with a method activity as an
exception handler. At application runtime,
this exception handler is added to the applications unbounded task flow.
Containing all exception handler activity
in the unbounded task flow seems to
handle all controller exceptions in the
sample application well, in that it displays
a user-friendly error message. Still, there
is an issue to fix. When you simulate an
exception in the bounded task flow by
clicking ADFc Custom Exception below
the employee table, the error displays in
the custom dialog box. The error handling,
however, is not in the bounded task flow but
in the unbounded task flow, which means
that the bounded task flow is left in an
unpredictable state, because application
focus now is on the unbounded task flow.
To avoid this and follow Oracle ADF best
practices, you should define error handler
activities in all bounded task flows so problems can be handled locally inside a task
flow. Details on how to configure exception

ORACLE MAGAZINE MARCH/APRIL 2013

40

ORACLE ADF

handler activities for bounded task flows are

in the next section.
BOUNDED TASK FLOW: ORACLE ADF
CONTROLLER ERROR HANDLING
Unlike in unbounded task flows, it is not
enough for bounded task flows to add
an Oracle ADF library with an exception
handler activity to the class path. Instead,
the activity must be configured in each task
flow. To simplify the configuration task, this
hands-on section uses a task flow template
containing the exception handler activity
and references it from the two bounded task
flows in the sample.
1. In the Oracle JDeveloper
Application Navigator, expand the
BoundedTaskFlowUtil project and select
the Web Content -> Page Flows ->
btf-error-handler-template bounded task
flow template file. Right-click the file, and
choose Open from the context menu.
The task flow template contains a
method activityBtfErrorHandlerthat
references the showAdfcError
MessageInDialog method of the
AdfcSampleErrorHandlerImpl class in
the ADfErrorHandlingUtil project to
display controller errors in a dialog box.
2. On the btf-error-handler-template.xml
tab, select the Diagram tab , select the
BtfErrorHandler method activity image,
and click the red exclamation mark
(Mark Exception Handler) in the diagram
toolbar. This configures the method
activity as an exception handler.
3. To deploy the bounded task flow
template with the error handler
activity in the Application Navigator,
right-click the BoundedTaskFlowUtil
project node and choose Deploy ->
BoundedTaskFlowUtilLib from the
context menu. The Oracle ADF library
has been predefined for this sample.
4. Click Finish in the dialog box (because
you are not making changes to the
deployment directory).
5. In the Application Navigator, select the
ViewController project.
6. Choose View -> Resource Palette to
display the Resource Palette panel.
7. In the Resource Palette, expand the IDE
Connection accordion tab and right-click

MARCH/APRIL 2013 ORACLE.COM/ORACLEMAGAZINE

the File System node.

8. Select New File System Connection
from the menu, and name the new
connection Bounded Task Flow
Error Handler.
9. Click Browse to navigate to and select
the deploy folderlocated in the
ErrorHandling -> BoundedTaskFlowUtil
folderin the directory to which you
unzipped the downloaded sample zip file.
10. Click Select and then OK.
11. In the Resource Palette -> IDE
Connections panel, expand the File
System -> Bounded Task Flow Error
Handler node.
12. With the ViewController project selected
in the Application Navigator, rightclick the BoundedTaskFlowUtilLib.jar
filelocated under the Bounded Task
Flow Error Handler node in the Resource
Paletteand choose Add to Project from
the context menu.
13. Click Add Library in the opened dialog
box to add the Oracle ADF library with
the bounded task flow exception handler
for the ViewController project.
14. In the Application Navigator, expand the
ViewController -> Web Content -> Page
Flows -> bounded-tf node.
15. Select the browse-employees-task-flow
bounded task flow, and select View ->
Structure to open the Structure window
(if it is not already open).
16. In the Structure window, expand the
ADF Task Flow node and select the taskflow-definition child node.
17. Select View -> Property Inspector, and
navigate to the Document property
under the Based on Template header.
18. Set the Document property value to
/WEB-INF/btf-error-handler-template
.xml

Note: /WEB-INF/btf-error-handlertemplate.xml is the name of the

template document defined in the
BoundedTaskFlowUtil project. There is
no option yet in Oracle JDeveloper for a
project to browse configured Oracle ADF
libraries for the names of contained documents. Therefore, this configuration is
manual for existing bounded task flows.

If you build a new bounded task flow,

you have the optionin the process of
task flow creationto select a template,
in which case this configuration is automated for you.
19. Edit the Based on Template ID property,
selecting the btf-error-handler-template
entry from the list. (You must click in
the Based on Template ID field for the
select list to appear.) Before configuring
the exception handler on the second
bounded task flow in the sample, run
the application. Select View Controller ->
Web Content -> pages -> DeptEmp.jsf,
right-click DeptEmp.jsf, and choose Run
from the context menu.
20. When the sample application appears
in the browser, click Edit Employee
(below the employee table) to navigate
to the bounded task flow containing the
edit form.
21. In the edit view, click ADFc JboException
and note how the edit form task flow is
abandoned and focus is put back on the
employee bounded task flow. Task flows
with no defined error handling are closed
when an exception occurs and is passed
on to the calling task flow. You can avoid
this by configuring an exception handler
activity in all bounded task flows.
22. Repeat steps 14 through 19 for the editemployee-task-flow bounded task flow
in the ViewController project, and rerun
the sample application.
23. Save your work.
Note: Bounded task flows dont necessarily need to share the same error handler
activity. Instead, each bounded task flow
can have its own error handler routine
defined. Also, there is no rule that errors
must be displayed in a dialog box as demonstrated in this sample application. You
can, for example, configure a router activity
as an error handler to handle exceptions
differently, according to their specific type
or error codes.
CUSTOM ORACLE ADF MODEL
ERROR HANDLER
The Oracle ADF Model error handler is
configured in the Oracle ADF Binding
context and handles errors that occur
when the business service is accessed

41

through the Oracle ADF Binding Layer.

The default implementation class is
DCErrorHandlerImplyouve seen it in
action earlier when running the sample
application and clicking one of the buttons
prefixed with ADFm in the label.
The Oracle ADF Model error handler is
central in Oracle ADF error handling, and by
default it re-raises only exceptions handled
by the controller of the Oracle ADF Faces
view layer. It also, however, removes the
outer exception from bundled exceptions to
avoid displaying duplicate error messages.
In a production environment, there is a lot
more you may want to do with exceptions,
such as suppressing specific exceptions,
changing error messages, or adding logging
and incident reporting.
To address these requirements, you can
customize the Oracle ADF error handler.
(There is only one Oracle ADF Model error
handler active for an Oracle ADF applica-

tion.) The Oracle-hosted online version

of this article at bit.ly/UleuqX includes
instructions on how to customize the Oracle
ADF error handler.
CONCLUSION
This article stepped you through the configuration of a custom error handler activity in
Oracle ADF task flows and the customization
of the default binding error handler. Error
handling is a large knowledge areafollow
up by reading more about it in the product
documentation and blog entries listed in
Next Steps. W

Frank Nimphius is a senior principal product

manager for Oracle JDeveloper and Oracle ADF.
He is a coauthor of Oracle Fusion Developer
Guide: Building Rich Internet Applications with
Oracle ADF Business Components and Oracle
ADF Faces (McGraw-Hill, 2010).

NEXT STEPS
DOWNLOAD
Oracle JDeveloper 11g
bit.ly/LRlg7k
the sample application for this article
bit.ly/10mJLA6
READ
Oracle-hosted online-only
article content
bit.ly/UleuqX
more about error handling
Oracle Fusion Middleware Fusion Developers
Guide for Oracle Application Development
Framework 11g Release 2 (11.1.2.3.0)
bit.ly/V1YWJK
Oracle Fusion Middleware Error Messages
Reference 11g Release 1 (11.1.1)
bit.ly/Vvg1wK
ADF Fail Whale: Handling The Database Is Down
Gracefully, One Size Doesnt Fit All (blog)
bit.ly/ZRB0Nc
JDev ADF: How to Log All Errors to the Database,
One Size Doesnt Fit All (blog)
bit.ly/VvhdAu

UPDATING
DATA ACROSS

THE CLOUD?

WEVE GOT A BETTER WAY!

Change Data Capture for the Cloud
t Supports all major databases across the Cloud
including Oracle, IBM DB2, MS SQL Server, Informix,
MySQL, Sybase, Netezza, Vectorwise, Cloud
systems and more
t Supports Google App Engine Datastore
t Converts data to encrypted le for Cloud transport
t Change Data Capture with log reading
t Continuous, automated updates
t Non-intrusive, low overhead, easy to use
T +1.408.345.4001

www.hitsw.com

FREE PAPER
Tips for Change Data Capture
across Enterprise and Cloud
Download at: http://info.hitsw.com/Oracle20132

[email protected]

Copyright 2013 HiT Software, Inc., A BackOffice Associates, LLC Company. All rights reserved. HiT Software, HiT Software logo, and DBMoto are either trademarks or registered trademarks of HiT Software
and BackOffice Associates, LLC in the United States and other countries. All other trademarks are the property of their respective owners.

ORACLE MAGAZINE MARCH/APRIL 2013