Skip navigation.

User Guide

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Modeling Message Flow in AquaLogic Service Bus

In BEA AquaLogic Service Bus, Message Flow defines the implementation of a proxy service. This section presents some guidelines to follow when you model message flows in AquaLogic Service Bus. Configuration of AquaLogic Service Bus is performed in the AquaLogic Service Bus Console, which is described in the Using the AquaLogic Service Bus Console.

This section includes the following topics:

 


About AquaLogic Service Bus Message Flow

Message Flows are the definitions of AquaLogic Service Bus proxy services. Pipelines, branch nodes, and route nodes define the implementation of AquaLogic Service Bus proxy services. Using the AquaLogic Service Bus Console, you 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 followng figure shows a high level view of the components of the message flow definition.

Figure 2-1 Components of Message Flows

Components of Message Flows


 

This topic includes the following sections:

Building a Message Flow

Any element may appear at the root of the message flow. One of the simplest of message flow designs is to have only a route node representing the entire flow. There is also no restriction on what two elements you can chain together. For example, two pipeline pair nodes can be chained together without a branch node in between. With regards to branching, each branch 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 come in two forms:

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

Table 2-1 Message Flow Components

Node Type

Summary

Pipeline Pair

See Pipelines.

A pipeline pair ties together a single request and a single response pipeline into one top-level element. A pipeline pair node can have only 1 direct descendant in the message flow. During request processing, only the request pipeline is executed when visiting a pipeline pair node. When reversing the path for response processing, only the response pipeline is executed.

See Table 2-3 for a simple pipeline pair node.

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 enables processing to proceed down 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 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, which is always present, 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 the Using the AquaLogic Service Bus Console.

For information about working with the message context variables to design conditions, see Message Context in the Using the AquaLogic Service Bus Console.

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.

As the 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 learn how 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 demonstrates the path of a message in a typical message flow.

Table 2-2 Path of a Message Through a Message Flow

Message Flow Node

What Happens to 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: Whether or not any routing is performed, the route node represents the change over from request processing to response processing. When a response comes in, the message processing proceeds along the reverses path it took for the request. The same thing occurs for any request path that ends without a route node—that is, without waiting for any response in this case, response processing is initiated.

Response Processing


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

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

Pipelines are typed into one of three categories:

To create the request and response paths, request and response pipelines are paired and organized into a single node called a pipeline pair node.

The following figure shows an example of a simple message flow. It defines a proxy service named loanGateway3.

Figure 2-2 Message Flow Definition for a Proxy Service

Message Flow Definition for a Proxy Service


 

The message flow in the preceding figure shows:

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.

Figure 2-3 Message Flow Definition for a Proxy Service

Message Flow Definition for a Proxy Service


 

To view or edit the components of the message flow, you can click the component in either the graphical message flow view or the map (tree) view.

This flow structure provides a clear overview of the message flow behavior in 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. To learn more 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. This section details the situations in which to use operational branching and the ones in which you can use conditional branching.

Operational Branching

When message flows define Web Services Description Language (WSDL)-based proxy services, there is frequently a need to perform processing that is operation-specific. Rather than requiring you to manually configure a branching node based on operation, AquaLogic Service Bus provides a minimal configuration branching node that automatically branches based on operation. In other words, when you create an operational branch node in a message flow, a shown in Figure 2-4, 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-5).

Figure 2-4 Add Branch

Add Branch


 

Figure 2-5 Definition for an Operation Branch

Definition for an Operation Branch


 

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.

Use operational branching to handle messages separately for each operation in situations where a proxy service is based on a WSDL with multiple operations. However, if the proxy service is not based on a WSDL and receives multiple document types, consider using a conditional branching node.

Conditional Branching

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. Setting the value of the lookup variable must be done before reaching the branch node.

Take for example, a scenario in which a proxy service is of type Any SOAP or Any XML, and you need to determine what the message type is so that you can perform conditional branching. You can use a stage action to identify the message type and use a conditional branching node in the flow to separate processing based on the message type received.

In this case, when you create a conditional branch node in a message flow, you build your branching logic based on evaluation of the value of the variable populated in the preceding stage.

To learn how to configure operational 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 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.

The following figure 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.

Figure 2-6 Top-Level Branch Node

Top-Level Branch Node


 

To learn about configuring conditional branching 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 become awkward in the design interface if the number of branches that extend from the branch node is large.

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 using XQuery and the eXtensible Stylesheet Language Transformation (XSLT) standard. 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:

If the message format you need to transform to or from depends on the target service(s), you must perform the transformation in a route action or publish action. In the case of transformations 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 only affect 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. It is important to understand the scope of the message context information in publish actions and route nodes. For more information, see Proxy Services: Actions and Message Context in Using the AquaLogic Service Bus Console.

Take for example a scenario in which the message flow deals with a large purchase order, for which it is necessary to send a summary of the purchase order, via email, to a manager. A summary can be created that details the salient aspects of the purchase order in the SOAP body of the incoming message by including a publish action in the request pipeline. In the publish action, the purchase order data can be transformed into a summary order—for example, all the attachments in $attachments can be deleted because they are not required in the summary order.

Another example is a situation in which you need to route messages to one of two possible destinations, based on a WS-addressing header—content-based routing. In addition, the second destination requires that the document in the SOAP body be transformed to a newer version. 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 in the Using the AquaLogic Service Bus Console for information about the subelements of the inbound and outbound variables and how the content of messages is constructed using the values of the variables in the message context.

For more information about:

 


Configuring Single or 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. This section outlines some of the reasons why you might use multiple stages in a pipeline. For information about configuring a stage, see "Adding a Stage" in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

The tasks performed by actions in message flows includes (specific information about creating and configuring any action in a message flow is available in Proxy Services: Actions in Using the AquaLogic Service Bus Console.information):

Using Multiple Stages

Consider the following characteristics of stages and actions to help you decide between designing multiple stages or configuring a single stage with multiple actions:

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

 


Handling Errors

This section presents a brief overview of how to handle errors and outlines some guidelines to consider when configuring your error handling options.

Each stage can have a sequence of steps to execute if an error occurs in that stage. This sequence of steps constitute an error pipeline for that stage. In addition, an error pipeline can be defined for a pipeline (request or response) or for an entire proxy service. The lowest scoped error pipeline that exists is invoked on an error.

Figure 2-7 Stage, Node, and Service-Level Error Handlers

Stage, Node, and Service-Level Error Handlers


 

For a more detailed explanation of error messages and handling, see "Error Messages and Handling" in Proxy Services: Error Handlers in the Using the AquaLogic Service Bus Console.

You can handle errors in the following ways:

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. To learn more about $fault, see "Predefined Context Variables" in Message Context in Using the AquaLogic Service Bus Console.

In general, it is easier to handle specific errors at the lowest level of the message flow and use higher level error handlers 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. However, if you decide to handle anticipated errors in the pipelines, you can only handle WS-Security related errors at the service level.

Generating the Error Message, Reporting, and Replying

In the event of errors for request/response type inbound messages, it is often necessary to generate a message that is sent back to the originator outlining the reason why an error occurred. You can accomplish this using a reply with failure action after configuring the message context variables with the response you want to send. For example, when a 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 the 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

This example shows how the Report and Reply actions can be configured 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:

Figure 2-8 Error Handler Message Flow

Error Handler Message Flow


 

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

Figure 2-9 Actions in Stage Error Handler

Actions in Stage Error Handler


 

The actions specify the behavior of the stage error handler as follows:

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.

AquaLogic Service Bus service types include:

Note: All service types can send and receive attachments using MIME.

The following table shows the service types and the transports on which they are supported by AquaLogic Service Bus.

Table 2-3 Supported Service Types and Transports

Service Type

Transport Protocols

SOAP or XML WSDL

JMS

HTTP(S)

SOAP (no WSDL)

JMS

HTTP(S)

XML (no WSDL)1

HTTP(S)

JMS

Email

File

FTP

Messaging Type (Binary, Text, MFL, XML)

HTTP(S)

JMS

Email

File

FTP


1. HTTP GET is only supported for XML with no WSDL.


 

Use 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 WDSL to define the service. For more WSDL information, see WSDLs in Using the AquaLogic Service Bus Console.

The benefits of using a WSDL in this situation include:

Choosing a WSDL Port or Binding?

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

You can get the WSDL for an HTTP(S)-based proxy service by entering the URL for the service appended with ?WSDL in your browser's Address field.

In the WSDL generated with the ?WSDL syntax, 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 client generation tools. The URL in the WSDL port bound to the service is not used during service definition, 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. For more information, see "Overview of Proxy Services" in Proxy Services in Using the AquaLogic Service Bus Console.

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.

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 "mistunderstand" 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 the Using the AquaLogic Service Bus Console. For more information on XQuery conditional expressions, see "Using the XQuery Condition Editor" in Proxy Services: Editors in the Using the AquaLogic Service Bus Console.

AquaLogic Service Bus does not automatically validate the message sent or received against the service interface definition, whether it is a WSDL definition or a messaging interface definition. However, you can 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 the Using the AquaLogic Service Bus Console.

 


Dynamic Routing

For a scenario in which you are designing a proxy service but you do not know the concrete service to invoke from that service, but you do know the shape of the interface, you can specify the service to be invoked directly or indirectly in the request message.

Note: The shape of a service refers to the abstract interface: namely message types, port types, and binding, and excludes the concrete interface. The concrete interface is the transport URL at which the service is located.

In this case, register a business service with the right shape (the transport URL does not matter). You can override the service URL by configuring $outbound with the URL of the service to invoke. In this way, the URL can be supplied at run time and the need to know it when you design and configure your service is eliminated.

 


Message Context

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.

$header contains a SOAP Header element, $body contains a SOAP Body element, and $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 message contents are typically wrapped in a Body element and assigned to $body, and an empty Header element is assigned to $header.

Binary and MFL messages are initialized differently. For MFL messages, the equivalent XML document is injected 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 injected into the Body element that is assigned to $body. The reference XML looks like <binary-content ref="..."/>, where "..." contains an unique identifier assigned by the proxy.

The message context is defined by an XML Schema. You typically 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" in Message Context in Using the AquaLogic Service Bus Console.

The message payload is contained in the body variable. The decision about which variable's content to include in an outgoing message is made at the point at which a message is dispatched from AquaLogic Service Bus. That determination is dependent upon whether the target endpoint is expecting a SOAP or a non-SOAP 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 in the Using the AquaLogic Service Bus Console.

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\weblogic90\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" in Message Context in the Using the AquaLogic Service Bus Console.

Key Context Manipulation Facts

Consider the following guidelines when you want to inspect or alter the message context:

Copying JMS Properties From Inbound to Outbound

AquaLogic Service Bus assumes that the interface of the proxy services and the invoked business service may be different. Therefore, it does not propagate any information (like 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 to outbound:

Use the Transport Headers action to set

$inbound/ctx:transport/ctx:request/tp:headers/tp:user-header 

as the first child of:

./ctx:transport/ctx:request/tp:headers 

in the outbound variable.

To learn how to configure the Transport Header action in the AquaLogic Service Bus Console, see "Transport Headers" in Proxy Services: Actions in the Using the AquaLogic Service Bus Console.

 


RPC and Document Style SOAP

AquaLogic Service Bus supports Remote Procedure Calls (RPC) style SOAP and document style SOAP. For more information, see:

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.

Listing 2-1 WSDL for a Sample RPC Style Web Service

<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-2 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.

Listing 2-2 Body Variable Value

<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 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-2, the value for the body variable ($body), shown in Listing 2-3, 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.

Listing 2-3 Body Variable Value

<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's 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. Such Java classes are used to invoke the proxy services that use this WSDL.

Document Style SOAP

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.

Listing 2-4 WSDL for a Sample Document Style Web Service

<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 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.

Listing 2-5 Body Variable Value

<soap-env:Body>
  <req:PurchaseOrg>BEA Systems</req:PurchaseOrg>
<soap-env:Body>

Where soap-env is the predefined SOAP name space 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.

Listing 2-6 Body Variable Value

<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's 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.

 


Variable Structures

This section includes the following topics:

Using the Inline XQuery Expression Editor

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 action 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.

You typically use the Inline XQuery Expression Editor to enter simple XQueries that consist of the following:

Note: For more complex XQueries, we recommend that you use the XQuery Mapper, especially if you are not familiar with XQuery.

Examples of good uses of Inline XQueries are:

Note: You can use the Inline XQuery Expression Editor to create variable structures. To learn more, see Using Variable Structures.

Using Variable Structures

You can use the Inline XQuery Expression Editor to create variable structures, which you can use to attach or define the structure of a given variable for design purposes (for example, an easy-to-create XPath, understanding what the variable is about, the ability to browse the structure in the Console rather than viewing the XML Schema).

Note: It is not necessary to create variable structures for your runtime to work.

In a typical programming language, variables are statically scoped and their name and type is explicitly declared. The variable can be accessed anywhere within the static scope.

In AquaLogic Service Bus, some predefined variables do exist, but you can also dynamically create variables by assigning a value to them. 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.

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 XQuery being composed.

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 to multiple structures, each with a different label. To view the structure, you can 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 is mapped to a structure, the XPaths generated when you select from the structure are relative XPaths relative to the variable. An example of a relative XPath is ./ctx:attachment/ctx:body. However, the mapping used to generate this XPath would map $attachments.

Using Variable Structure Mappings

This section includes the following topics:

Sample WSDL

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. To learn more, see Creating the Resources You Need for the Examples.

Listing 2-7 Sample WSDL

<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>

Creating the Resources You Need for the Examples

To make use of the examples that follow, you need to save the sample WSDL as a resource in your configuration, and you need to create the sample business and proxy services that use the sample WSDL.

The tasks in this procedure include:

To Save the WSDL as a Resource

  1. If you have not already done so, from the left navigation pane in the AquaLogic Service Bus Console, under Change Center, click Create to create a new session for making changes to the current configuration.
  2. From the left navigation pane, select Project Explorer. The Project View page is displayed.
  3. Select the project to which you want to add the WSDL.
  4. From the Project View page, in the Create Resource field, select WSDL from under Interface. The Create a New WSDL Resource page is displayed.
  5. In the Resource Name field, enter SampleWSDL. This is a required field.
  6. In the WSDL field, copy and paste the text from the sample WSDL into this field.
  7. Note: This is a required field.

  8. To save the WSDL, click Save. The new WSDL SampleWSDL is included in the list of resources and is saved in the current session. You must now create a proxy service that uses this WSDL—continue in To Create a Proxy Service that Uses the Sample WSDL.

To Create a Proxy Service that Uses the Sample WSDL

  1. From the left navigation pane, select Project Explorer. The Project View page is displayed.
  2. Select the project to which you want to add the proxy service.
  3. From the Project View page, in the Create Resource field, select Proxy Service from under Service. The Edit a Proxy Service - General Configuration page is displayed.
  4. In the Service Name field, enter ProxywithSampleWSDL. This is a required field.
  5. In the Service Type field, which defines the types and packaging of the messages exchanged by the service, do the following:
    1. Select WSDL binding from under Create a New Service.
    2. Click Browse. The WSDL Browser is displayed.
    3. Select SampleWSDL, then select POBinding in the Select WSDL Definitions pane.
    4. Click Submit.
  6. Use the defaults for all other fields on the General Configuration page, then click Next.
  7. Use the defaults for all fields on the Transport Configuration pages, then click Next.
  8. On the Operation Selection Configuration page, make sure SOAP Body Type is selected in the Selection Algorithm field, then click Next.
  9. Review the configuration data that you have entered for this proxy service, then click Save. The new proxy service ProxywithSampleWSDL is included in the list of resources and is saved in the current session. You must now build message flow for this proxy service—continue in To Build Message Flow for the Sample Proxy Service.

To Build Message Flow for the Sample Proxy Service

  1. On the Project View page, in the Actions column, click the Edit Message Flow icon for the ProxywithSampleWSDL proxy service. The Edit Message Flow page is displayed.
  2. Click the ProxywithSampleWSDL icon, then click Add Pipeline Pair. PipelinePairNode1 is displayed, which includes request and response pipelines.
  3. Click the request pipeline, then click Add Stage. The stage stage1 is displayed.
  4. Click Save. The basic message flow is created for the ProxywithSampleWSDL proxy service.
  5. When you work with the examples, you must edit the stage to access the Edit Stage Configuration page, then add an action that uses an expression to access the XQuery Expression Editor page. First, you must create a business service that uses SampleWSDL—continue in To Create a Business Service that Uses the Sample WSDL.

To Create a Business Service that Uses the Sample WSDL

  1. From the left navigation pane, select Project Explorer. The Project View page is displayed.
  2. Select the project to which you want to add the business service.
  3. From the Project View page, in the Create Resource field, select Business Service from under Service. The Edit a Business Service - General Configuration page is displayed.
  4. In the Service Name field, enter BusinesswithSampleWSDL. This is a required field.
  5. In the Service Type field, which defines the types and packaging of the messages exchanged by the service, do the following:
    1. Select WSDL binding from under Create a New Service.
    2. Click Browse. The WSDL Browser is displayed.
    3. Select SampleWSDL, then select POBinding in the Select WSDL Definitions pane.
    4. Click Submit.
  6. Use the defaults for all other fields on the General Configuration page, then click Next.
  7. Use the defaults for all fields on the Transport Configuration and SOAP Binding Configuration pages, then click Next.
  8. Review the configuration data that you have entered for this business service, then click Save. The new business service BusinesswithSampleWSDL is included in the list of resources and is saved in the current session.
  9. From the left navigation pane, click Activate under Change Center. The session ends and the configuration is deployed to run time. You are now ready to use the examples—continue in Example 1: Selecting a Predefined Variable Structure.

Example 1: Selecting a Predefined Variable Structure

Suppose the proxy service ProxyWithSampleWSDL has a service type WSDL binding that uses the binding POBinding from SampleWSDL.

In this example, the proxy service message flow needs to know the structure of the message to manipulate it. To achieve this, AquaLogic Service Bus automatically provides a predefined structure that maps the body variable to the SOAP body for all the messages in the interface. This predefined structure mapping is labelled body.

Note: This predefined structure is also supported for messaging services with a typed interface.

To Select a Predefined Variable Structure

Example 2: Creating a Variable Structure that Maps a Variable to a Type

Suppose the proxy service ProxyWithSampleWSDL invokes a service callout to the business service BusinessWithSampleWSDL, which also has a service type WSDL binding 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 to manipulate it. To achieve this, you can create a new variable structure that maps the response parameter variable to the type InvoiceType.

To Map a Variable to a Type

  1. In the Variable Structures panel, click Add New Structure. Additional fields are displayed as follows:
  2. Figure 2-11 Variable Structures—Add a New Structure

    Variable Structures—Add a New Structure


     
  3. Make sure XML Type is selected.
  4. In the Structure Label field, enter 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.
  5. In the Structure Path field, enter $InvoiceType as the path of the variable structure at run time.
  6. To select the type InvoiceType, do the following:
    1. Under the Type field, select the appropriate radio button, then select WSDL Type.
    2. Click Browse. The WSDL Browser is displayed.
    3. In the WSDL Browser, select SampleWSDL, then select InvoiceType under Types in the Select WSDL Definitions pane.
    4. Click Submit. InvoiceType is displayed under your selection WSDL Type.
  7. Click Add. The new variable structure InvoiceType is included under XML Type in the drop-down list of variable structures.
  8. The variable structure InvoiceType is displayed as follows:

    Figure 2-12 Variable Structures—InvoiceType

    Variable Structures—InvoiceType


     

Example 3: Creating a Variable Structure that Maps a Variable to an Element

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

  1. In the Variable Structures panel, click Add New Structure.
  2. Make sure XML Type is selected.
  3. In the Structure Label field, enter Invoice as the meaningful display name for the variable structure you want to create.
  4. In the Structure Path field, enter $Invoice as the path of the variable structure at run time.
  5. To select the element Invoice, do the following:
    1. Under the Type field, make sure the appropriate radio button is selected, then select WSDL Element.
    2. Click Browse. The WSDL Browser is displayed.
    3. In the WSDL Browser, select SampleWSDL, then select Invoice under Elements in the Select WSDL Definitions pane.
    4. Click Submit. Invoice is displayed under your selection WSDL Element.
  6. Click Add. The new variable structure Invoice is included under XML Type in the drop-down list of variable structures.
  7. The variable structure Invoice is displayed as follows:

    Figure 2-13 Variable Structures—Invoice

    Variable Structures—Invoice


     

Example 4: Creating a Variable Structure that Maps a Variable to a Child Element

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

  1. In the Variable Structures panel, click Add New Structure.
  2. Make sure XML Type is selected.
  3. In the Structure Label field, enter body to PO as the meaningful display name for the variable stucture you want to create.
  4. In the Structure Path field, enter $body as the path of the variable structure at run time.
  5. To select the PO element, do the following:
    1. Under the Type field, make sure the appropriate radio button is selected, then select WSDL Element.
    2. Click Browse. The WSDL Browser is displayed.
    3. In the WSDL Browser, select SampleWSDL, then select PO under Elements in the Select WSDL Definitions pane.
    4. Click Submit.
  6. Select the Set as child checkbox to set the PO element as a child of the body to PO variable structure.
  7. Click Add. The new variable structure body to PO is included under XML Type in the drop-down list of variable structures.
  8. The variable structure body to PO is displayed as follows:

    Figure 2-14 Variable Structures—body to PO

    Variable Structures—body to PO


     

Example 5: Creating a Variable Structure that Maps a Variable to a Business Service

The ProxyWithSampleWSDL proxy service routes to the BusinessWithSampleWSDL business service, which also has a service type WSDL binding 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 interface.

Note: This mapping is also supported for messaging services with a typed interface.

To Map a Variable to a Business Service

  1. In the Variable Structures panel, click Add New Structure.
  2. Select Service Interface.
  3. In the Structure Label field, enter BusinessService as the meaningful display name for the variable structure.
  4. In the Structure Path field, $body is already set as the default. This is the path of the variable structure at run time.
  5. To select the business service, do the following:
    1. Under the Service field, click Browse. The Service Browser is displayed.
    2. In the Service Browser, select the BusinessWithSampleWSDL business service, then click Submit. The business service is displayed under the Service field.
    3. In the Operation field, select All.
  6. Click Add. The new variable structure BusinessService is included under Service Interface in the drop-down list of variable structures.
  7. The variable structure BusinessService is displayed as follows:

    Figure 2-15 Variable Structures—BusinessService

    Variable Structures—BusinessService


     

Example 6: Creating a Variable Structure that Maps a Child Element to Another Child Element

Suppose you 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, then modify the pasted value to add the predicate.

To Map a Child Element to Another Child Element

  1. In the Variable Structures panel, select attachments from the drop-down list of built-in structures.
  2. The variable structure attachments is displayed as follows:

    Figure 2-16 Variable Structures—attachments

    Variable Structures—attachments


     
  3. Select the body child element in the attachments structure. The contents of body are displayed in the Property Inspector on the right side of the page:
  4. $attachments/ctx:attachment/ctx:body
  5. Copy the contents of the body element.
  6. In the Variable Structures panel, click Add New Structure.
  7. Make sure XML Type is selected.
  8. In the Structure Label field, enter PO attachment as the meaningful display name for this variable structure.
  9. In the Structure Path field, paste the contents of the body element:
  10. $attachments/ctx:attachment/ctx:body

    This is the path of the variable structure at run time.

  11. To select the PO element, do the following:
    1. Under the Type field, make sure the appropriate radio button is selected, then select WSDL Element.
    2. Click Browse. The WSDL Browser is displayed.
    3. In the WSDL Browser, select SampleWSDL, then select PO under Elements in the Select WSDL Definitions pane.
    4. Click Submit.
  12. Select the Set as child checkbox to set the PO element as a child of the body element.
  13. Click Add. The new variable structure second attachment is included under XML Type in the drop-down list of variable structures.
  14. If there can be multiple attachments, you'll need to add an index to the reference when you use fields from this structured variable in your XQueries. For example, if you drag the PO field to the XQuery Text box, but the PO will be the second attachment, you'll need to change the inserted value
  15. $attachments/ctx:attachment/ctx:body/bea:PO/bea:id

    to

    $attachments/ctx:attachment[2]/ctx:body/bea:PO/bea:id

 


Quality of Service

This section includes the following topics:

Delivery Guarantees

BEA AquaLogic Service Bus supports reliable messaging. When messages are routed to another service from a route node, the default quality of service (QoS) element in $outbound is either exactly-once or best-effort. The value of the qualityOfService element in the outbound context variable provides AquaLogic Service Bus with a hint on the desired delivery behavior. The value of the qualityOfService element is used only for a proxy service's outbound transport in the case of HTTP, HTTPS, or JMS transports.

The folllowing is the list of delivery guarantee types provided:

Table 2-4 Delivery Guarantee Types


 

Delivery Reliability

Description

Exactly once

Exactly once means reliability is optimized. Exactly once delivery reliability is a hint, not a directive. When exactly once is specified, exactly once reliability is provided if possible.

The default value of the qualityOfService element is exactly-once for a Route Node action if the proxy service inbound transport is as follows:

  • Email

  • FTP

  • File

  • JMS/XA

At least once

At least once delivery semantics are attempted if exactly once is not possible but the qualityOfService element is exactly-once.

Best effort

Best effort delivery is performed if exactly once and at least once delivery semantics are not possible but the qualityOfService element is exactly-once.. Best effort means that performance or availability is optimized.

The default value of the qualityOfService element is best-effort for the following inbound transports:

  • JMS/nonXA

  • HTTP

  • HTTPS

The default value of the qualityOfService element is best-effort for the following:

  • Service callout action — always best-effort, not modifiable

  • Publish action — defaults to best effort, modifiable

  • Route action — defaults to $inbound QoS, modifiable

  • Proxy service response message — always exactly once where applicable, not modifiable

Note: When the value of the qualityOfService element is best-effort for a Publish action, all errors are ignored. However, when the value of the qualityOfService element is best-effort for a Route Node action or a Service callout action, any error will raise an exception.


 

Overriding the Default Element Attribute

You can override the default qualityOfService element attribute for the following:

Note: You cannot override the qualityOfService element attribute for a Service callout action.

To override the qualityOfService element attribute, you must set the qualityOfService in the outbound message context variable ($outbound). For more information, see "Message Context Schema" in Message Context in Using the AquaLogic Service Bus Console.

Delivery Guarantee Rules

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 not JMS and the invoker is another proxy service, the inbound transport of the invoking proxy service is responsible for the delivery guarantee. This 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 not JMS. For more information on transport protocols, see "Adding a Proxy Service" and "Adding a Business Service" in Proxy Services in the Using the AquaLogic Service Bus Console.

Note: No delivery guarantee is provided for responses from a proxy service.

The following rules govern delivery guarantees:

Table 2-5 Delivery Guarantee Rules

Delivery Guarantee Provided

Rule

Exactly once

The proxy service inbound transport is JMS/XA and the value of the qualityOfService element is exactly-once to an outbound JMS/XA transport

At least once

The proxy service inbound transport is file, FTP, or email and the value of the qualityOfService element is exactly-once

At least once

The proxy service inbound transport is JMS/XA and the value of the qualityOfService element, where applicable, is exactly once to an outbound transport that is not JMS/XA,

No delivery guarantee

All other cases, including all response processing cases


 

Note: To support at least once and exactly once delivery guarantees, you must exploit JMS transactions and configure a retry count and retry interval on the JMS queue to ensure 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 email 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 the BEA AquaLogic Service Bus Deployment Guide.

Here are some more delivery guarantee rules:

The guarantee of delivering the message at least once for HTTP and HTTPS requires further explanation. It is assumed that the delivery completed even in a case in which a target service responds (with a fault or HTTP status). In other words, even though the target service returned an authentication error or page not found error (for example), the server was available and the service had an opportunity to process the message. However, the message is redelivered if the following applies:

If fail over URLs are specified, at least once semantics are provided with respect to at least one of the URLs.

Threading Model

The BEA AquaLogic Service Bus threading model works as follows:

Note: In a request or response flow Publish action, responses are always discarded because Publish actions are inherently a oneway message send.

Splitting Proxy Services

You may want to split a proxy service in the following situations:

Outbound Message Retries

In addition to configuring inbound retries for messages, you can configure outbound retries and load balancing. Load balancing, failover, and retries work in concert 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 the Using the AquaLogic Service Bus Console.

Note that for HTTP and HTTPS 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.

 


Content Types, JMS Type, and Encoding

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 email and HTTP(S) protocols.

If the service type is:

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 about the $outbound and $inbound context variables, see Message Context in the Using the AquaLogic Service Bus Console.

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 the AquaLogic Service Bus Console.

Encoding is also explicitly configured in the service definition for all outbound messages. For more information about the service definitions, see "Adding a Proxy Service" and "Adding a Business Service" in Proxy Services in the Using the AquaLogic Service Bus Console.

 


Asynchronous Request/Response

This section details the advantages that you gain from using asynchronous request/response messaging before briefly describing a user case scenario where it is advantageous to use asynchronous request/response messages.

Using asynchronous request/response messages has the following advantages:

If you are using WebSphere MQ, asynchronous request/response messages may typically be the desired approach for interacting with some mainframes. You should note that the asynchronous service must echo the correlation ID. The correlation ID format used internally by AquaLogic Service Bus is compatible with WebSphere MQ and works even if the target service is using MQ native interfaces. For more information, see JMS Correlation ID.

Asynchronous request/response messages are handled by the outbound transport. That is, the message flow, except for the $outbound transport specific data, does not distinguish between JMS request/response and HTTP request/response.

A common use case where asynchronous request and response should be used is where the client invokes a proxy Web service via HTTP, but the backend system that is invoked by the proxy service uses JMS request/response.

JMS Correlation ID

This section describes how you use the JMS correlation ID to link request and response messages.

You must use the JMS correlation ID to link request and response messages for business services that communicate with AquaLogic Service Bus using JMS. When you design the business service in Java, make sure that you use getJMSCorrelationID on the inbound message and setJMSCorrelationID on the outbound message before sending the JMS response to a queue or topic. For more information on configuring business services, see Business Services in the Using the AquaLogic Service Bus Console.

You can obtain the JMSCorrelationID when you receive a message using:

String getJMSCorrelationID()

The above method returns correlation ID values that provide specific message IDs or application specific string values.

To set the JMSCorrelationID() when you send a message:

void setJMSCorrelationID(String correlationID)

 


WS-I Compliance

BEA AquaLogic Service Bus provides WS-I (Web Service Interoperability) compliance 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, you can use the AquaLogic Service Bus Console to specify whether you want AquaLogic Service Bus to enforce WS-I compliance for the service. To learn how to do this, see "Adding a Proxy Service" in Proxy Services in theUsing the AquaLogic Service Bus Console.

When you configure WS-I compliance for a proxy service, checks are performed against 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 strongly advises 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 the 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. This 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 follows in the AquaLogic Service Bus Console:

Figure 2-17 Enforce WS-I Compliance Checkbox

Enforce WS-I Compliance Checkbox


 

WS-I Compliance Checks

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 be non-null. This depends upon the operation selection algorithm being configured properly. For response messages received from invoked services, the operation should have been specified in the action configurations for Route, Publish and Service Callout.

When you configure WS-I compliance checking for a service, AquaLogic Service Bus carries out the following checks:

Table 2-6 AquaLogic Service Bus WS-I Compliance Checks

Check

WS-I Basic Profile Details

AquaLogic Service Bus Description

3.1.1 SOAP Envelope Structure

R9980 An Envelope must conform to the structure specified in SOAP 1.1, Section 4, "SOAP Envelope" (subject to amendment)

This check applies to request and response messages. If a response message is checked and the message does not possess an outer Envelope tag, a soap:Client error is generated. If the message is an Envelope tag but possesses a different namespace, it is handled by the 3.1.2 SOAP Envelope Namespace.

3.1.2 SOAP Envelope Namespace

R1015 A Receiver must generate a fault if they encounter an envelope whose document element is not soap:Envelope.

This check applies to request and response messages and is related to the 3.1.1 SOAP Envelope Structure. If a request message has a localname of Envelope, but the namespace is not SOAP 1.1, a soap:VersionMismatch error is generated.

3.1.3 SOAP Body Namespace Qualification

R1014 The children of the soap:Body element in an Envelope must be namespace qualified.

This check applies to request and response messages. Any request error messages generate a soap:Client error.

3.1.4 Disallowed Constructs

R1008 An Envelope must not contain a Document Type Declaration.

This check applies to request and response messages. Any request error messages generate a soap:Client error.

3.1.5 SOAP Trailers

R1011 An Envelope must not have any element children of soap:Envelope following the soap:Body element.

This check applies to request and response messages. Any request error messages generate a soap:Client error.

3.1.9 SOAP attributes on SOAP 1.1 elements

R1032 The soap:Envelope, soap:Header, and soap:Body elements in an Envelope must not have attributes in the namespace http://schemas.xmlsoap.org/soap/envelope/

This check applies to request and response messages. Any request error messages generate a soap:Client error.

3.3.2 SOAP Fault Structure

R1000 When an Envelope is a Fault, the soap:Fault element must not have element children other than faultcode, faultstring, faultactor, and detail.

This check only applies to response messages.

3.3.3 SOAP Fault Namespace Qualification

R1001 When an Envelope is a Fault, the element children of the soap:Fault element must be unqualified.

This check only applies to response messages.

3.4.6 HTTP Client Error Status Codes

R1113 An instance should use a "400 Bad Request" HTTP status code if a HTTP request message is malformed.

R1114 An instance should use a "405 Method not Allowed" HTTP status code if a HTTP request message is malformed.

R1125 An instance must use a 4xx HTTP status code for a response that indicates a problem with the format of a request.

Only applies to responses for a proxy service where you cannot influence the status code returned due to errors in the request.

3.4.7 HTTP Server Error Status Codes

R1126 An instance must return a "500 Internal Server Error" HTTP status code if the response envelope is a fault.

This check applies differently to request and response messages. For request messages, any faults generated have a 500 Internal Server Error HTTP status code. For response messages, an error is generated if fault responses are received that do not have a 500 Internal Server Error HTTP status code.

4.7.19 Response Wrappers

R2729 An envelope described with an rpc-literal binding that is a response must have a wrapper element whose name is the corresponding wsdl:operation name suffixed with the string Response.

This check only applies to response messages. AquaLogic Service Bus never generates a non-fault response from a proxy service.

4.7.20 Part Accessors

R2735 An envelope described with an rpc-literal binding must place the part accessor elements for parameters and return value in no namespace.

R2755 The part accessor elements in a message described with an rpc-literal binding must have a local name of the same value as the name attribute of the corresponding wsdl:part element.

This check applies to request and response messages. Any request error messages generate a soap:Client error.

4.7.22 Required Headers

R2738 An envelope must include all soapbind:headers specified on a wsdl:input or wsdl:output of a wsdl:operation of a wsdl:binding that describes it.

This check applies to request and response messages. Any request error messages generate a soap:Client error.

4.7.25 Describing SOAPAction

R2744 A HTTP request message must contain a SOAPAction HTTP header field with a quoted value equal to the value of the soapAction attribute of soap:operation, if present in the corresponding WSDL description.

R2745 A HTTP request message must contain a SOAPAction HTTP header field with a quoted empty string value, if in the corresponding WSDL description, the SOAPAction of soapbind:operation is either not present, or present with an empty string as its value.

This check applies to request messages and a soap:Client error is returned.


 

 

Skip navigation bar  Back to Top Previous Next