ActiveVOS Designer User’s Guide

Previous | Next

Catching Undeclared and SOAP Faults

In standard fault handling, a fault message is declared as part of a WSDL operation. This declaration is a best practice and is expected behavior for BPEL fault handling. However, best practices do not always exist for Web services, and fault messages may be missing. When a service faults, the process faults with no information about the cause. To improve upon this behavior, ActiveVOS provides fault handling for undeclared faults.

To catch undeclared faults as well as SOAP faults, you can declare your own faults and then use the ActiveVOS fault custom functions to handle non-WSDL faults.

Using the ActiveVOS custom functions, you can prevent a process from terminating and can get access to the following fault information:

• getFaultCode() - Returns the category of the fault
• getFaultString() -Returns a short description related to the fault code
• getFaultDetail() - Returns information about what caused the fault. You can catch a specific Java fault, including the class name, message, and stack trace. As described below in Example 4, implement this feature by using a custom fault name in a catch. Note the required namespace for the qualified custom fault name for a Java fault.
• getSOAPFault() - Returns the entire soap:Fault element (if fault was due to a SOAP invoke that resulted in a fault).

Here are some examples of how to create fault handling of undeclared faults.

Example 1: Add a CatchAll handler for undeclared faults and SOAP faults

1. Add a catchAll to a scope or to the process, as described in Defining Catch and CatchAll Fault Handlers. (Or add the handler as a BPMN boundary event).
2. Add an assign activity as the target activity of the handler.
3. Copy an expression to a process variable using the fault custom functions, as shown in the following example:



4. The copy operation you create would look like the following XQuery example:

Copy From:

<ns1:myFaultInfo xmlns:ns1="urn:faults:undeclared" xmlns:ns2="urn:faults:undeclared:result">

   <ns2:result>

      <ns2:FaultCode>{abx:getFaultCode()}</ns2:FaultCode>

      <ns2:FaultString>{ abx:getFaultString() }</ns2:FaultString>

      <ns2:FaultDetail>{ abx:getFaultDetail() }</ns2:FaultDetail>

      <ns2:SOAPFault>{ abx:getSOAPFault() }</ns2:SOAPFault>

   </ns2:result>

</ns1:myFaultInfo>

Copy To:

myFaultInfo

Example 2: Declare a process variable to add to a catch

1. Add a schema element to a project WSDL. This will be used in a catch or throw fault variable definition. For example:

<xs:element name="undeclaredFaultElement" type="tns:undeclaredFaultType"/>

     <xs:complexType name="undeclaredFaultType">

       <xs:sequence>

         <xs:element name="faultMessage" type="xs:string" />

       </xs:sequence>

    </xs:complexType>

2. Add a catch and use the schema element as a Fault Variable Definition:

Element = ns1:undeclaredFaultElement

3. Add a catch Fault Variable Name, such as myFault
4. Add an assign activity to the catch, and complete it as in Example 1.

Example 3: Declare a process variable to add to a throw activity

1. Add a schema element to a project WSDL, as in Example 2.
2. Add a new process variable, such as myFault, defined as the schema element.
3. Add an Initial Value to the variable as a literal, such as the following example:

<ns1:undeclaredFaultElement xmlns:ns1="urn:faults:undeclared">

   <faultMessage>string</faultMessage>

</ns1:undeclaredFaultElement>

4. Add a throw to the process.
5. Select myFault as the Fault Variable.
6. Create a Custom Fault Name for the throw, such as ns1:myFault.

Example 4: Catch a Java fault by name

1. Add the required namespace to the process, as follows:

aex="http://www.active-endpoints.com/2004/06/bpel/extensions/”

This is the ActiveVOS namespace used for catching system errors.

2. Add a catch to the process.
3. Define a custom Fault Name as follows:
• Prefix of aex or some other prefix that points to the required namespace shown in Step 1.
• Unqualified class name of a Java exception. The name is the NCName of the class, without the package details. For example: UnknownHostException

Example: aex:UnknownHostException

4. Complete the catch by adding an assign. See Example 1.

For example, if the java.net.UnknownHostException is thrown by an invoke due to an invalid URL, the fault detail element will appear as follows:

<ext:UnknownHostException xmlns:ext="http://www.active-endpoints.com/2004/06/bpel/extensions/" 

 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> 

  <Class xmlns="http://www.active-endpoints.com/2004/06/bpel/extensions/">java.net.UnknownHostException</Class> 

           <Message xmlns="http://www.active-endpoints.com/2004/06/bpel/extensions/">unknown-host</Message> 

           <StackTrace xmlns="http://www.active-endpoints.com/2004/06/bpel/extensions/">java.net.UnknownHostException: unknown-host

 at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:177)

 at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:366)

 at java.net.Socket.connect(Socket.java:525)

 at java.net.Socket.connect(Socket.java:475)

 at java.net.Socket.<init>(Socket.java:372)

 at java.net.Socket.<init>(Socket.java:246)

 at org.apache.commons.httpclient.protocol.DefaultProtocolSocketFactory.createSocket(DefaultProtocolSocketFactory.java:80)

 at org.apache.commons.httpclient.protocol.DefaultProtocolSocketFactory.createSocket(DefaultProtocolSocketFactory.java:122)

 at org.apache.commons.httpclient.HttpConnection.open(HttpConnection.java:707)

 at org.apache.commons.httpclient.MultiThreadedHttpConnectionManager$HttpConnectionAdapter.open(MultiThreadedHttpConnectionManager.java:1361)

 at org.apache.commons.httpclient.HttpMethodDirector.executeWithRetry(HttpMethodDirector.java:387)

 at org.apache.commons.httpclient.HttpMethodDirector.executeMethod(HttpMethodDirector.java:171)

 at org.apache.commons.httpclient.HttpClient.executeMethod(HttpClient.java:397)

 at org.apache.commons.httpclient.HttpClient.executeMethod(HttpClient.java:323)

 at org.activebpel.rt.metro.tube.AeHttpTransportTube.process(AeHttpTransportTube.java:214)

 at org.activebpel.rt.metro.tube.AeHttpTransportTube.processRequest(AeHttpTransportTube.java:162)

 at com.sun.xml.ws.transport.DeferredTransportPipe.processRequest(DeferredTransportPipe.java:116)

 at com.sun.xml.ws.api.pipe.Fiber.__doRun(Fiber.java:598)

 at com.sun.xml.ws.api.pipe.Fiber._doRun(Fiber.java:557)

 at com.sun.xml.ws.api.pipe.Fiber.doRun(Fiber.java:542)

 at com.sun.xml.ws.api.pipe.Fiber.runSync(Fiber.java:439)

 at com.sun.xml.ws.api.pipe.helper.AbstractTubeImpl.process(AbstractTubeImpl.java:112)

 at com.sun.xml.xwss.XWSSClientPipe.process(XWSSClientPipe.java:160)

 at com.sun.xml.ws.api.pipe.helper.PipeAdapter.processRequest(PipeAdapter.java:115)

 at com.sun.xml.ws.api.pipe.Fiber.__doRun(Fiber.java:598)

 at com.sun.xml.ws.api.pipe.Fiber._doRun(Fiber.java:557)

 at com.sun.xml.ws.api.pipe.Fiber.doRun(Fiber.java:542)

 at com.sun.xml.ws.api.pipe.Fiber.runSync(Fiber.java:439)

 at com.sun.xml.ws.client.Stub.process(Stub.java:222)

 at com.sun.xml.ws.client.dispatch.DispatchImpl.doInvoke(DispatchImpl.java:180)

 at com.sun.xml.ws.client.dispatch.DispatchImpl.invoke(DispatchImpl.java:206)

 at org.activebpel.rt.metro.jaxws.AeJAXWSClient.invoke(AeJAXWSClient.java:113)

 at org.activebpel.rt.metro.wsio.AeMetroInvoker.doInvoke(AeMetroInvoker.java:135)

 at org.activebpel.rt.metro.wsio.AeMetroInvoker.invoke(AeMetroInvoker.java:73)

 at org.activebpel.rt.metro.wsio.AeMetroInvokeHandler.handleInvoke(AeMetroInvokeHandler.java:72)

 at org.activebpel.rt.bpel.server.engine.invoke.AeInvoker.handleInvoke(AeInvoker.java:193)

 at org.activebpel.rt.bpel.server.engine.AeInMemoryQueueManager$1.run(AeInMemoryQueueManager.java:138)

 at org.activebpel.work.AeDelegatingWork.run(AeDelegatingWork.java:62)

 at org.activebpel.work.AeProcessWorkManager$AeProcessWork.run(AeProcessWorkManager.java:254)

 at org.activebpel.work.AeDelegatingWork.run(AeDelegatingWork.java:62)

 at org.activebpel.work.AeExceptionReportingWork.run(AeExceptionReportingWork.java:58)

 at org.activebpel.work.AeWorkerThread.run(AeWorkerThread.java:142)

</StackTrace> 

        </ext:UnknownHostException> 

Copyright (c) 2004-2011 Active Endpoints, Inc.