|
|
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:
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.
This topic includes the following sections:
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.
|
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.
|
||
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.
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.
|
|||
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.
The following table gives brief description of the components in a typical message flow
|
|||
Executes any response transformations. See Route for Request Processing.
|
|||
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.
Pipelines belong to one of the following categories:
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.
Message Flow Definition for a Proxy Service shows an example of a simple message flow. It defines a proxy service named loanGateway3.
The message flow in the preceding figure shows:
loanGateway3 proxy service.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.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.
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.
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.
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.
| Note: | It is highly recommended that you define a default branch whenever your message flow involves conditional branching. |
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.
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:
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.
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.
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.
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:
| Note: |
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:
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:
| 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:
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 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
| 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. |
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:
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:
Reporting actions in a stage under a pipeline error handler includes:
For more information on the reporting actions, see Proxy Services: Actions in Using the AquaLogic Service Bus Console.
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:
| Note: | The message flow processing resumes at the next stage in the pipeline. |
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.
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:
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.
<sayHello xmlns="http://www.openuri.org/">
<intVal>100</intVal>
<string>Hello AquaLogic</string>
</sayHello>
At run time, the SOAP Request Header variable, reqheader, is bound to the following SOAP header.
<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>
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.
<m:sayHelloResponse xmlns:m="http://www.openuri.org/">
<result ns0:type="xsd:string" xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance">
This message brought to you by Hello AquaLogic and the number 100
</result>
</m:sayHelloResponse>
Messages for SOAP RPC Style services (including EJB RPC services) can be constructed as follows:
To illustrate how messages are constructed during callouts to SOAP RPC Style services, take an example with the following configuration:
In this scenario, the body of the outbound message to the service is as shown in Listing 2-6:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<sayHello2 xmlns="http://www.openuri.org/">
<intVal>100</intVal>
<string >Hello AquaLogic</string>
</sayHello2>
</soapenv:Body>
</soapenv:Envelope>
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.
<message ns0:type="xsd:string" xmlns:ns0="http://www.w3.org/2001/XMLSchema-intance">
This message brought to you by Hello AquaLogic and the number 100</message>
Messages for XML services can be constructed as follows:
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.
<sayHello xmlns="http://www.openuri.org/">
<intVal>100</intVal>
<string>Hello AquaLogic</string>
</sayHello>
<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>
In the case of Messaging services:
<binary-content ref=.../> reference XML.<binary-content ref= ... /> reference XML, regardless of the actual content received.
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:
<binary-content ref=" cid:1850733759955566502-2ca29e5c.1079b180f61.-7fd8"/>
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”
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.
<con:fault xmlns:con="http://www.bea.com/wli/sb/context">
<con:errorCode>BEA-380000</con:errorCode>
<con:reason>Not Found</con:reason>
<con:details>
.......
</con:details>
<con:location>
<con:node>PipelinePairNode1</con:node>
<con:pipeline>PipelinePairNode1_request</con:pipeline>
<con:stage>stage1</con:stage>
</con:location>
</con:fault>
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>
| Note: | The XML Schema for the Service Callout-generated fault is shown in XML Schema for the Service Callout-Generated Fault Details. |
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.
Take for example a scenario in which a service returns the following error.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring>Application Error</faultstring>
<detail>
<message>That’s an Error!</message>
<errorcode>1006</errorcode>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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">hat’s an Error!
<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</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>
| Note: | The unique error code BEA-382500 is reserved for the case when Service Callout actions receive SOAP Fault 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.
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>
<xs:element name="http-response-code" type="xs:int" minOccurs="0"/>\
type="xs:int" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="UnrecognizedResponseDetail">
<xs:sequence>
<xs:element name="detail" minOccurs="0" type="xs:string" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ErrorResponseDetail">
<xs:sequence>
<xs:element name="detail" minOccurs="0" type="xs:string" />
</xs:sequence>
</xs:complexType>
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.
Handles all the errors in a proxy service, along with any unhandled errors in any pipeline in a service.
|
|||
| Note: | There are exceptions to the scope of error handlers. For example, an exception thrown by a non-XML transformation at the Stage level is only caught by the Service level error handler.Suppose a transformation occurs that transforms XML to MFL for an outgoing proxy service response message, it always occurs in the binding layer. Therefore, for example, if a non-XML output is missing a mandatory field at the stage level, only a service level error handler can catch this error. |
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.
| Note: | You can only handle WS-Security related errors at the service level. |
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.
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:
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()
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.
With Failure.For configuration information, see “Error Messages and Handling” in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.
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.
AquaLogic Service Bus service types for a proxy service include:
<soap:Envelope> element. SOAP services can be SOAP 1.1 or SOAP 1.2 services.| Note: | All service types can send and receive attachments using MIME. |
| Note: | For more information on selecting a service type, see Adding a Proxy Services in Using the AquaLogic Service Bus Console |
The following table shows the service types and the transports, which AquaLogic Service Bus supports.
XML (no WSDL)1
|
Tuxedo2
|
1HTTP GET is supported for the XML (no WSDL) service type and Messaging Service. 2For 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.
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.
There are three types of WSDLs you can define. They are:
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.
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.
| Note: | Namespace declarations have been removed from the XML in the listings that follow for the sake of clarity. |
<soap-env:body>
<req:purchaseorg>BEA Systems</req:purchaseorg>
</soap-env:body>
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.
| Note: | Namespace declarations have been removed from the XML in the listings that follow for the sake of clarity. |
<soap-env:body>
<req:legacyboolean>true</req:legacyboolean>
</soap-env:body>
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.
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:
http://example.com/lookup/service
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.
| Note: | Namespace declarations have been removed from the XML in the listings that follow for the sake of clarity. |
<soap-env:body>
<ns:lookup>
<request>
<req:purchaseorg>BEA Systems</req:purchaseorg>
</request>
</ns:lookup>
<soap-env:body>
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.
<soap-env:body>
<ns:lookupResponse>
<result>
<req:legacyboolean>true</req:legacyboolean>
</result>
</ns:lookupResponse>
<soap-env:body>
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 benefits of using a WSDL include the following:
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. <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.$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. |
If you use a WSDL service type, it is useful to bind the service to a WSDL port instead of to a binding because:
(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.)
<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:
http://host:port/sbresource?PROXY/project/proxyname
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.
If you want to expose one port to clients for a variety of enterprise applications, use Any SOAP or Any XML service types.
| Note: | For Any SOAP, you need to specify if it is SOAP 1.1 or SOAP 1.2. |
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.
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:
The format of the URLs used to expose the resources is as follows:
You can use the following URL formats to expose the resource details:
| Note: | The URLs used to expose the resources in AquaLogic Service Bus must be encoded in UTF-8 in order to escape special characters. |
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:
| 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.
With this technique, to send user names and passwords in its outbound requests, the proxy service uses the service account of the statically defined business service, regardless of the URI to which the request is actually sent.
For information on how to use this technique, see Implementing Dynamic Routing.
| Note: | This technique is used when the overview of the interface is fixed. The overview of the interface includes message types, port types, and binding, and excludes the concrete interface. The concrete interface is the transport URL at which the service is located. |
You can use dynamic routing to determine the destination during the runtime of a proxy service. To achieve this you can use a routing table in an XML file to create an XQuery resource.
| Note: | Instead of using the XQuery resource, you can also directly use the XML file from which the resource is created. |
An XML file or the Xquery resource can be maintained easily. At runtime you provide the entry in the routing table that will determine the routing or publishing destination of the proxy service.The XML file or the XQuery resource contains a routing table, which maps a logical identifier to (such as the name of a company) to the physical identifier (the fully qualified name of the service in AquaLogic Service Bus). The logical identifier, which is extracted from the message, maps on to the physical identifier, which is the name of the service you want to invoke.
| Note: | To use the dynamic route action, you need the fully qualified name of the service in AquaLogic Service Bus. |
In a pipeline the logical identifier is obtained with an XPath into the message.You assign the XML table in the XQuery resource to a variable. You implement a query against the variable in the routing table to extract the physical identifier based on the corresponding logical identifier. Using this variable you will be able to invoke the required service. The following sections describe how to implement dynamic routing.
You can create an XQuery resource from the following XML file. Save this as sampleXquery.xml.
<routing>
<row>
<logical>BEA Systems</logical>
<physical>default/goldservice</physical>
</row>
<row>
<logical>ABC Corp</logical>
<physical>default/silverservice</physical>
</row>
</routing>
| Note: | To do this repeat step 11 to step 13 |
<ctx: route>
<ctx: service>{$routingtable/row[logical/text()=$logicalidentifier]/physical/text()}</ctx: service>
</ctx: route>
In the above code, replace $logicalidentifier by the actual XPath to extract the logical identifier from the message (example from $body).
By this you extract the XML used by the dynamic route action into this variable.
AquaLogic Service Bus provides read-access to databases from proxy services without requiring you to write a custom EJB or custom Java code and without the need for a separate database product like AquaLogic Data Services Platform. You can use the execute-sql() function to make a simple JDBC call to a database to perform simple database reads. Any SQL query is legal, from a query that gets a single tax rate for the supplied location to a query that does a complex join to obtain an order's current status from several underlying database tables.
A database query can be used to get data for message enrichment, for routing decisions, or for customizing the behavior of a proxy service. Take for example a scenario in which an AquaLogic Service Bus proxy service receives “request for quote” messages. The proxy service can route the requests based on the customer's priority to one of a number of quotation business services (say, standard, gold, or platinum level services). The proxy service can then perform a SQL-based augmentation of the results that those services return—for example, based on the selected ship method and the weight of the order, the shipping cost can be looked up and that cost added to the request for quote message.
fn-bea:execute-sql() describes the syntax for the function and provides examples of its use. The execute-sql() function returns typed data and automatically translates values between SQL/JDBC and XQuery data models.
You can store the returned element in a user-defined variable in an AquaLogic Service Bus message flow.
The following databases and JDBC drivers are supported using the execute-sql() function:
Use non-XA drivers for datasources you use with the fn-bea:execute-sql() function—the function supports read-only access to the datasources.
| WARNING: | In addition to specifying a non-XA JDBC driver class to use to connect to the database, you must ensure that you disable global transactions and two-phase commit. (Global transactions are enabled by default in the WebLogic Server console for JDBC data sources.) These specifications can be made for your data source via the WebLogic Server Administration Console. See Create JDBC Data Sources in the WebLogic Server Administration Console Online Help. |
For complete information about database and JDBC drivers support in AquaLogic Service Bus, see Supported Database Configurations in Supported Configurations for AquaLogic Service Bus.
Databases other than the core set described in the preceding listing are also supported. However, for the core databases listed above, the XQuery engine does a better recognition and mapping of data types to XQuery types than it does for the non-core databases—in some cases, a core database’s proprietary JDBC extensions are used when fetching data. For the non-core databases, the XQuery engine relies totally on the standard type codes provided by the JDBC driver and standard JDBC resultset access methods.
When designing your proxy service, you can enter XQueries inline as part of an action definition instead of entering them as resources. You can also use inline XQueries for conditions in If...Then... actions in message flows. For information about using the inline XQuery editor, see Creating Variable Structure Mappings.
The message context is a set of variables that hold message context and information about messages as they are routed through the AquaLogic Service Bus. Together, the header, body, and attachments variables, (referenced as $header, $body and $attachments in XQuery statements) represent the message as it flows through AquaLogic Service Bus. The canonical form of the message is SOAP. Even if the service type is not SOAP, the message appears as SOAP in the AquaLogic Service Bus message context.
In a Message Context, $header contains a SOAP Header element and $body contains a SOAP Body element. The Header and Body elements are qualified by the SOAP 1.1 or SOAP 1.2 namespace depending on the service type of the proxy service. Also in a Message Context, $attachments contains a wrapper element called attachments with one child attachment element per attachment. The attachment element has a body element with the actual attachment.
When a message is received by a proxy service, the message contents are used to initialize the header, body, and attachments variables. For SOAP services, the Header and Body elements are taken directly from the envelope of the received SOAP message and assigned to $header and $body respectively. For non-SOAP services, the entire content of the message is typically wrapped in a Body element (qualified by the SOAP 1.1 namespace) and assigned to $body, and an empty Header element (qualified by the SOAP 1.1 namespace) is assigned to $header.
Binary and MFL messages are initialized differently. For MFL messages, the equivalent XML document is inserted into the Body element that is assigned to $body. For binary messages, the message data is stored internally and a piece of reference XML is inserted into the Body element that is assigned to $body. The reference XML looks like <binary-content ref="..."/>, where "..." contains a unique identifier assigned by the proxy service.
The message context is defined by an XML Schema. You must use XQuery expressions to manipulate the context variables in the message flow that defines a proxy service.
The predefined context variables provided by AquaLogic Service Bus can be grouped into the following types:
For information about the predefined context variables, see Predefined Context Variables.
The $body contains message payload variable. When a message is dispatched from AquaLogic Service Bus you can decide the variables, whose you want to include in the outgoing message. That determination is dependent upon whether the target endpoint is expecting a SOAP or a non-SOAP message:
$body is sent.$body contains the XML equivalent of the MFL document. $body contains the text. For text attachments, the body element in $attachments contains the text. If the contents are XML instead of simple text, the XML is sent as a text message.$body contains the XML. For XML attachments, the body element in $attachments contains the XML.<soap:Envelope> element. (The SOAP 1.1 namespace is used for SOAP 1.1 services, while the SOAP 1.2 namespace is used for SOAP 1.2 services.) If the body variable contains a piece of reference XML, it is sent.That is the referenced content is not substituted in the message.
For non-SOAP services, if the Body element of $body contains a binary-content element, then the referenced content stored internally is sent ‘as is’, regardless of the target service type.
For more information, see Message Context.
The types for the message context variables are defined by the message context schema (MessageContext.xsd). When working with the message context variables in the BEA XQuery Mapper, you need to reference MessageContext.xsd and the transport-specific schemas, which are available in a JAR file at the following location in your AquaLogic Service Bus installation:
<BEA_HOME>\weblogic92\servicebus\lib\sb-schemas.jar
where BEA_HOME represents the directory in which you installed AquaLogic Service Bus.
To learn about the message context schema and the transport specific schemas, see Message Context Schema.
Consider the following guidelines when you want to inspect or alter the message context:
Content-Description of the first attachment in a message: $attachments/ctx:attachment[1]/ctx:content-Description
To obtain the second attachment
$attachments/ctx:attachment[2]/ctx:body/*
idvar, the assign action specification is: assign data($header/wsa:messageID to variable idvar
| Note: | In this case, if two WS-Addressing MessageID headers exist, the idvar variable will be assigned the value of the first one. |
$header, $body, and $attachments are never empty. However, $header can contain an empty SOAP Header element, $body can contain an empty SOAP Body element, and $attachments can contain an empty attachment element.$body) as input to a transformation:
The result of the transformation can be put back in $body with a Replace action. That is replace the content of $body, which is the content of the Body element. For more information, see
XQuery Transformations and
XSL Transformations in Using the AquaLogic Service Bus Console.
$inbound to $outbound. For information on adding an action, see “Adding an Action” in
Proxy Services: Actions in Using the AquaLogic Service Bus Console. For an example, see Copying JMS Properties From Inbound to Outbound.It is assumed that the interfaces of the proxy services and of the invoked business service may be different. Therefore, AquaLogic Service Bus does not propagate any information (such as the transport headers and JMS properties) from the inbound variable to the outbound variable.
The transport headers for the proxy service’s request and response messages are in $inbound and the transport headers for the invoked business service’s request and response are in $outbound.
For example, the following XQuery expression can be used in a case where the user-defined JMS properties for a one-way message (an invocation with no response) need to be copied from inbound message to outbound message:
Use the Transport Headers action to set
$inbound/ctx:transport/ctx:request/tp:headers/tp:user-header ./ctx:transport/ctx:request/tp:headers To learn how to configure the Transport Header action in the AquaLogic Service Bus Console, see “Transport Headers” in Proxy Services: Actions in Using the AquaLogic Service Bus Console.
The following sections describe
AquaLogic Service Bus allows you to import XQueries that have been created with an external tool such as the BEA XQuery Mapper. You can use these XQueries anywhere in the proxy service message flow by binding the XQuery resource input to an Inline XQuery, and binding the XQuery resource output to an action that uses the result as the input; for example, the Assign, Replace, or Insert actions.
However, you can enter the XQuery inline as part of the action definition instead of entering the XQuery as a resource. You can also use Inline XQueries for the condition in an If...Then... action.
The Inline XQuery Expression Editor to enter simple XQueries that consist of the following:
| Note: | For more complex XQueries, it is recommended that you use the XQuery Mapper, especially if you are not familiar with XQuery. |
Inline XQueries can be used effectively to:
$header or $body.$attachments. for loop. for loop with an Update action.| Note: | You can also use the Inline XQuery Expression Editor to create variable structures. For more information, see Using Variable Structures |
You can use the Inline XQuery Expression Editor to create variable structures, with which you define the structure of a given variable for design purposes. For example, it is easier to browse the XPath variable in the console rather than viewing the XML Schema of the XPath variable.
| Note: | It is not necessary to create variable structures for your runtime to work. Variable structures define the structure of the variable or the variable path but do not create the variable. Variables are created at runtime as the target of the Assign action in the stage. |
In a typical programming language, the scope of variables is static. Their name and type are explicitly declared. The variable can be accessed anywhere within the static scope.
In AquaLogic Service Bus, there are some predefined variables, but you can also dynamically create variables and assign value to them using the Assign action or using the loop variable in the for-loop. When a value is assigned to a variable, the variable can be accessed anywhere in the proxy service message flow. The variable type is not declared but the type is essentially the underlying type of the value it contains at any point in time.
| Note: | The scope of the for-loop variable is limited and cannot be accessed outside the stage. |
When you use the Inline XQuery Expression Editor, the XQuery has zero or more inputs and one output. Because you can display the structure of the inputs and the structure of the output visually in the Expression Editor itself, you do not need to open the XML Schema or WSDL resources to see their structure when you create the Inline XQuery. The graphical structure display also enables you to drag and drop simple variable paths along the child axis without predicates, into the composed XQuery.
Each variable structure mapping entry has a label and maps a variable or variable path to one or more structures. The scope of these mappings is the stage or route node. Because variables are not statically typed, a variable can have different structures at different points (or at the same point) in the stage or route node. Therefore, you can map a variable or a variable path to multiple structures, each with a different label. To view the structure, select the corresponding label with a drop-down list.
| Note: | You can also create variable structure mappings in the Inline XPath Expression Editor. However, although the variable or a variable path is mapped to a structure, the XPaths generated when you select from the structure are XPaths relative to the variable. An example of a relative XPath is ./ctx:attachment/ctx:body. |
The following sections describe how to create several types of variable structure mappings:
This sample WSDL is used in most of the examples in this section. You need to save this WSDL as a resource in your configuration. For more information, see Creating the Resources You Need for the Examples.
<definitions
name="samplewsdl"
targetNamespace="http://example.org"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:s0="http://www.bea.com"
xmlns:s1="http://example.org"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
<types>
<xs:schema
attributeFormDefault="unqualified"
elementFormDefault="qualified"
targetNamespace="http://www.bea.com"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="PO" type="s0:POType"/>
<xs:complexType name="POType">
<xs:all>
<xs:element name="id" type="xs:string"/>
<xs:element name="name" type="xs:string"/>
</xs:all>
</xs:complexType>
<xs:element name="Invoice" type="s0:InvoiceType"/>
<xs:complexType name="InvoiceType">
<xs:all>
<xs:element name="id" type="xs:string"/>
<xs:element name="name" type="xs:string"/>
</xs:all>
</xs:complexType>
</xs:schema>
</types>
<message name="POTypeMsg">
<part name="PO" type="s0:POType"/>
</message>
<message name="InvoiceTypeMsg">
<part name="InvReturn" type="s0:InvoiceType"/>
</message>
<portType name="POPortType">
<operation name="GetInvoiceType">
<input message="s1:POTypeMsg"/>
<output message="s1:InvoiceTypeMsg"/>
</operation>
</portType>
<binding name="POBinding" type="s1:POPortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="GetInvoiceType">
<soap:operation soapAction="http://example.com/GetInvoiceType"/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
</binding>
</definitions>
To make use of the examples that follow, you save the sample WSDL as a resource in your configuration and create the sample business service and proxy service that use the sample WSDL.
The tasks in this procedure include:
SampleWSDL. This is a required field.| Note: | This is a required field. |
SampleWSDL is included in the list of resources and saved in the current session. You must now create a proxy service that uses this WSDL, seeCreate a Proxy Service That Uses the Sample WSDL.ProxywithSampleWSDL. This is a required field.ProxywithSampleWSDL is included in the list of resources and saved in the current session.To build message flow for this proxy service, see Build a Message Flow for the Sample Proxy Service.ProxywithSampleWSDL proxy service. ProxywithSampleWSDL icon, then click Add Pipeline Pair. PipelinePairNode1 is displayed, which includes request and response pipelines.ProxywithSampleWSDL proxy service. BusinesswithSampleWSDL. This is a required field.BusinesswithSampleWSDL is included in the list of resources and is saved in the current session.
In this example, you select a predefined variable structure using the proxy service ProxyWithSampleWSDL, which has a service type WSDL Web Service that uses the binding POBinding from SampleWSDL.
The proxy service message flow needs to know the structure of the message in order to manipulate it. To achieve this, AquaLogic Service Bus automatically provides a predefined structure that maps the body variable to the SOAP body structure as defined by the WSDL of the proxy service for all the messages in the interface. This predefined structure mapping is labeled body.
| Note: | This predefined structure is also supported for messaging services with a typed interface. |
To select a predefined variable structure:
In the Variable Structures panel on the XQuery Expression Editor page, select body from the drop-down list of built-in structures.
The variable structure body is displayed as follows:
Suppose the proxy service ProxyWithSampleWSDL invokes a service callout to the business service BusinessWithSampleWSDL, which also has a service type WSDL Web Service that uses the binding POBinding from SampleWSDL. The operation GetInvoiceType is invoked.
In this example, the message flow needs to know the structure of the response parameter in order to manipulate it. To achieve this, you can create a new variable structure that maps the response parameter variable to the type InvoiceType.
InvoiceType as the display name for the variable structure you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at run time.$InvoiceType as the path of the variable at run time.
Suppose a temporary variable has the element Invoice described in the SampleWSDL WSDL. In this example, the ProxyWithSampleWSDL message flow needs to access this variable. To achieve this, you can create a new variable structure that maps the variable to the element Invoice.
To map a variable to an element:
Invoice as the meaningful display name for the variable structure you want to create.$Invoice as the path of the variable structure at run time.SampleWSDL, then select Invoice under Elements in the Select WSDL Definitions pane.
The ProxyWithSampleWSDL proxy service routes to the document style Any SOAP business service that returns the Purchase Order in the SOAP body. In this example, the ProxyWithSampleWSDL proxy service message flow must then manipulate the response. To achieve this, you can create a new structure that maps the body variable to the PO element, and specify the PO element as a child element of the variable. You need to specify it as a child element because the body variable contains the SOAP Body element and the PO element is a child of the Body element.
To map a variable to a child element:
body to PO as the meaningful display name for the variable structure you want to create.$body as the path of the variable structure at run time.PO element: PO element as a child of the body to PO variable structure.
The ProxyWithSampleWSDL proxy service routes the message to the BusinessWithSampleWSDL business service, which also has a service type WSDL Web Service that uses the binding POBinding from SampleWSDL. In this example, the message flow must then manipulate the response. To achieve this, you can define a new structure that maps the body variable to the BusinessWithSampleWSDL business service. This results in a map of the body variable to the SOAP body for all the messages in the WSDL interface of the service.
| Note: | This mapping is also supported for messaging services with a typed interface. |
To map a variable to a business service:
BusinessService as the meaningful display name for the variable structure.$body is already set as the default. This is the path of the variable structure at run time.BusinessService is included under Service Interface in the drop-down list of variable structures.
The variable structure BusinessService is displayed as shown below:
Modify the SampleWSDL so that the ProxyWithSampleWSDL proxy service receives a single attachment. The attachment is a Purchase Order. In this example, the proxy service message flow must then manipulate the Purchase Order. To achieve this, you can define a new structure that maps the body element in $attachments to the PO element, which is specified as a child element. The body element is specified as a variable path of the form:
$attachments/ctx:attachment/ctx:body You can select and copy the body element from the predefined attachments structure, paste this element as the variable path to be mapped in the new mapping definition.
To map a child element to another child element:
The variable structure attachments is displayed as follows:
body child element in the attachments structure. The variable path of the body element is displayed in the Property Inspector on the right side of the page: $attachments/ctx:attachment/ctx:bodybody element.PO attachment as the meaningful display name for this variable structure.$attachments/ctx:attachment/ctx:bodyThis is the path of the variable structure at run time.
PO element: PO attachment is included under XML Type in the drop-down list of variable structures.
The following sections discuss quality of service features in AquaLogic Service Bus messaging:
BEA AquaLogic Service Bus supports reliable messaging. The value of the qualityOfService element in the outbound context variable provides AquaLogic Service Bus with a hint on the desired delivery behavior. When messages are routed to another service from a route node, the default Quality of Service element in $outbound is either exactly-once or best-effort.
The following delivery guarantee types are provided in AquaLogic Service Bus:
You can override the default qualityOfService element attribute for the following:
To override the qualityOfService element attribute, you must use the Route Options action to route or publish, and also select the checkbox for a service callout action. See Message Context Schema.
The delivery guarantee supported when a proxy service publishes a message or routes a request to a business service depends on the following conditions:
However, if the inbound proxy service is a Local Transport and is invoked by another proxy service, the inbound transport of the invoking proxy service is responsible for the delivery guarantee. That is because a proxy service that invokes another proxy service is optimized into a direct invocation if the transport of the invoked proxy service is a Local Transport. For more information on transport protocols, see “Adding a Proxy Service” and “Adding a Business Service” in Proxy Services in Using the AquaLogic Service Bus Console.
| Note: | No delivery guarantee is provided for responses from a proxy service. |
The following rules govern delivery guarantees:
| Note: | To support at least once and exactly-once delivery guarantees with JMS, you must exploit JMS transactions and configure a retry count and retry interval on the JMS queue to ensure that the message is redelivered in the event of a server crash or a failure that is not handled in an error handler with a Reply or Resume action. File, FTP, and e-mail transports also internally use a JMS/XA queue. The default retry count for a proxy service with a JMS/XA transport is 1. For a list of the default JMS queues created by AquaLogic Service Bus, see AquaLogic Service Bus Deployment Guide. |
The following are some more delivery guarantee rules:
qualityOfService element is set to exactly-once, any Route node and Publish actions executed in the request flow to a transactional destination are performed in the same transaction.qualityOfService element is set to best-effort for any action in a Route node, Service Callout or Publish actions are executed outside of the request flow transaction. Specifically, for JMS, Tuxedo, Transactional Tuxedo, or EJB transport, the request flow transaction is suspended and the Transactional Tuxedo work is done without a transaction or in a separate transaction that is immediately committed.qualityOfService element is set to exactly-once, all Route, Service Callout, and Publish actions are performed in the same transaction. qualityOfService element is set to best-effort, all Publish actions and Service Callout actions are executed outside of the response flow transaction. Specifically, for JMS, EJB, or transactional Tuxedo types of transports, the response flow transaction is suspended and the service is invoked without a transaction or in a separate transaction that is immediately committed.qualityOfService element setting.| Note: | You will encounter a run-time error when the inbound transport is transactional Tuxedo and the outbound is an asynchronous transport, for example, JMS/XA. |
The BEA AquaLogic Service Bus threading model works as follows:
qualityOfService element is best-effort. | Note: | In a request or response flow Publish action, responses are always discarded because Publish actions are inherently a one-way message send. |
You may want to split a proxy service in the following situations:
loanGateway1 invokes another proxy service, say loanGateway2. Route to the proxy service loanGateway2 from the proxy service loanGateway1 where the proxy service loanGateway2 uses JMS transport.qualityOfService element of exactly-once and uses an XA connection factory.In addition to configuring inbound retries for messages using JMS, you can configure outbound retries and load balancing. Load balancing, failover, and retries work in conjunction to provide performance and high availability. For each message, the list of URLs you provide as failover URLs is automatically ordered based on the load balancing algorithm into a failover sequence. If the retry count is N, the entire sequence is retried N times before stopping. The system waits for the specified retry interval before commencing subsequent loops through the sequence. After completing the retry attempts, if there is still an error, the error handler pipeline for the route node is invoked. For more information on the error handler pipeline, see “Adding Pipeline Error Handling” in Proxy Services in Using the AquaLogic Service Bus Console.
| Note: | For HTTP and HTTP(S) transports, any HTTP status other than 200 or 202 is considered an error by AquaLogic Service Bus and must be retried. Because of this algorithm, it is possible that AquaLogic Service Bus retries errors like authentication failure that may never be rectified for that URL within the time period of interest. On the other hand, if AquaLogic Service Bus also fails over to a different URL for subsequent attempts to send a given message, the new URL may not give the error. |
| Note: | For quality of service=exactly once failover or retries will not be executed. |
To support interoperability with heterogeneous endpoints, AquaLogic Service Bus allows you to control the content type used, the JMS type used, and the encoding used.
AquaLogic Service Bus does not make assumptions about what the external client or service needs, and uses the information configured for this purpose in the service definition. AquaLogic Service Bus derives the content type for outbound messages from the service type and interface. Content type is a part of the e-mail and HTTP(S) protocols.
Additionally, there is a JMS type, which can be byte or text. You configure the JMS type to use when you define the service in AquaLogic Service Bus Console.
You can override the content type in the outbound context variable ($outbound) for proxy services invoking a service, and in the inbound context variable ($inbound) for a proxy service response. For more information on $outbound and $inbound context variables, see Inbound and Outbound Variables.
Encoding is also explicitly configured in the service definition for all outbound messages. For more information on service definitions, see Adding a Proxy Service in and Adding a Business Service in Using the AquaLogic Service Bus Console.
A throttling pattern is typically used with an HTTP Web service to restrict the degree of concurrency, that is to keep the number of outstanding requests without a response below a limit. Instead of accessing the business service directly, you access the business service through another proxy service. This proxy service typically uses the JMS one-way transport or JMS request response transport to communicate with the business service.You should define a work manager for the JMS request queue. For more information on defining a work manager, see Work Manager. Configure the work manager to have the maximum number of threads. This restricts the number of requests that can be placed in the request queue. That is no requests can be placed in the queue if the number of incoming request exceeds the maximum number of threads configured in the work manager.
| Note: | Set the qualityOfService of the business service $outbound to Exactly Once.You can use the Routing Options action to set the required qualityOfService. For more information, see
Routing Options Using the AquaLogic Service Bus Console. |
| Note: | When a throttling pattern is implemented in a cluster, the total number of requests across all the Managed Servers should be equal to maximum number of threads on the work manager / number of managed servers |
BEA AquaLogic Service Bus provides Web Service Interoperability (WS-I) compliance for SOAP 1.1 services in the run-time environment. The WS-I basic profile has the following goals:
The WS-I basic profile is available at the following URL:
http://www.ws-i.org/Profiles/BasicProfile-1.1.html.
When you configure a proxy service or business service based on a WSDL, you can use the AquaLogic Service Bus Console to specify whether you want AquaLogic Service Bus to enforce WS-I compliance for the service. For more information on how to do this, see “Adding a Proxy Service” in Proxy Services in Using the AquaLogic Service Bus Console.
When you configure WS-I compliance for a proxy service, checks are performed on inbound request messages received by that proxy service. When you configure WS-I compliance for an invoked service, checks are performed when any proxy receives a response message from that invoked service. BEA recommends that you create an error handler for these errors, since by default, the proxy service SOAP client receives a system error handler-defined fault. For more information on creating fault handlers, see “Error Messages and Handling” in Proxy Services in Using the AquaLogic Service Bus Console.
For messages sent from a proxy service, whether as outbound request or inbound response, WS-I compliance checks are not explicitly performed. That is because the pipeline designer is responsible for generating most of the message content. However, the parts of the message generated by AquaLogic Service Bus should satisfy all of the supported WS-I compliance checks. This includes the following content:
The Enforce WS-I Compliance checkbox is displayed as shown in Figure 2-15:
| Note: | WS-I compliance checks require that the system knows what operation is being invoked on a service. For request messages received by a proxy service, that means that the context variable $operation should not be null. That depends upon the operation selection algorithm being configured properly. For response messages received from invoked services, the operation should be specified in the action configurations for Route, Publish, and Service Callout. |
When you configure WS-I compliance checking for a proxy service or a business service, AquaLogic Service Bus carries out the following checks.
R1113 An instance should use a “
400 Bad Request” HTTP status code if a HTTP request message is malformed.
|
||
AquaLogic Service Bus supports SOAP 1.1 and SOAP 1.2. A SOAP 1.1 proxy service can invoke a SOAP 1.2 business service or vice versa. The SOAP namespace is automatically changed by AquaLogic Service Bus before invoking the business service. If a fault comes back from the business service it is automatically changed to the SOAP version of the proxy service. It is, however, up to the pipeline actions to map the SOAP header-related XML attributes (like MustUnderstand) between the two versions. It is also up to the pipeline actions to change the SOAP encoded name space for encoded envelopes.
|