Modeling Message Flow in AquaLogic Service Bus

In AquaLogic Service Bus, the Message Flow defines the implementation of a proxy service. You configure AquaLogic Service Bus proxy services in the AquaLogic Service Bus Console, which is described in Using the AquaLogic Service Bus Console. This section presents guidelines for modeling and designing message flows. It contains the following topics:

About AquaLogic Service Bus Message Flow

A message flow consists of the pipelines, branch nodes, and route nodes that together define the implementation of an AquaLogic Service Bus proxy service. A proxy service is an AquaLogic Service Bus definition of an intermediary Web Service that is hosted locally on AquaLogic Service Bus. Using the AquaLogic Service Bus Console, you can configure the logic for the manipulation of messages in proxy service message flow definitions. This logic includes such activities as transformation, publishing, and reporting—the logic is configured in individual actions within the message flow.

The following figure shows a high level view of the components of the message flow definition.

Building a Message Flow

Any component can be at the root of a message flow. (For a description of the components, see Table 2-1, Message Flow Components, on page 2-4). One of the simplest of message flow designs is to have only a route node representing the entire flow. No restrictions exist on what two components you can chain together to create a message flow. For example, two pipeline pair nodes can be linked together without a branch node in between. In the case of branch nodes, each branch node can start with a different element. One branch can terminate with a route node, another can be followed by a pipeline pair, and yet another may have no descendant. In the latter case, a branch with no descendants means that at run time, when this branch is executed, response processing begins immediately. However, in general a message flow is likely to be designed in one of the following forms:

A message flow is constructed by linking together instances of the top-level components described in the following table. Subsequent sections in this topic describe the node types in more detail.

Node Type

Summary

Pipeline Pair

See Pipelines.

A pipeline pair combines a single request and a single response pipeline into one top-level element. A pipeline pair node can have only one direct descendant in the message flow. During request processing, only the request pipeline is executed when AquaLogic Service Bus processes a pipeline pair node. The execution path is reversed when AquaLogic Service Bus processes the response pipeline.

For an example of a simple pipeline pair node, see Figure 2-3.

To learn how to configure a pipeline pair node, see “Adding a Pipeline Pair Node” in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

Branch

See Branching in Message Flows.

A branch node allows processing to proceed along exactly one of several possible paths. Branching is driven by an XPath-based switch table. Each branch in the table specifies a condition (for example, <500) that is evaluated in order down the message flow against a single XPath expression (for example, ./ns: PurchaseOrder/ns:totalCost on $body). Whichever condition is satisfied first determines which branch is followed. If no branch condition is satisfied, then the default branch is followed. A branch node may have several descendants in the message flow: one for each branch, including the default branch.

Note:

It is highly recommended that you define a default branch whenever your message flow involves conditional branching.

To learn how to add a branch node, see “Adding a Conditional Branch Node” in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

For information about working with the message context variables to design conditions, see Message Context.

Route

A route node is used to perform request/response communication with another service. It represents the boundary between request and response processing for the proxy service. When the route node dispatches a request message, the request processing is considered complete. When the route node receives a response message, the response processing begins. The route node supports conditional routing as well as request and response transformations.

Because a route node represents the boundary between request and response processing, it cannot have any descendants in the message flow.

To learn how to add a route node, see Adding a Route Node in Proxy Services: Message Flow in the Using the AquaLogic Service Bus Console.

To create a message flow, see “Viewing and Changing Message Flow” in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

Message Execution

The following table gives brief description of the components in a typical message flow

Table 2-2 Path Of a Message during a Message Flow

Message Flow Node

What Happens During Message Processing?

Request Processing

Request processing begins at the root of the message flow.

Pipeline Pair

Executes the request pipeline only.

Branch

Evaluates the branch table and proceeds down the relevant branch.

Route

Performs the route along with any request transformations.

Note:

In the message flow, regardless of whether routing takes place or not, the route node represents the change-over from processing a request to processing a response. At the route node, the direction of the message flow is reversed. If a request path does not have a route node, the response processing is initiated in the reverse direction without waiting for any response.

Response Processing

Skips any branch nodes and continues with the node that preceded the branch.

Route

Executes any response transformations. See Route for Request Processing.

Branch

Skips any branch nodes and continues with the node that preceded the branch.

Pipeline Pair

Executes the response pipeline.

Root of the Message Flow

Sends the response back to the client.

Pipelines

The principal component in a proxy service implementation is the pipeline. A pipeline is a named sequence of stages representing a non-branching one-way processing path.

To create the request and response paths, you pair request and response pipelines and organize them into a single node called a pipeline pair node.

A start node is the root of the tree structure for the loanGateway3 proxy service.
A pipeline pair node (PipelinePairNode1), which includes request and response pipelines. The request pipeline includes one stage (validate loan application). The icon associated with the validate loan application stage indicates that an error handler is defined for this stage. For more information about error handlers, which are also implemented as message flows, see Handling Errors.
A Route node (Route to Normal Loan Processing Service)

In addition to the view of the message flow shown in the preceding figure, the AquaLogic Service Bus Console displays the corresponding tree view map of the message flow to help you navigate components of a message flow at design time.

To view or edit the components of the message flow, click the component in the Map of Message Flow view. To edit or view a component from the tree view map, click the component and select the appropriate action from the list.

This flow structure provides a clear overview of the message flow behavior at design time, making both routes and branch conditions explicit parts of the overall design, rather than locating them out of view inside a pipeline stage or route node. A branch node allows you to conditionally execute these pipeline pairs, and route nodes at the ends of the branches perform the request and response dispatching. For more information about branch nodes, see Branching in Message Flows.

Branching in Message Flows

Two kinds of branching are supported in message flows: operational and conditional branching. The following sections explain when to use operational branching and when to use conditional branching.

Operational Branching

When message flows define Web Services Description Language (WSDL)-based proxy services, operation-specific processing is required. Instead of configuring a branching node based on operations manually, AquaLogic Service Bus provides a minimal configuration branching node that automatically branches based on operations. In other words, when you create an operational branch node in a message flow, you can quickly build your branching logic based on the operations defined in the WSDL because the AquaLogic Service Bus Console presents those operations in the branch node configuration page (Figure 2-4).

You must use operational branching in situations when a proxy service is based on a WSDL with multiple operations. You can consider using an operational branch node to handle messages separately for each operation. To learn how to configure operational branch nodes, see “Adding an Operational Branch Node” and “Viewing and Changing Operational Branch Details” in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

Conditional Branching

If the proxy service is not based on a WSDL and receives multiple document types as input, consider using a conditional branch node.

Conditional branching is driven by a lookup table with each branch tagged with a simple, but unique, string value. A variable in the message context is designated as the lookup variable for that node, and at run time, its value is used to determine which branch to follow. If no branch matches the value of the lookup variable, then the default branch is followed. You should design the proxy service in such a way that the value of the lookup variable is set before reaching the branch node.

For example, consider a case when a proxy service is of type Any SOAP or Any XML, and you need to determine the type of the message is so that you can perform conditional branching. In this case you can design a stage action to identify the message type and then design a conditional branching node in the flow to separate processing based on the message type you receive. When you design the conditional branch node in a message flow, you build the branching logic based on evaluation of the value of the variable populated in the preceding stage.

For more information on conditional branch nodes, see “Adding a Conditional Branch Node” in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

You can also use conditional branching to expose the routing alternatives at the top level flow view. For example, if you invoke service A or service B based on a condition, instead of configuring conditional branching by using a routing table within the route node, you can expose this branching in the message flow itself and use simple route nodes as the subflows for each of the branches.

Figure 2-5 shows a simple message flow with a top-level branch node (BranchNode1) and two subordinate route nodes. At run time, one branch is executed, causing messages to be routed to either service A or service B.

For more information on configuring a conditional branch in a route node, see “Adding Route Node Actions” in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

Consider your business scenario before deciding whether you configure branching in the message flow or in a stage or route node. When making your decision, remember that configuring branches in the message flow can awkward in the design interface if a large number of branches extend from the branch node.

For more information, see “Overview of Message Flow” in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

Performing Transformations

This section presents guidelines to follow when you design transformations. Transformation maps describe the mapping between two data types. AquaLogic Service Bus supports data mapping that uses XQuery and the eXtensible Stylesheet Language Transformation (XSLT) standards. XSLT maps describe XML-to-XML mappings, whereas XQuery maps can describe XML-to-XML, XML to non-XML, and non-XML to XML mappings. For more information, see XQuery Transformations and XSL Transformations in Using the AquaLogic Service Bus Console. For information on using the BEA XQuery Mapper to create XQueries, see Transforming Data Using the XQuery Mapper in Transforming Data Using the XQuery Mapper.

The point in a message flow at which you specify a transformation depends on whether:

The message format relies on target services—that is, the message format must be in a format acceptable by the route destination. This applies when the transformation is performed in a route node or in one of the publish actions.

Publish actions identify a target service for a message and configure how the message is packaged and sent to that service. AquaLogic Service Bus provides Publish Table actions also. A Publish Table action consists of a set of routes wrapped in a switch-style condition table. It is a shorthand construct that allows different routes to be selected, based upon the results of a single XQuery expression.

You perform the transformation on the response or request message regardless of the route destination. In this case, you can configure the transformations in the request or response pipeline stages.

Transformations and Publish Actions

When transformations are designed in publish actions, the transformations have a local copy of the $outbound variable and message-related variables ($header, $body, and $attachments). Any changes you make to an outbound message in a publish action affect only the published message. In other words, the changes you make in the publish action are rolled back before the message flow proceeds to any actions that follow the publish action in your message flow. For more information, see Proxy Services: Actions in Using the AquaLogic Service Bus Console and Message Context..

For example, consider a message flow that deals with a large purchase order, and you have to send the summary of the purchase order, through e-mail, to the manager. The summary of the of the purchase order is created in the SOAP body of the incoming message when you include a publish action in the request pipeline. In the publish action, the purchase order data is transformed into a summary of the purchase order—for example, all the attachments in $attachments can be deleted because they are not required in the summary of the purchase order.

Transformations and Route Nodes

In a situation in which you need to route messages to one of two possible destinations, based on a WS-addressing header, content-based routing and the second destination requires the newer version of the document in the SOAP body. In this situation, you can configure the route node to conditionally route to one of the two destinations. You can configure a transformation in the route node to transform the document for the second destination.

You can also set the control elements in the outbound context variable ($outbound) to influence the behavior of the system for the outbound message (for example, you can set the Quality of Service). See “Inbound and Outbound Variables” and “Constructing Messages to Dispatch” in Message Context. for information about the sub-elements of the inbound and outbound variables and how the content of messages is constructed using the values of the variables in the message context.

Configuring Single and Multiple Stages in Pipelines

In AquaLogic Service Bus message flows, stages are the containers for actions that define the logic of the message flow. In most cases it is sufficient to use a single stage in a pipeline. However, some situations require the use of multiple stages. Section Using Multiple Stages explains the usage of multiple stages in a pipeline. For information about configuring a stage, see “Adding a Stage” in Proxy Services: Actions in Using the AquaLogic Service Bus Console.

The BEA AquaLogic Service Bus provides a wide range of actions with which you can configure a stage in message flows. The actions are divided into following categories:

Communication

The actions in this category control the message flow in the pipeline. You use them to specify the target URL for a message flow, a mode of packaging for a message flow, and a mode to configure a synchronous callout to an AquaLogic Service Bus registered proxy service or a business service. Communication actions in a stage in a message flow pipeline include:

Dynamic Publish
Publish Overview
Publish Table
Routing Options
Service Callout
Transport Headers

For more information on communication actions, see Proxy Services: Action in Using the AquaLogic Service Bus Console. The communication actions available in a route node are:

Dynamic Routing
Routing
Routing Table

Note:

For more information on adding action to a stage in a route node, see Proxy Services: Message Flow-Adding Route Node Actions in Using the AquaLogic Service Bus Console.

The communication actions available in an error handler stage are:

Dynamic Publish
Publish Table
Routing Options
Service Callout
Transport Headers

Flow Control

The actions in this category control the message flow in the pipeline. You use them to implement conditional routing, conditional looping, and error handling within a stage in a message flow. Also you can use them to notify the invoker of success or to skip the rest of the actions in the stage. Flow actions in a stage in a pipeline include:

For Each
If... Then...
Raise Error
Reply
Skip

For more information on actions in this category, see Proxy Services: Actions in Using the AquaLogic Service Bus Console.

The flow control action available in a route node is If... Then...

Note:

For more information on adding an action to a stage in a route node, see Proxy Services: Message Flow-Adding Route Node Actions in Using the AquaLogic Service Bus Console.

The flow control actions available in an error handler stage are

For Each
If... Then...
Raise Error
Reply
Resume
Skip

Note:

For more information on adding an action to a stage in a route node, see Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.

Message Processing

The actions in this category process the message flow. You can use the actions under this category to modify the XPath expressions, invoke Java methods for processing, transform the message format, and set transport headers. Message Processing actions in a stage in a message flow pipeline include:

For more information on message processing actions, see Proxy Services: Actions in Using the AquaLogic Service Bus Console.

Message processing actions available in a stage in a pipeline error handler includes:

Reporting

You use the actions in this category to log or report errors and generate alerts if required in a message flow within a stage. Reporting actions in a stage in a message flow pipeline include:

For more information on the reporting actions, see Proxy Services: Actions in Using the AquaLogic Service Bus Console.

Using Multiple Stages

Having multiple stages in a message flow enables you to define error handlers at a modular level. Each stage in a message flow can have a separate error handling pipeline. You can use two types of actions to control runtime execution of the actions in a stage:

For more information, see “Adding a Stage” and “Viewing and Changing Stage Configuration Details” in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

Constructing Service Callout Messages

When AquaLogic Service Bus makes a call to a service via a Service Callout action, the content of the message is constructed using the values of variables in the message context. The message content for outbound messages is handled differently depending upon the type of the target service. How the message content is created depends on the type of the target service and whether you choose to configure the SOAP Body or the payload (parameters or document), as described in the following topics:

SOAP Document Style Services

Messages for SOAP Document Style services (including EJB document and document-wrapped services), can be constructed as follows:

To illustrate how messages are constructed during callouts to SOAP Document Style services, consider a Service Callout action configured as follows:

Assume also that at run time, the request document variable, myreq, is bound to the following XML.

At run time, the SOAP Request Header variable, reqheader, is bound to the following SOAP header.

In this example scenario, the full body of the message sent to the external service is as shown in the following listing (the contents of the myreq and reqheader variables are shown in bold).

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing">
        <wsa:Action>...</wsa:Action>
        <wsa:To>...</wsa:To>
        <wsa:From>...</wsa:From>
        <wsa:ReplyTo>...</wsa:ReplyTo>
        <wsa:FaultTo>...</wsa:FaultTo>
    </soap:Header>
    <soapenv:Body>
        <sayHello xmlns="http://www.openuri.org/">
            <intVal>100</intVal>
            <string>Hello AquaLogic</string>
        </sayHello>
    </soapenv:Body>
</soapenv:Envelope>

Based on the configuration of the Service Callout action described above, the response from the service is assigned to the myresp variable. The full response from the external service is as shown in the following listing.

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.
org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <env:Header/>
    <env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <m:sayHelloResponse xmlns:m="http://www.openuri.org/">
            <result xsi:type="xsd:string">This message brought to you by Hello AquaLogic and the number 100
            </result>
        </m:sayHelloResponse>
    </env:Body>
</env:Envelope>

In this scenario, the myresp variable is assigned the value shown in the following listing.

SOAP RPC Style Services

Messages for SOAP RPC Style services (including EJB RPC services) can be constructed as follows:

Request messages are assembled from message context variables.

The SOAP Body is built based on the SOAP RPC format (operation wrapper, parameter wrappers, and so on).
The SOAP Header is the content of the variable specified for the SOAP Request Header, if one is specified.
Part as element—the parameter value is the variable content.
Part as simple type—the parameter value is the string representation of the variable content.
Part as complex type—the parameter corresponds to renaming the root of the variable content after the parameter name.

Response messages are assembled as follows:

The output content is the content of SOAP Header, if a SOAP Header is specified.
Part as element—the output content is the child element of the parameter; there is at most one child element.
Part as simple/complex type—the output content is the parameter itself

To illustrate how messages are constructed during callouts to SOAP RPC Style services, take an example with the following configuration:

A message context variable input1 is bound to a value 100
A message context variable input2 is bound to a string value: Hello AquaLogic.
A Service Callout action configured as follows:

Request Parameter intval: input1
Request Parameter string: input2
Response Parameter result: output1

In this scenario, the body of the outbound message to the service is as shown in Listing 2-6:

The response returned by the service to which the call was made is shown in the following listing.

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <env:Header/>
    <env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <m:sayHello2Response xmlns:m="http://www.openuri.org/">
            <result xsi:type="n1:HelloWorldResult" xmlns:n1="java:">
                <message xsi:type="xsd:string">
                This message brought to you by Hello AquaLogic and the number 100
                </message>
            </result>
        </m:sayHello2Response>
    </env:Body>
</env:Envelope>

The message context variable output1 is assigned the value shown in the following listing.

XML Services

To illustrate how messages are constructed during callouts to XML services, take for example a Service Callout action configured as follows:

Assume also that at run time, the request document variable, myreq, is bound to the following XML.

Messaging Services

For example, if the request message context variable myreq is bound to an XML document of the following format: <hello>there</hello>, the outbound message contains exactly this payload. The response message context variable (myresp) is bound to a reference element similar to the following:

Handling Errors

You can configure error handling at the Message Flow, pipeline, route node, and stage level. For information about doing so, see “Error Messages and Handling” on page 20-1. The types of errors that are received from an external service as the result of a Service Callout include transport errors, SOAP faults, responses that do not conform to an expected response, and so on.

The fault context variable is set differently for each type of error returned. You can build your business and error handling logic based on the content of the fault variable. To learn more about $fault, see “Fault Variable” on page A-14 and Appendix A, “Error CodesLocal Transport”

Transport Errors

When a transport error is received from an external service and there is no error response payload returned to AquaLogic Service Bus by the transport provider (for example, in the case that an HTTP 403 error code is returned), the Service Callout action throws an exception, which in turn causes the pipeline to raise an error. The fault variable in a user-configured error handler is bound to a message formatted similarly to that shown in the following listing.

In the case that there is a payload associated with the transport error—for example, when an HTTP 500 error code is received from the business service and there is XML payload in the response—a message context fault is generated with the custom error code: BEA-382502.

The following conditions must be met for a BEA-382502 error response code to be triggered as the result of a response from a service—when that service uses an HTTP or JMS transport:

If the transport is HTTP, the ErrorResponseDetail element will also contain the HTTP error code returned with the response. The ErrorResponseDetail element in the fault contains error response payload received from the service. The following listing shows an example of the ErrorResponseDetail element.

<ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context">
    <ctx:errorCode>BEA-382502<ctx:errorCode>
    <ctx:reason> Service callout has received an error response from the server</ctx:reason>
    <ctx:details>
        <alsb:ErrorResponseDetail xmlns:alsb="http://www.bea.com/...">
            <alsb:detail> <![CDATA[
. . .                 
	]]>
            </alsb:detail>           <alsb:http-response-code>500</alsb:http-response-code>
        </alsb:ErrorResponseDetail>
    </ctx:details>
    <ctx:location>. . .</ctx:location>
</ctx:Fault>

SOAP Faults

In case an external service returns a SOAP fault, the AquaLogic Service Bus run time sets up the context variable $fault with a custom error code and description with the details of the fault. To do so, the contents of the 3 elements under the <SOAP-ENV:Fault> element in the SOAP fault are extracted and used to construct an AquaLogic Service Bus fault element.

The <faultcode>, <faultstring>, and <detail> elements are extracted and wrapped in an <alsb:ReceivedFault> element. Note that the faultcode element in Listing 2-13 contains a QName—any related namespace declarations are preserved. If the transport is HTTP, the ReceivedFault element will also contain the HTTP error code returned with the fault response.

The generated <alsb:ReceivedFault> element, along with the custom error code and the error string are used to construct the contents of the fault context variable, which in this example takes a format similar to that shown in the following listing.

<ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context">
    <ctx:errorCode>BEA-382500<ctx:errorCode>
    <ctx:reason> service callout received a soap Fault response</ctx:reason>
    <ctx:details>
        <alsb:ReceivedFault xmlns:alsb="http://www.bea.com/...">
            <alsb:faultcode
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">SOAP-ENV:Clien
            </alsb:faultcode>
            <alsb:faultstring>Application Error</alsb:faultstring> 
            <alsb:detail> 
                <message>T

hat’s an Error!

</message> 
                <errorcode>1006</errorcode> 
            </alsb:detail>

          <alsb:http-response-code>500</alsb:http-response-code>
        </alsb:ReceivedFault>
    </ctx:details>
    <ctx:location> </ctx:location>
</ctx:Fault>

Unexpected Responses

When a service returns a response message that is not what the proxy service’s run time expects, a message context fault will be generated and initialized with the custom error code BEA-382501. The details of the fault include the contents of the SOAP-Body element of the response. If the transport is HTTP, the ReceivedFault element will also contain the HTTP error code returned with the fault response.

The XML Schema for the Service Callout-generated fault is shown in Listing 2-15.

XML Schema for the Service Callout-Generated Fault Details

The XML schema definition of the service callout-generated fault details is shown in the following listing.

<xs:complexType name="ReceivedFaultDetail">
        <xs:sequence>
            <xs:element name="faultcode" type="xs:QName"/>
            <xs:element name="faultstring" type="xs:string"/>
            <xs:element name="detail" minOccurs="0" >
               <xs:complexType>
                 <xs:sequence>
                        <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax" /> 
                 </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax" /> 
               </xs:complexType>
            </xs:element>

Handling Errors

The process described in the next paragraph constitutes an error handling pipeline for the error handling stage. In addition, an error pipeline can be defined for a pipeline (request or response) or for an entire proxy service.

The error handler at the stage level is invoked for handling an error; If the stage-level error handler is not able to handle a given type of error, the pipeline error handler is invoked. If the pipeline -level error handler also fails to handle the error the service level error handler is invoked. If the service level error handler also fails, the error is handled by the system.The following table summarizes the scope of the error handlers at various levels in the message flow.

For more information on error messages and error handling, see “Error Messages and Handling” in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.

You can handle errors by configuring a test that checks if an assertion is true and use the reply action configured false. You can repeat this test at various levels. Also you can have an error without an error handler at a lower level and handle it through an error handler at an higher level in message flow.In general, it is easier to handle specific errors at a stage level of the message flow and use error handlers at the higher level for more general default processing of errors that are not handled at the lower levels. It is good practice to explicitly handle anticipated errors in the pipelines and allow the service-level handler to handle unanticipated errors.

Generating the Error Message, Reporting, and Replying

A predefined context variable (the fault variable) is used to hold information about any error that occurs during message processing. When an error occurs, this variable is populated with information before the appropriate error handler is invoked. The fault variable is defined only in error handler pipelines and is not set in request and response pipelines, or in route or branch nodes. For additional information about $fault, see Predefined Context Variables.

In the event of errors for request/response type inbound messages, it is often necessary to send a message back to the originator outlining the reason why an error occurred. You can accomplish this by using a Reply with Failure action after configuring the message context variables with the response you want to send. For example, when an HTTP message fails, Reply with Failure generates the HTTP 500 status. When a JMS message fails, Reply with Failure sets the JMS_BEA_Error property to true. The AquaLogic Service Bus error actions are discussed in “Error Messages and Handling” in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.

An error handling pipeline is invoked if a service invoked by a proxy service returns a SOAP fault or transport error. Any received SOAP fault is stored in $body, so if a Reply with Failure is executed without modifying $body, the original SOAP fault is returned to the client that invoked the service. If a reply action is not configured, the system error handler generates a new SOAP fault message. The proxy service recognizes that a SOAP fault is returned because a HTTP error status is set, or the JMS property SERVER_Error is set to true.

Some use cases require error reporting. You can use the report action in these situations. For example, consider a scenario in which the request pipeline reports a message for tracking purposes, but the service invoked by the route node fails after the reporting action. In this case, the reporting system logged the message, but there is no guarantee that the message was processed successfully, only that the message was successfully received.

You can use the AquaLogic Service Bus Console to track the message to obtain an accurate picture of the message flow. This allows you to view the original reported message indicating the message was submitted for processing, and also the subsequent reported error indicating that the message was not processed correctly. To learn how to configure a Report action and use the data reported at run time, see Proxy Services: Actions in Using the AquaLogic Service Bus Console.

Example of Action Configuration in Error Handlers

This example shows how you can configure the Report and Reply actions in error handlers. The message flow shown in Figure 2-2 includes an error handler on the validate loan application stage. The error handler in this case is a simple message flow with a single stage configured—it is represented in the AquaLogic Service Bus Console as shown in the following figure.

The stage is, in turn, configured with actions (Replace, Report, and Reply) as shown in the following figure.

The actions control the behavior of the stage in the pipeline error handler as follows:

Replace—The contents of a specified element of the body variable are replaced with the contents of the fault context variable. The body variable element is specified by an XPath expression. The contents are replaced with the value returned by an XQuery expression—in this case $fault/ctx:reason/text()
Report— Messages from the reporting action are written to the AquaLogic Service Bus Reporting Data Stream if the error handler configured with this action is invoked. The JMS Reporting Provider reports the messages on the AquaLogic Service Bus Dashboard. AquaLogic Service Bus provides the capability to deliver message data to one or more reporting providers. Message data is captured from the body of the message and from any other variables associated with the message, such as header or inbound variables. You can use the message delivered to the reporting provider for functions such as tracking messages or regulatory auditing.

When an error occurs, the contents of the fault context variable are reported. The key name is errorCode, and the key value is extracted from the fault variable using the following XPath expression: ./ctx:errorCode. Key/value pairs are the key identifiers that identify these messages in the Dashboard at run time.

To configure a Report action and use the data reported at run time, see Proxy Services: Actions in Using the AquaLogic Service Bus Console.

Reply— At run time, an immediate reply is sent to the invoker of the loanGateway3 proxy service (see Figure 2-2) indicating that the message had a fault The reply is With Failure.

For configuration information, see “Error Messages and Handling” in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.

Selecting a Service Type

AquaLogic Service Bus supports a variety of service types that range from conventional Web services (using XML or SOAP bindings in WSDLs) to non-XML or generic services. This section provides guidelines on selecting a service type.

SOAP Services—SOAP services receive and respond with SOAP messages. SOAP messages are constructed by wrapping the contents of the header and body variables inside a <soap:Envelope> element. SOAP services can be SOAP 1.1 or SOAP 1.2 services.
XML Services (Non SOAP)—The messages to XML-based services are XML, but can be of any type allowed by the proxy service configuration.
Messaging Services—Messaging services are those that can receive messages of one data type and respond with messages of a different data type. The supported data types include XML, MFL, text, and untyped binary.
WSDL Web Service—In AquaLogic Service Bus you define proxy services based on WSDL. The WSDL indicates if the service is a SOAP 1.1 or a SOAP 1.2 service. Although it is not mandatory, BEA recommends that you use a WSDL to define a proxy service. For more information on WSDL based services, see Using a WSDL to Define a Service.

The following table shows the service types and the transports, which AquaLogic Service Bus supports.

Table 2-4 Supported Service Types and Transports
Service Type	Transport Protocols
SOAP or XML WSDL	HTTP HTTP(S) JMS Local
SOAP (no WSDL)	HTTP HTTP(S) JMS Local
XML (no WSDL)¹	e-mail File FTP HTTP HTTP(S) JMS Local Tuxedo²
Transport Typed	EJB
Messaging Type (Binary, Text, MFL, XML)	e-mail File FTP HTTP HTTP(S) JMS Local Tuxedo

¹HTTP GET is supported for the XML (no WSDL) service type and Messaging Service.

²For a Tuxedo transport-based service, if the service type is XML, an FML32 buffer with an FLD_MBSTRING field from a Tuxedo client will not be transformed to XML.

BEA recommends that you use the local transport for communication between two proxy services. For more information on local transport, see Local Transport.

Using a WSDL to Define a Service

If a service has a well defined Web Services Description Language (WSDL) interface, it is recommended, although not required, that you use the WSDL to define the service. For more information on WSDL resources in AquaLogic Service Bus, see WSDLs in Using the AquaLogic Service Bus Console.

SOAP Document Wrapped Web Services

A document wrapped Web Service is described in a WSDL as a Document Style Service. However, it follows some additional conventions. Standard document-oriented Web Service operations take only one parameter or message part, typically an XML document. This means that the methods that implement the operations must also have only one parameter. Document-wrapped Web Service operations, however, can take any number of parameters, although the parameter values will be wrapped into one complex data type in a SOAP message. This wrapped complex data type will be described in the WSDL as the single document for the operation.

For more information on SOAP Document Wrapped Web Services see Adding a Business Service in Using the AquaLogic Service Bus Console.

SOAP Document Style Web Services

You can configure proxy services as SOAP style proxy services and configure business services as SOAP style business services.

The following listing provides an example of a WSDL for a sample document style Web service using SOAP 1.1.

<definitions name="Lookup"
targetNamespace="http://example.com/lookup/service/defs"
xmlns:tns="http://example.com/lookup/service/defs"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:docs="http://example.com/lookup/docs"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types>
    <xs:schema targetNamespace="http://example.com/lookup/docs" elementFormDefault="qualified">
      <xs:element name="PurchaseOrg" type="xs:string"/>
      <xs:element name="LegacyBoolean" type="xs:boolean"/>
    </xs:schema>
  </types>
  <message name="lookupReq">
    <part name="request" element="docs:purchaseorg"/>
  </message>
  <message name="lookupResp">
    <part name="result" element="docs:legacyboolean"/>
  </message>
  <portType name="LookupPortType">
    <operation name="lookup">
      <input message="tns:lookupReq"/>
      <output message="tns:lookupResp"/>
    </operation>
  </portType>
  <binding name="LookupBinding" type="tns:lookupPortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="lookup">
      <soap:operation/>
      <input>
        <soap:body use="literal" />
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
</definitions>

The service has an operation (equivalent to a method in a Java class) called lookup. The binding indicates that this is a SOAP 1.1 document style Web service.

When the WSDL shown in the preceding listing is used for a request, the value of the body variable ($body) that the document style proxy service obtains is displayed in the following listing.

In Listing 2-17, soap-env is the predefined SOAP 1.1 namespace and req is the namespace of the PurchaseOrg element (<http://example.com/lookup/docs>).

If the business service to which the proxy service is routing uses the above WSDL, the value for the body variable ($body) given above is the value of the body variable ($body) from the proxy service.

The value of the body variable ($body) for the response from the invoked business service that the proxy service receives is displayed in the following listing.

This is also the value of the body variable ($body) for the response returned by the proxy service using this WSDL.

There are many tools available (including BEA WebLogic Workshop tools) that take the WSDL of a proxy service (obtained by adding the ?WSDL suffix to the URL of the proxy service in the browser) and generate a Java class with the appropriate request and response parameters to invoke the operations of the service. This Java class can be used to invoke the proxy service that uses this WSDL.

SOAP RPC Web Services

You can configure proxy services as RPC style proxy services and configure business services as RPC style business services.

The following listing provides an example of a WSDL for a sample RPC style Web service using SOAP 1.1.

<definitions name="Lookup"
targetNamespace="http://example.com/lookup/service/defs"
xmlns:tns="http://example.com/lookup/service/defs"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:docs="http://example.com/lookup/docs"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types>
    <xs:schema targetNamespace="http://example.com/lookup/docs" elementFormDefault="qualified">
      <xs:complexType name="RequestDoc">
        <xs:sequence>
          <xs:element name="PurchaseOrg" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="ResponseDoc">
        <xs:sequence>
          <xs:element name="LegacyBoolean" type="xs:boolean"/>
        </xs:sequence>
      </xs:complexType>
    </xs:schema>
  </types>
  <message name="lookupReq">
    <part name="request" type="docs: RequestDoc"/>
  </message>
  <message name="lookupResp">
    <part name="result" type="docs: ResponseDoc"/>
  </message>
  <portType name="LookupPortType">
    <operation name="lookup">
      <input message="tns:lookupReq"/>
      <output message="tns:lookupResp"/>
    </operation>
  </portType>
  <binding name="LookupBinding" type="tns:lookupPortType">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="lookup">
      <soap:operation/>
      <input>
        <soap:body use="literal" namespace="http://example.com/lookup/service"/>
      </input>
      <output>
        <soap:body use="literal" namespace="http://example.com/lookup/service"/>
      </output>
    </operation>
  </binding>
</definitions>

The service described in the preceding listing includes an operation (equivalent to a method in a Java class) called lookup. The binding indicates that this is a SOAP RPC Web service. In other words, the Web service’s operation receives a set of request parameters and returns a set of response parameters. The lookup operation has a parameter called request and a return parameter called result. The namespace of the operation in the binding is:

When the WSDL shown in Listing 2-19 is used for a request, the value of the body variable ($body) that the SOAP RPC proxy service obtains is displayed in the following listing.

Where soap-env is the predefined SOAP 1.1 name space, ns is the operation namespace (<http://example.com/lookup/service>) and, req is the namespace of the PurchaseOrg element (<http://example.com/lookup/docs>).

If the business service to which the proxy service routes the messages uses the WSDL shown in Listing 2-17, the value for the body variable ($body), shown in Listing 2-18, is the value of the body variable ($body) from the proxy service.

When this WSDL is used for a request, the value of the body variable ($body) for the response from the invoked business service that the proxy service receives is displayed in the following listing.

This is also the value of the body variable ($body) for the response returned by the proxy service using this WSDL.

There are many tools available (including BEA WebLogic Workshop tools) that take the WSDL of a proxy service (obtained by adding the ?WSDL suffix to the URL of the proxy in the browser) and generate a Java class with the appropriate request and response parameters to invoke the operations of that service. You can use such Java classes to invoke the proxy services that use this WSDL.

The system can provide metrics for each operation in a WSDL.
Operational branching is possible in the pipeline. For more information, see Branching in Message Flows.
For SOAP 1.1 services, the SOAPAction header is automatically populated for services invoked by a proxy service. For SOAP 1.2 services, the action parameter of the Content-Type header is automatically populated for services invoked by a proxy service.
A WSDL is required for services using WS-Security. WS-Policies are attached to WSDLs. See WS-Polices in Using the AquaLogic Service Bus Console.
The system supports the <url>?WSDL syntax, which allows you to dynamically obtain the WSDL of a HTTP proxy service. This is useful for a number of SOAP client generation tools, including BEA WebLogic Workshop.
In the XQuery and XPath editors and condition builders, it is easy to manipulate the body content variable ($body) because the editor provides a default mapping of $body to the request message in the WSDL of a proxy service. See Message Context.

Note: The run-time contents of $body for a specific action can be different from the default mapping displayed in the editor. This is because AquaLogic Service Bus is not a programming language in which typed variables are declared and used. Instead, variables are untyped and are created dynamically at run time when a value is assigned. In addition, the type of the variable is the type that is implied by its contents at any point in the message flow. To enable you to easily create XQuery and XPath expressions, the design time editor allows you to map the type for a given variable by mapping the variable to the type in the editor. To learn about using the XQuery and XPath editor to create expressions, see Working with Variable Structures on page 2-53.

Binding a Service to a WSDL Port Instead of to a Binding

If you use a WSDL service type, it is useful to bind the service to a WSDL port instead of to a binding because:

If the service is bound to port X in the template WSDL, then port X is also defined in the generated WSDL. Any other ports defined in the template WSDL are not included in the generated WSDL. Furthermore, if you base the proxy service on a WSDL port, the generated WSDL uses that port name and preserves any WS-Policies associated with that port.

(The template WSDL is the WSDL for the service upon which you based your proxy service; the generated WSDL is the WSDL created for the new proxy service.)

If the service is bound to binding Y in the template WSDL, the generated WSDL defines one service and port (<service-name>QSService and <port-name>QSPort). None of the ports defined in the template WSDL are included in the generated WSDL.

You can get the WSDL for an HTTP or HTTP(S)-based proxy service by entering the following URL in your browser’s address field:

In the WSDL returned by the http://host:port/sbresource?PROXY/project/proxyname URL or the WSDL, which is obtained from the URL for the proxy service, the port name is preserved if the proxy service is bound to a port on the WSDL and the URL accurately reflects the URL of the proxy service. This can be important to some tools, which generate a client. The URL in the WSDL port that is bound to the service is not used when you define a service, except to populate the URL in the WSDL port as the default URL for a business service. You can overwrite the transport type and transport URL in the transport configuration UI for the service definition.

Any WS-Security policies at the port level apply. See “Overview of Proxy Services” in Proxy Services in Using the AquaLogic Service Bus Console.

Using Any SOAP or Any XML Service Types

If you want to expose one port to clients for a variety of enterprise applications, use Any SOAP or Any XML service types.

Using the Messaging Service Type

If one of the request or response messages is non-XML, you must use the messaging service type.

AquaLogic Service Bus does not automatically perform “misunderstand” SOAP header checking. However, you can use XQuery conditional expressions and validate actions to explicitly perform this type of check. For more information on the validate action, see “Validate” in Proxy Services: Actions in Using the AquaLogic Service Bus Console. For more information on conditional XQuery expressions, see “Using the XQuery Condition Editor” in Proxy Services: Editors in Using the AquaLogic Service Bus Console.

You can use AquaLogic Service Bus to configure a validate action and use XQuery conditional expressions to perform validation checks explicitly in the message flow.

For more information on service types, see “Overview of Proxy Services” in Proxy Services in Using the AquaLogic Service Bus Console.

Viewing Resource Details

AquaLogic Service Bus provides a resource servlet that is used to expose the resources registered in AquaLogic Service Bus. The resources registered with AquaLogic Service Bus include:

http://host:port/sbresource?WSDL/project/...wsdlname
http://host:port/sbresource?POLICY/project/...policyname
http://host:port/sbresource?MFL/project/...mflname
http://host:port/sbresource?SCHEMA/project/...schemaname
http://host:port/sbresource?PROXY/project/...proxyname

Using Dynamic Routing

When you do not know the service you need to invoke from the proxy service you are creating, you can use dynamic routing.

For any given proxy service, you can use one of the following techniques to dynamically route messages:

In a message flow pipeline, design an XQuery expression to dynamically set the fully qualified service name in AquaLogic Service Bus and use the dynamic route or dynamic publish actions.

Note:

Dynamic Routing can be achieved in a route node, whereas dynamic publishing can achieved in a stage in a request pipeline or a response pipeline.

With this technique, the proxy service dynamically uses the service account of the endpoint business service to send user names and passwords in its outbound requests. For example, if a proxy service is routing a request to Business Service A, then the proxy service uses the service account from Business Service A to send user names and passwords in its outbound request. See Implementing Dynamic Routing.

Configure a proxy service to route or publish messages to a business service. Then, in the request actions section for the route action or publish action, add a Routing Options action that dynamically specifies the URI of a service.

With this technique, to send user names and passwords in its outbound requests, the proxy service uses th

User Guide

Modeling Message Flow in AquaLogic Service Bus

About AquaLogic Service Bus Message Flow

Building a Message Flow

Message Execution

Pipelines

Branching in Message Flows

Operational Branching

Conditional Branching

Performing Transformations

Transformations and Publish Actions

Transformations and Route Nodes

Configuring Single and Multiple Stages in Pipelines

Communication

Flow Control

Message Processing

Reporting

Using Multiple Stages

Constructing Service Callout Messages

SOAP Document Style Services

SOAP RPC Style Services

XML Services

Messaging Services

Handling Errors

Transport Errors

SOAP Faults

Unexpected Responses

XML Schema for the Service Callout-Generated Fault Details

Handling Errors

Generating the Error Message, Reporting, and Replying

Example of Action Configuration in Error Handlers

Selecting a Service Type

Using a WSDL to Define a Service

SOAP Document Wrapped Web Services

SOAP Document Style Web Services

SOAP RPC Web Services

Binding a Service to a WSDL Port Instead of to a Binding

Using Any SOAP or Any XML Service Types

Using the Messaging Service Type

Viewing Resource Details

Using Dynamic Routing