12c SOA - Oracle Mediator part4 - Error Handling

• Mediator provides sophisticated error handling capabilities that enable you to configure a Mediator service component for error occurrences and corresponding corrective actions. 
• Error handling enables a Mediator to handle errors that occur during the processing of messages and also the exceptions returned by outside web services. 
• You can handle both business faults and system faults with Mediator.

Business faults are application-specific and are explicitly defined in the service WSDL file. You can handle business faults by defining the fault handlers in Oracle JDeveloper at design time.
System faults occur because of some problem in the underlying system such as a network not being available. Mediator provides fault policy-based error handling for system faults. Fault policies enable you to handle errors automatically or through human intervention.

Mediator fault policy-based error handling consists of the following three components:
• Fault policies
• Fault bindings
• Error groups

Fault Policies: 

A fault policy defines error conditions and corresponding actions. Fault policies are defined in the fault-policies.xml file.
Fault policies for sequential routing rules are handled differently than for parallel routing rules. Due to the single threading of sequential routing rules, only three actions (Abort, Rethrow, and Java) are supported for handling errors, and the specified actions areexecuted immediately in the caller's thread.

Fault policies are not supported for the following:
• Callback execution failures
• Fault Handler action failures
• Resequencer failures

Fault Bindings:
Fault bindings associate fault policies with composites or components, and are defined
in the fault-bindings.xml file.

Fault policies can be created at the following levels:
Composite: You can define one fault policy for all Mediator components in a composite.
<composite faultPolicy="ConnectionFaults"/>
Component: You can define a fault policy exclusively for a Mediator service component. A component-level fault policy overrides the composite-level fault policy.
<component faultPolicy="ConnectionFaults">
<name>Component1</name>
<name>Component2</name>
</component>
Reference: You can define a fault policy for the references of a Mediator component.
<reference faultPolicy="policy1">
<name>DBAdapter3</name>
</reference>

Note:

• The level of precedence for fault policies is Reference -> Component -> Composite.
• Human intervention is the default action for errors that do not have a fault policy defined.

Error Groups in Mediator:
You can specify an action for an error type or error group while defining the conditions in a fault policy. medns:mediatorFault indicates that the error is a Mediator error, whereas medns:TYPE_FATAL_MESH refers to an error group. An error group consists of one or more child error types. TYPE_ALL is an error group that contains all Mediator errors.

Error handling with Fault policy and Fault binding:

User case 1: Notify an email to the desired recipient when there is any error in the mediator.
Right click on project⇾New⇾From Gallery

Search with Policy and select Fault Policy Documnent

Select the fault. here I selected mediator faults,

Select the default action. here I selected the default-termination

Creates condition to have a TYPE ALL group error.

Open the Expression builder and put contains($fault.mediatorErrorCode, "TYPE_ALL")

Create Alert

Here we are selecting email.

Provide the email properties like To and CC field. Property set is not mandatory for email.

Select the created email alert.

Go the composite flow and click the Edit Composite Fault Polices option

Bind the policy to the composite or component or reference section as required.

Test and receive the error over mail.

fault-policies.xml
<?xml version="1.0" encoding="UTF-8"?>
<faultPolicies
    xmlns="http://schemas.oracle.com/bpel/faultpolicy"
    xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
    xmlns:bpel1="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
    xmlns:bpel2="http://docs.oasis-open.org/wsbpel/2.0/process/executable"
    xmlns:medns="http://schemas.oracle.com/mediator/faults"
    xmlns:rjm="http://schemas.oracle.com/sca/rejectedmessages">

    <faultPolicy id="policySet">
        <Conditions>
            <faultName name="medns:mediatorFault" xmlns:medns="http://schemas.oracle.com/mediator/faults"
                       description="All Mediator faults">
                <condition>
                    <test>contains($fault.mediatorErrorCode, "TYPE_ALL")</test>
                    <action ref="default-termination"/>
                    <alert ref="emailProperties"/>
                </condition>
                <condition>
                    <action ref="default-termination"/>
                </condition>
            </faultName>
        </Conditions>
        <Alerts>
            <Alert id="emailProperties">
                <email>
                    <To>test1@test.com</To>
                    <CC></CC>
                </email>
            </Alert>
        </Alerts>
        <Actions>
            <Action id="default-termination">
                <abort/>
            </Action>
            <Action id="default-human">
                <humanIntervention/>
            </Action>
            <Action id="default-java">
                <javaAction className="oracle.integration.platform.faultpolicy.IFaultRecoveryJavaClass" defaultAction="default-termination"/>
            </Action>
            <Action id="default-replay">
                <replayScope/>
            </Action>
            <Action id="default-rethrow">
                <rethrowFault/>
            </Action>
            <Action id="default-ws">
                <invokeWS  uri="WebServiceURI"/><!-- format - <Absolute wsdl path>|service name|port name -->
            </Action>
            <Action id="default-enqueue">
                <enqueue uri="QueueURI"/> <!-- QueueURI format  - jdbc:oracle:thin:@<host>:<port>:<sid>#<un>/<pw>#queue -->
            </Action>
            <Action id="default-file">
                <fileAction>
                    <location>FOLDER_LOCATION</location>
                    <fileName>FILE_NAME</fileName><!-- FILE_NAME will support %ID%(rejected message instance id) or %TIMESTAMP% wildcards -->
                </fileAction>
            </Action>
            <Action id="default-retry">
                <retry>
                    <retryCount>3</retryCount>
                    <retryInterval>2</retryInterval>
                </retry>
            </Action>
        </Actions>
        <Properties>
        </Properties>
    </faultPolicy>
</faultPolicies>

Use Case2 : When there is any mediator error, Using fault policy and fault binding, publish the error details into a JMS Queue.
Click here 12c-soa-oracle-mediator-part5-error-handling-usecase2.html

12c SOA - Oracle Mediator part3 - Echo

• Mediator can echo source messages back to the initial caller without routing the message to another target.
• Echo option is used when we don’t have target service available ,we expose Mediator functionality as target service and Echo a response to initial caller . Suppose we are doing query from target service but that target service is down due to some reason , in this case to test our Mediator we use Echo, we will create sample query response message and pass that to calling service as a Echo.
• This is typically used in use cases where a certain message has to be enriched, or some filtering to be done, etc.

I will show you how we can create one sample Mediator project to show Echo functionality.

Implementation:
Create one project and add Mediator to it. Name it as “MediatorEcho” and made it as Synchronous.

 Note: we can also use custom xsd for the echo mediator.

 Go to Mediator mplan file and open one static routing rule.

 Choose “Echo Reply” from available options.

 Do the required mapping and map all the fields which we want to send to initial caller as Echo.

 Deploy and test.

12c SOA - Oracle Mediator part2 - Resequencer

"The Resequencer in Mediator rearranges a stream of related but out-of-sequence messages into a sequential order. When incoming messages arrive, they may be in a random order. The resequencer orders the messages based on sequential or chronological information, and then sends the messages to the target services in an orderly manner. The sequencing is performed based on the sequencing strategy selected."

Mediator can resequence the incoming messages in a user-specified order. This implementation enables you to specify three types of resequencing orders:

• Standard Resequencer
• FIFO Resequencer
• Best Effort Resequencer

Mediator Processing without Resequencing:

Standard – Processes transactions contiguously within a Group, based on a defined Group and Sequence ID.  Groups are processed in parallel.

FIFO (First-In-First-Out) – Processes transactions based on the time they are received by the Resequencer.

Best Effort – Processes transactions based on Sequence ID in increasing order at predefined intervals. Best Effort transaction processing is not always contiguous.

Implementation using Standard type:

• When using the standard resequencer in Mediator, you must always specify a group XPath expression and a sequence ID XPath expression. These specify where theMediator resequencer can find the group and the sequence ID in the messages. 
• You must also supply the sequence numbering in terms of the start sequence ID and the sequence ID incremental delta. This numbering is used to form each group. 
• In addition to the group, sequence ID, and increment properties, you can also specify a timeout period, in seconds, to wait for the expected messages.

The Mediator standard resequencer holds back messages in the Mediator resequencer database until it can produce the right sequence for different groups. This situation means that if for a given group, the message with a particular sequence ID does not arrive within the timeout period, the subsequent messages for that group are held back forever. In such a case, you must manually unlock the group through Oracle Enterprise Manager Fusion Middleware Control and go to the next available message,
skipping the pending message.

Schema used:

<?xml version="1.0" encoding="windows-1252" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.emp.poc" targetNamespace="http://www.emp.poc"

            elementFormDefault="qualified">

  <xsd:element name="process">

    <xsd:complexType>

      <xsd:sequence>

        <xsd:element name="empID" type="xsd:string"/>

        <xsd:element name="empType" type="xsd:string"/>

        <xsd:element name="empName" type="xsd:string"/>

      </xsd:sequence>

    </xsd:complexType>

  </xsd:element>

</xsd:schema>

Create a SOA project and above schema file and drag and drop mediator

 Use One way Interface and use the schema.

 Choose Re-sequence level as Component.

 Choose Resequence mode as Standard.

 Select the Xpaths for Group and ID. Here we use empType as Group and empID and ID.

For the Resequence Level we can select ‘operations’ or ‘component’.

For Mediator components which only have 1 operation it doesn’t matter which one we select. For a Mediator component which consists of more then 1 operation and selecting the ‘component’ option means resequencing is applied to all operations in it. For this test we selected the ‘component’ option and used the ‘Standard’ mode.

About options to configure the re-sequencer.

Group – xpath expression to the field in the payload which the resequencer will use to group our incoming messages

ID – xpath expression to the field which will uniquely identify our message

Start – Start value of the ID in the incoming message

Increment – Value which will be used for the increment of the id field in the upcoming messages

Timeout – Time to wait before a following expected message arrives at the Mediator component

 Create a file adapter to write the files in a local directory.

 Now wire it

 Do the transformation

 Deploy to the server and test

test with ID= 1 and Group = TMP

 test with ID= 3 and Group = TMP

 Observed that the transaction (id=3) went to running state and waiting for the ID=2 which is not processed yet.

 Test with ID=2 and group=TMP

 Now 1st process ID=2 and then ID=3.

Implementation using FIFO Resequencer:

• The FIFO resequencer supports a standard first in, first out (FIFO) pattern.The FIFO resequencer receives a stream of messages that are in order and processes them in sequence for each group based on the arrival time of the messages.
• When using the FIFO resequencer, you must always specify a group XPath expression. However, you do not need to specify a sequence ID because the messages are processed according to the time of arrival to the Mediator service component that isconfigured for FIFO resequencing. The group XPath expression specifies where the FIFO resequencer should find the group information in the message to group the messages. No further configuration is needed for a FIFO pattern.

Test with ID=1 and group=PERM

 Test with ID=3 and group=PERM

 Test with ID=2 and group=PERM

 Its processed 1,3 and 2 in FIFO manner.

Implementation using Best Effort Resequencer:

• The best effort pattern is useful for applications that produce a large number of messages in a short period and cannot provide information to the resequencer about the identifier to use for sequencing. Typically, the identifier used for sequencing in Resequencing Order such scenarios is of a dateTime type or numeric type. Using the dateTime field as the sequence ID XPath enables you to control the sequencing. The messages are expected to be sent in sequence by the applications, thus the date and time the messages are sent can be used for sequencing. The Mediator makes the best effort to ensure that the messages are delivered in sequence.

• The best effort resequencer can reorder messages based on no knowledge about the increment of the sequence ID. This situation means that unlike the standard resequencer, you do not need to define the increment of the sequence ID for the best effort resequencer in advance. When the messages are processed, they are processed in sequence based on the specified sequence ID and the messages that have arrived, whether a true sequence is received. The sequence IDs are either numeric or dateTime. Therefore, sequencing occurs on the numeric order or the dateTime order of the sequence IDs.

When using the best effort resequencer, you must specify a group XPath expression, a sequence ID XPath expression, and the data type of the sequence ID (numeric or dateTime). These specify where the resequencer should find the group and the sequence ID in the messages and how to handle the sequence ID. In addition, you must specify either a maximum number of rows to select for each resequencing batch or a time window during which the messages included in one batch arrive. Unlike the standard resequencer, the best effort resequencer has no knowledge about how the sequence is built. No further information

Example of Best Effort Resequencing Based on Maximum Rows
In this example, msgX(Y,Z) indicates that the message arrives as message number X to the Mediator service component and the message contains sequenceID Y and group Z.

Group C 
msg03(1,c)
msg06(2,c)
msg10(3,c)
msg12(4,c)

Sequenced Messages
msg12(4,c),msg10(3,c),msg06(2,c),msg03(1,c)

Example of Best Effort Resequencing Based on a Time Window
In this example, the time window is 10 minutes, the buffer is 10% (one minute), and msgX(Y) indicates that the message arrives as message number X to the Mediator service component and the message contains the sequence ID Y. The first message arrives at 2:00:00, which starts the time window. The time window lasts until 2:10:00, but with the addition of the buffer time, messages that arrived until 2:11:00 are processed.

Group C
Message/Time
msg01(04)/2:00:00
msg02(05)/2:00:20
msg03(01)/2:00:30
msg04(03)/2:00:50
msg05(07)/2:04:20
msg06(02)/2:04:45
msg07(13)/2:05:10
msg08(08)/2:05:40
msg09(06)/2:08:40
msg10(12)/2:09:20
msg11(10)/2:10:30
msg12(09)/2:10:40
msg13(14)/2:10:50
msg14(11)/2:13:00

Sequenced Messages
msg03(01), msg06(02), msg04(03), msg01(04), msg02(05),
msg09(06), msg05(07), msg08(08), msg12(09), msg11(10),
msg10(12), msg07(13)

Note:
In the above example, the resequencer identified the maximum sequence ID for the time window as 13 (from message 7). Message 13 arrived within the buffer time, but has a sequence ID of 14. It is not processed with the original group, but instead begins a new time window at its arrival time of 2:10:50. Message 14 arrived too late and is included in the second time window.