OSB Error Handler Tutorial

Error handling in OSB is fairly straight forward but can seem more complex than needed.  The following exercises will provide hands-on examples of how error handlers function in OSB.  I have also included a sample project which makes it very easy to try different scenarios that can help broaden your understanding of OSB Error Handling.  These examples are meant to give some guidance but please try different scenarios and if there is something you are curious about add it to one of the proxy services and see what OSB does.

Before we start with the hands-on exercises below is a quick overview of the key points in OSB Error Handling. 

OSB Error Handling Overview

Error handling can be configured at 4 different areas in and OSB Proxy Service.

1. Proxy Service
2. Route Node
3. Pipeline
4. Stage Node

If an error is not handled in any of these areas then it will be caught in the System error handler.

An error will be handled by the inner-most encompassing error handler.  In other words, if there is no error handler configured at the level the error occurred then the error will be processed by the next level error handler.  Below is an outline of how the error handlers are nested.

Stage Node -> Pipeline -> Proxy Service -> System Error Handler

Route Node ->  Proxy Service -> System Error Handler

Choosing an error handler action

An Error Handler is not considered completely configured until it has a Resume or Reply Action configured.  If an error handler is missing one of these actions then the other steps in the error handler will be completed but the error will be bubbled up to the next level error handler.

Reply – Will immediately reply back to the calling process with an error response and all further message processing stops. 

Resume – Message flow process will continue as if no error occurred.   The processing will continure after the node or stage that the error handler is configure in.  

Configuring Error Handlers

Error handlers are just another pipeline and can be configured like any other pipeline.  You may use an assign action, publish action…. Etc.

In the error handler a new context variable is available ($fault).  The $fault context variable contains information about any error that occurs during message flow processing and is populated before the error handler is invoked.

For more information on the contents of the $fault variable see  OSB Context Variables

Error Handler Exercises

The following exercises are simple and are meant to demonstrate how error handlers behave in OSB.  Specifically we are going to focus on how error handlers are nested and the behavior of OSB when there are no error handlers. 

To complete these exercises please import the Error_Handler_Demo project.

You can download the project at the following link.

https://docs.google.com/file/d/0B5g0v_BbuvHUV05NaVFOUWxFamM/edit

The Error_Handler_Demo project consists of 3 proxy services.

1)      ValidateID – This proxy service will look at the value of the ID passed in. 

If the ID is <= 5, then it will return a status of “Success” and reply with Success.

If the ID is between 6 and 10, it will return a status of “BusinessFault” and reply with Fault.   

If the ID is between 11 and 20 it will return a status of “TechnicalFault” and reply with Fault.

2)      ErrorHandlerDemoImpl – This proxy service will call the ValidateID proxy service.  We primarily will use this service to demonstrate how OSB handles errors that are returned from a child process.

3)      ErrorHandlerDemo – This proxy service will call the ErrorHandlerDemoImpl proxy service.  This service will be used to show how errors are handled when the error is thrown from a nested service.

ErrorHandlerDemoImpl Service

We will start with calling the ErrorHandlerDemoImpl service directly to demonstrate how it will handle errors returned from the ValidateID service.

For these examples remember that error handler order of execution is as follows when a route node is involved.

Route Node ->  Proxy Service -> System Error Handler

No Error Handler

In the following exercise we will run through several requests to show how the service will behave with no configured error handlers.

1)      Call the ErrorHandlerDemoImpl service and pass in an ID of 2.

§  Based on this ID we would expect a status value of Success to be returned in the response message. Since there were no faults, it will process as expected even though we do not have any error handlers defined.

  

2)      Call the ErrorHandlerDemoImpl service and pass in an ID of 8.

§  Based on this ID we would expect a status of BusinessFault to be returned in the response message.  Unfortunately no status gets returned.  Instead you see a soap fault with a faultstring of “BEA-380000”.   

§  This is because we do not have any error handlers configured.  When the ValidateID service returns a failure it automatically gets processed through the system error handler.  If you look at the Invocation Trace of your test call, you will see that the ValidateID service returns the correct status in the body.  It also returns a response-code of 1.  You can see this in the $outbound context variable.  We are not seeing these in the response because any unhandled faults will be processed through the system error handler and a SOAP fault will be returned.

Proxy Service Error Handler

We will now add a Proxy Service Error Handler to see how it changes the services behavior.

          1)      Add an error handler at the proxy service level.

a.       For detailed instructions on how to do this visit the following link. http://docs.oracle.com/cd/E14571_01/doc.1111/e15867/proxy_errors.htm

b.      In the error handler add a Reply and configure it to Reply With Failure.  Remember the error handler will not be considered completely configured unless it has a Reply or Resume node.

          2)      Call the ErrorHandlerDemoImpl and pass in an ID of 8.

§  Based on this value we would expect to see a response message with a status of BusinessFault returned.   This is because we now have now configured an error handler that will handle the error returned from the ValidateID service and the correct response message should be passed on.

          3)      Try passing in different values for IDs to see how the service behaves.

Route Node Error Handler

Let’s see what happens when we add a route node error handler to our proxy service.

          1)      Add a Route Node Error Handler to the ErrorHandlerDemoImpl proxy service.

a.       For details on how to do this see the following link http://docs.oracle.com/cd/E14571_01/doc.1111/e15867/proxy_errors.htm#autoId4

b.      In your Route Node Error Handler add a Reply which is configured to Reply With Failure.

          2)      Test ErrorHandlerDemoImpl with an ID of 12.

a.       As expected a response message with a  status of TechnicalFault gets returned.  Also note how the error is processed through the Route Node Error Handler instead of the Service Error Handler.

ErrorHandlerDemo Service

Now that we have the error handlers configured in the ErrorHandlerDemoImpl process, let’s look to see how that error information will get propagated to a calling service.  

For these examples remember that error handler order of execution is as follows when a stage node is involved.

Stage Node -> Pipeline -> Proxy Service -> System Error Handler

No Error Handler

The ErrorHandlerDemo proxy service does not have any error handlers defined.

Note:  Remember that the ErrorHandlerDemo service is configure to call the ErrorHandlerDemoImpl service using a Service Callout.

1)      Try calling the ErrorHandlerDemo service with an ID of 10.   When we call the ErrorHandlerDemoImpl process with this value it will return a response message with a status of “Technical Fault”.  This is something that we tested in the previous exercise. The ErrorHandlerDemo service is still going to return a SOAP fault not the correct response message with a status of TechnicalFault.  Since we do not have any error handlers defined the message will be handled by the system error handler which as we saw in our previous exercise will return a SOAP fault.

Proxy Service Error Handler

          1)      In the ErrorHandlerDemo proxy service, add a Proxy Service Error Handler.

          2)      Execute ErrorHandlerDemo service and pass in an ID value of 11.

a.       Based on our previous exercises we would now expect the service to return a response message that contains a status of TechnicalFault and this holds true in this example.  Also if you look in the invocation trace, you will see that the error is getting processed through the service handler.

Pipeline Error Handler

          1)      Add an error handler on the Request pipeline in the ErrorHandlerDemo service.

a.       For detailed steps on how to add this error handler, see the following link

http://docs.oracle.com/cd/E14571_01/doc.1111/e15867/proxy_errors.htm#autoId2

          2)      Execute the ErrorHandlerDemo service and pass in an ID value of 15.

a.       Once again we will see that there is a response message that contains a status of TechnicalFault.  The only thing that is different with this example is that the error is now being handled by the Pipeline Error Handler instead of the System Error Handler.

Stage Node Error Handler

For our last example, we will add a Stage Node Error Handler to demonstrate that it will process the error before the Pipeline or Service Error Handler.

          1)      Add an error handler on the Stage Node in the ErrorHandlerDemo service which calls the    ErrorHandlerDemoImpl service.

a.       For detailed steps on how to add this error handler, see the following link

http://docs.oracle.com/cd/E14571_01/doc.1111/e15867/proxy_errors.htm#autoId3

          2)      Execute the ErrorHandlerDemo service and pass in an ID value of 11.

a.       The response message should contain a status of TechnicalFault and the error will be processed through the Stage Node Error Handler.