In 11g Fault Policies were added so that you could easy intervene when a (SOAP/BPEL) fault was thrown. But you could only create them in source mode, there was no graphical editor. With the release of SOA Suite 12c a new visual editor for creating Fault Policies is added to JDeveloper. With the Fault Policy Editor you can now Design and Edit Fault Policies. Besides the already existed functionality a lot of new features are added.
To start open/add a existing SOA project (as part of SOA application) and create a new Fault Policy document. Right-click on the SOA project and select option New -> From Gallery. From the gallery select SOA-Tier -> Faults -> Fault Policy Document to create new policy file.
The editor will open with a clean policy document. A policy document can have more then one policy, so faults can be grouped i.g. a policy for system faults and a policy for service faults. For every type of fault you can create a fault handler and for each handler you can select one or more actions. When adding more the one actions you can use a XPath expression to select a filter. With the editor you can also create alerts, property sets and new (custom) actions. Shortly, we will look into the details of the editor.
Lets start by creating two fault policies, one for system fault and one more service faults. You can add fault policies by clicking on the + icon and remove a fault policy by clicking on the X icon when having that policy selected. Give the Fault Policy a name that covers the containing Fault Handlers.
For every type of fault you can create a fault handler. Select for the first fault the Fault Name that you want to create the Fault Handler for. Fault are categorized in System Faults and Service Faults. Under System Fault you can select between bindingFault, mediatorFault and remoteFault and under Service Faults you can find faults defined in one of the WSDLs the composites uses. If there ain’t any this category is not shown. If you want an other Fault Handler just click on the + icon at right side.
You can select a default action (default is termination) for the list of available actions. If you have created your own action you can also select that one. Some actions may not be shown if there are not applicant to the fault type. For instance a System Fault can’t be redirected to a WS or JMS queue and a
You can add multiple actions to a Fault Handler and use contextual if/then/default to select the action to execute.
You can also assign an alert to an action. With this you can send an alert through email, JMS or write alert to a log file. You must first create a Alert to be able to assign one, but we will look at the creation of Alerts later.
Alerts, Actions and Properties for custom Interactions
With the editor you can also create and edit alerts, property sets and new (custom) actions per Policy. Alerts can be used to send a message to a email address, a JMS queue or write the message to log. With property sets you can create constants that can be used to configure alerts and actions. Actions control what to do when a Fault occurs. Let’s start with explaining actions.
Actions control what to do when a Fault occurs
When creating a new Fault Policies document a set of default actions is created. These default actions show the types that are no support and can be altered to your own liking. You can also create your own actions and delete not used actions.
|Abort||Terminates the entire business flow.|
|Human Intervention||Causes the current activity to stop processing. Human intervention from Oracle Enterprise Manager Fusion Middleware Control is required to handle the fault.|
|Replay Scope||Replay the scope the Fault occured in.|
|Rethrow Fault||Sends the fault to the BPEL fault handlers (catch activities in scope activities).
If none are available, the fault is sent up.
|Retry||Provides the following options for retrying the activity:
- Retry a specified number of times.
- Provide a delay between retries (in seconds).
- Increase the interval with an exponential back off.
- Chain to a retry failure action if retry N times fails.
|Java Action||Enables you to execute an external Java class.|
|Invoke WS (new in 12c)||Handles a rejected message by calling a web service (uses a Oracle defined schema).|
|Enqueue (new in 12c)||Enqueues a rejected message to a Queue (AQ) as a JMS message with the appropriate context and payload.|
|File Action (new in 12c)||Creates an error handler for messages by storing a rejected message in a file.|
The Abort, Human Intervention, Replay Scope and Rethrow Fault actions enable you to change the default reference to the action and for these actions you can only set a name. These actions were also available in SAO Suite 11g.
The Java Action enables you to execute an external Java class. Just like in 11g your Java class is based on the IFaultRecoveryJavaClass interface. With this class you can do what ever you like with the rejected message. To select the Java class when editing/creating the Java action it should be in the classpath of JDeveloper.
When you define a Property Set and assign it to the Java action the property values can be accessed. For this action you can also select a default action to execute after calling the Java class or you can define Return Values to override the default action. Each value is assigned to an action that should be executed when returned by the Java class.
Invoke WebService (WS) Action
With this action a rejected message can be handled by calling a Web Service. If you choose to use a Web Service to handle these errors, you should implement a predefined WSDL interface implemented by the target service. The WSDL Interface for the Web Service handler must have one port type, only one input operation, and a schema for the input message.
<!-- format - <Absolute wsdl path>|service name|port name -->
With this action you can enqueue a rejected message to a Queue as a JMS message with the appropriate context and payload, however not a JMS queue, at this moment you can only do this task with the AQ adapter. The type of the AQ should be JMS to successfully enqueue the message.
<!-- QueueURI format - jdbc:oracle:thin:@<host>:<port>:<sid>#<un>/<pw>#queue -->
With this action you create an error handler for messages by storing a rejected message in a file. You can store the payload with the proper context. When creating the File Action the location needs to exist on your local machine. If your deployment environment is Linux and your development environment is Windows you need to use Linux paths i.g. c:\Temp\ = \Temp\.
\Temp\ RejectedMessage_%ID% <!-- FILE_NAME will support %ID%(rejected message instance id) or %TIMESTAMP% wildcards -->
This action is still the same as in 11g, but I just wanted to share the new dialog.
3 2 <!--exponentialBackoff/-->
Property Sets can be used for custom Java Actions, to pass through properties that can be used in the Java code, but also with Alerts i.g. logging extra properties/constants (LOG alert). You can add
localhost 110 emailuser welkom2014 true
A new addition in 12c are the Alerts. There are three types of Alerts; Log, Email and JMS. Alerts can be attached to Fault Handler actions and are executed when the action is triggered.
$fault.code/code = "HTTP/404" ...
With this alert you can write a alert to the managed server log when a fault occurs. You can choose which Logger class to use, by default the java.util.logging.Logger is used, if a Property Set should be logged and you can add Supplementary attributes that a logged when a fault occurs.
This alert enables you to specify the users to receive an email alert when a fault occurs. A Property Set can also be added to the email when a fault occurs.
This action enables you to use JMS queues for sending alerts when a fault occurs. A Property Set is needed to connect to the correct JMS Queue. To configure the right JMS properties you can use the “Create Required Properties” wizard. You can also add optional JMS Headers.
FaultAlert ... jms/testfwk/TestFwkQueue eis/wls/Queue
Add Fault Policies to Fault Bindings
Now that the Fault Policies are created they can be coupled to Fault Bindings. A policy can be coupled to a Composite, Components, Reference and Service Binding. To create/edit the Fault Bindings click on the “Edit Composite Fault Policies” icon.
The Composite Fault Policies opens. In this dialog window you can choose the Fault Policies document to use (if one is located in SOA project then this one is automatically selected). With the selected Fault Policies document you can assign the Policies of this document to the Composite, the Components and Service & Reference bindings.
This concludes this post. In an upcoming post I will actually go through a working end-to-end demo of the new Actions and Alerts.