User Guide

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
• Pipelines
• Branching in Message Flows
• Performing Transformations
• Configuring Single or Multiple Stages in Pipelines
• Handling Errors
• Selecting a Service Type
• Dynamic Routing
• Message Context
• RPC and Document Style SOAP
• Variable Structures
• Quality of Service
• Content Types, JMS Type, and Encoding
• Asynchronous Request/Response
• WS-I Compliance

 

---

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

 

This topic includes the following sections:

• Building a Message Flow
• Message Execution

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:

• In the case of non-operational services (services that are not based on WSDLs with operations), the flow is likely to consist of a single pipeline pair at the root followed by a route node.
• In the case of operational services, the flow is likely to consist of a single pipeline pair at the root, followed by a branch node based on operation, with each branch consisting of a pipeline pair followed by a route node.

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

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

 

---

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:

• Request—Request pipelines are used for processing the request path of the message flow.
• Response—Response pipelines are used for processing the response path of the message flow.
• Error—Error pipelines are designed to handle errors for stages and nodes in a message flow, and also at the level of the message flow (service).

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

 

The message flow in the preceding figure shows:

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

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

Figure 2-3 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

 

Figure 2-5 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

 

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:

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

Publish actions identify a target service for a message and configure how the message is packaged and sent to that service. Publish Table actions are also available—a Publish Table action is comprised of a set of routes wrapped in a switch-style condition table. It is a short-hand construct that allows different routes to be selected based upon the results of a single XQuery expression.

• You perform the transformation on the response or request message regardless of the route destination.

In this case, you can configure the transformations in the request or response pipeline stages.

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:

• Quality of Service—see Quality of Service
• Configuring pipelines—see "Pipelines" in "Overview of Message Flow" in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console
• Actions, see Adding an Action" in Proxy Services: Actions in theUsing the AquaLogic Service Bus Console
• Route nodes, see Adding a Route Node" in Proxy Services: Message Flow in Using the AquaLogic Service Bus Console

 

---

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

• Transformation of messages. For more information, see XQuery Transformations and XSL Transformations in the Using the AquaLogic Service Bus Console.
• Reporting on messages. For more information, see Reporting in Using the AquaLogic Service Bus Console and Reporting.
• Perform a lookup with a Service Callout action to achieve message enrichment or to facilitate routing decisions.
• Validate the message and raise errors. For more information, see "Error Messages and Handling" in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.
• Publish a copy of the message, or data from the message that has been transformed by the message flow, to a specified destination. For more information, see:
• "Publish" in Proxy Services: Actions in Using the AquaLogic Service Bus Console
• "Constructing Messages and Dispatches" in Message Context in Using the AquaLogic Service Bus Console.
• Iterate over a sequence of values and execute a block of actions using the For Each action.
• Generate a log. For more information, see "Viewing Server Log Files" in Monitoring in the Using the AquaLogic Service Bus Console.
• Assign the result of an XQuery expression to a context variable.
• Insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression.
• Validate elements selected by an XPath expression against a top level XML schema element or WSDL resource.
• Rename elements selected by an XPath expression without modifying contents.
• Set the transport headers for inbound and outbound messages.

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:

• Multiple stages provide a natural modularity compared to configuring all the actions in a single stage.
• Each stage in a request or response pipeline can have a separate error handling pipeline. Designing your pipeline with multiple stages allows you to avoid writing a single error handler that must handle all errors by all actions in a single stage. For more information, see "Error Messages and Handling" in Proxy Services: Error Handlers in the Using the AquaLogic Service Bus Console.
• If you use the resume action (in a stage level error handler) or the skip action, processing is resumed at the next stage in a request or response pipeline. Therefore, you must place the actions that you want performed after a resume or skip action in subsequent stages in the message flow.
• The Resume action is used in error handlers. At run time, this action causes the message flow processing to continue as though no error has occurred. Processing continues after the node or stage in which the error handler is configured.
• The Skip action specifies that at run time, the execution of the current stage is skipped and the processing proceeds to the next stage in the message flow.

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

 

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:

• Configure a test that checks if an assertion is true and use a reply action (with failure) in the request or response pipelines.
• Catch and handle the errors at the stage level, route node level, or pipeline level. For more information, see "Adding Stage Error Handling", "Adding Pipeline Error Handling", and "Adding Error Handling for the Route Node" in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.
• Catch and handle the errors at the service level. For more information, see "Adding Error Handling for the Proxy Service" in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.
• Let the system error handler handle the error. The system error handler handles the error in the event that the error is not handled by a stage or a service level handler.

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

 

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

 

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

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

In this case, in the event of an error, the contents of the fault context variable are reported. errorCode is the key name, 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 are used to identify these messages in the Dashboard at run time.

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.

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

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:

• SOAP Services—SOAP services receive and respond with SOAP messages. SOAP messages are constructed by wrapping the contents of the header and body variables inside a <soap:Envelope> element.
• XML Services (Non SOAP)—The messages to XML-based services are XML, but can be of any type allowed by the proxy service configuration.
• Messaging Services—Messaging services are those that can receive messages of one data type and respond with messages of a different data type. The supported data types include XML, MFL, text, and untyped binary.

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

 

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:

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

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

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:

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

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

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

You can get the WSDL for an HTTP(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:

• Message-related variables
• Inbound and outbound variables
• Operation variable
• Fault variable

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:

• If the message is binary, any text or XML content inside the Body element in $body is sent.
• For MFL messages, the Body element in $body contains the XML equivalent of the MFL document.
• For text messages, the Body element in $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.
• For XML messages, the Body element in $body contains the XML. For XML attachments, the body element in $attachments contains the XML.
• SOAP messages are constructed by wrapping the contents of the header and body variables inside a <soap:Envelope> element. If the body variable contains a piece of reference XML, it is sent as is—in other words, the referenced content is not substituted into 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 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:

• In an XQuery expression, the root element in a variable is not present in the path when referring to an element in that variable. For example, the following XQuery expression obtains the Content-Description of the first attachment in a message:

$attachments/ctx:attachment[1]/ctx:Content-Description

To obtain the second attachment that contains, for example, a purchase order:

$attachments/ctx:attachment[2]/ctx:body/*

• A context variable is either empty or it contains a single XML element or string value. However, an XQuery expression often returns a sequence. When you use an XQuery expression to assign a value to a variable, only the first element in the sequence returned by the expression is stored as the variable value. For example, if you want to assign the value of a WS-Addressing Message ID from a SOAP header (assuming there is one in the header) to a variable named 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.

• The variables $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.
• For many of the cases in which you use a transformation resource (XSLT or XQuery), the transformation resource is defined to transform the document in the SOAP body of a message. To make this transformation case easy and efficient, the input parameter to the transformation can be an XQuery expression. For example, you can use the following XQuery expression to feed the business document in the Body element of a message ($body) as input to a transformation:

$body/* [1]

The result of the transformation can be put back in $body with a Replace action (replace the content of $body, which means the content of the Body element). For more information, see XQuery Transformations and XSL Transformations in Using the AquaLogic Service Bus Console.

• In addition to inserting or replacing a single element, you can also insert or replace a selected sequence of elements using an insert or replace action. You can configure an XQuery expression to return a sequence of elements. For example, you can use insert and replace actions to copy a set of transport headers from $inbound to $outbound. For information on adding an action, see "Adding an Action" in Proxy Services: Actions in the Using the AquaLogic Service Bus Console. For an example, see Copying JMS Properties From Inbound to Outbound.

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
• Document Style SOAP

RPC Web Services

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

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

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
• Using Variable Structures
• Using Variable Structure Mappings

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:

• Fragments of XML with embedded XQueries.
• Simple variable paths along the child axis.

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:

• Extract or access a business document or RPC parameter from the SOAP envelope elements in $header or $body.
• Extract or access an attachment document in $attachments.
• Set up the parameters of a Service Callout action by extracting it from the SOAP envelope.
• Fold the result parameter of a Service Callout action into the SOAP envelope.
• Extract a sequence from the SOAP envelope to drive a for loop.
• Update an item in the sequence in a for loop with an Update action.

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
• Creating the Resources You Need for the Examples
• Example 1: Selecting a Predefined Variable Structure
• Example 2: Creating a Variable Structure that Maps a Variable to a Type
• Example 3: Creating a Variable Structure that Maps a Variable to an Element
• Example 4: Creating a Variable Structure that Maps a Variable to a Child Element
• Example 5: Creating a Variable Structure that Maps a Variable to a Business Service
• Example 6: Creating a Variable Structure that Maps a Child Element to Another Child Element

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
• To Create a Proxy Service that Uses the Sample WSDL
• To Build Message Flow for the Sample Proxy Service
• To Create a Business Service that Uses the Sample WSDL

To Save the WSDL as a Resource

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.
From the left navigation pane, select Project Explorer. The Project View page is displayed.
Select the project to which you want to add the WSDL.
From the Project View page, in the Create Resource field, select WSDL from under Interface. The Create a New WSDL Resource page is displayed.
In the Resource Name field, enter SampleWSDL. This is a required field.
In the WSDL field, copy and paste the text from the sample WSDL into this field.

Note: This is a required field.

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

From the left navigation pane, select Project Explorer. The Project View page is displayed.
Select the project to which you want to add the proxy service.
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.
In the Service Name field, enter ProxywithSampleWSDL. This is a required field.
In the Service Type field, which defines the types and packaging of the messages exchanged by the service, do the following:
Select WSDL binding from under Create a New Service.
Click Browse. The WSDL Browser is displayed.
Select SampleWSDL, then select POBinding in the Select WSDL Definitions pane.
Click Submit.
Use the defaults for all other fields on the General Configuration page, then click Next.
Use the defaults for all fields on the Transport Configuration pages, then click Next.
On the Operation Selection Configuration page, make sure SOAP Body Type is selected in the Selection Algorithm field, then click Next.
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

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.
Click the ProxywithSampleWSDL icon, then click Add Pipeline Pair. PipelinePairNode1 is displayed, which includes request and response pipelines.
Click the request pipeline, then click Add Stage. The stage stage1 is displayed.
Click Save. The basic message flow is created for the ProxywithSampleWSDL proxy service.

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

From the left navigation pane, select Project Explorer. The Project View page is displayed.
Select the project to which you want to add the business service.
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.
In the Service Name field, enter BusinesswithSampleWSDL. This is a required field.
In the Service Type field, which defines the types and packaging of the messages exchanged by the service, do the following:
Select WSDL binding from under Create a New Service.
Click Browse. The WSDL Browser is displayed.
Select SampleWSDL, then select POBinding in the Select WSDL Definitions pane.
Click Submit.
Use the defaults for all other fields on the General Configuration page, then click Next.
Use the defaults for all fields on the Transport Configuration and SOAP Binding Configuration pages, then click Next.
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.
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

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

Figure 2-10 Variable Structures—body




 

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

In the Variable Structures panel, click Add New Structure. Additional fields are displayed as follows:

Figure 2-11 Variable Structures—Add a New Structure




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

The variable structure InvoiceType is displayed as follows:

Figure 2-12 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

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

The variable structure Invoice is displayed as follows:

Figure 2-13 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

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

The variable structure body to PO is displayed as follows:

Figure 2-14 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

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

The variable structure BusinessService is displayed as follows:

Figure 2-15 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

In the Variable Structures panel, select attachments from the drop-down list of built-in structures.

The variable structure attachments is displayed as follows:

Figure 2-16 Variable Structures—attachments




 

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:

$attachments/ctx:attachment/ctx:body

Copy the contents of the body element.
In the Variable Structures panel, click Add New Structure.
Make sure XML Type is selected.
In the Structure Label field, enter PO attachment as the meaningful display name for this variable structure.
In the Structure Path field, paste the contents of the body element:

$attachments/ctx:attachment/ctx:body

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

To select the PO element, do the following:
Under the Type field, make sure the appropriate radio button is selected, then select WSDL Element.
Click Browse. The WSDL Browser is displayed.
In the WSDL Browser, select SampleWSDL, then select PO under Elements in the Select WSDL Definitions pane.
Click Submit.
Select the Set as child checkbox to set the PO element as a child of the body element.
Click Add. The new variable structure second attachment is included under XML Type in the drop-down list of variable structures.
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

$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
• Outbound Message Retries

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

 

 

Overriding the Default Element Attribute

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

• Route Node action
• Publish action

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:

• The value of the qualityOfService element.
• The inbound transport (and connection factory if applicable).
• The outbound transport (and connection factory if applicable).

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

 

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:

• If the proxy service inbound transport is file, FTP, email, or JMS/XA, the request flow work is performed in a transaction.
• When the qualityOfService element is set to exactly-once, any Route node and Publish actions executed in the request flow to a JMS/XA destination are performed in the same transaction.
• When the qualityOfService element is set to best-effort, any Route node, Service Callout actions, or Publish actions are executed outside of the request flow transaction. Specifically, for JMS, the request flow transaction is suspended and the JMS work is done without a transaction or in a separate transaction that is immediately committed.
• If an error occurs during request flow processing, but is caught by a user error handler that manages the error (by using the Resume or Reply action), the message is considered successfully processed and the transaction commits. A transaction is aborted if the system error handler receives the error—that is, if the error is not handled before reaching the system level. The transaction is also aborted if a server failure occurs during request pipeline processing.
• If a response is received by a proxy service that uses a JMS/XA transport, the response flow work is performed in a single transaction.
• When the qualityOfService element is set to exactly-once, all Publish actions are performed in the same transaction.
• When the 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, the response flow transaction is suspended and the JMS work is done without a transaction or in a separate transaction that is immediately committed.
• The proxy service responses executed in the response flow to a JMS/XA destination are always performed in the same transaction, regardless of the qualityOfService element setting.

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:

• The proxy server or the target server crashes during message transfer
• The target server is not running
• The response times out

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:

• The request and response flows in a proxy service execute in different threads.
• Service callouts are always blocking, but a HTTP route or publish action is non-blocking (for request/response or oneway invocation) if the value of the qualityOfService element is best-effort.
• JMS Route actions or Publish actions are always nonblocking, but the response is lost if the server restarts after the request is sent because AquaLogic Service Bus has no persistent message processing state.

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:

• When HTTP is the inbound and outbound transport for a proxy service, you may want to incorporate enhanced reliability into the middle of the message flow. To enable enhanced reliability in this way, split the proxy service into a front end HTTP proxy service and a back end JMS (oneway or request/response) proxy service with a HTTP outbound transport. In the event of a failure, the first proxy service must quickly enqueue the message in the queue for the second proxy service to avoid loss of messages.
• To disable the direct invocation optimization for a non JMS transport when a proxy service invokes another proxy service, route to the second proxy service from the first proxy service where the second proxy service uses JMS transport.
• To have a HTTP proxy service publish to a JMS queue but have the Publish action roll back if there is a exception later on in the request processing, split the proxy service into a front end HTTP proxy service and a backend JMS proxy service. The Publish action specifies a qualityOfService element of exactly-once and uses a XA connection factory.

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:

• XML or SOAP (with or without a WSDL), the content type is text/XML.
• Messaging and the interface is MFL or binary, the content type is binary/octet-stream.
• Messaging and the interface is text, the content type is text/plain.
• Messaging and the interface is XML, the content type is text/XML.

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:

• The request thread does not block waiting for the response. This removes a thread management issue that can occur when numerous blocking request/response invocations are made.
• The messaging is more reliable.

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:

• Disambiguate the WSDL and SOAP specifications wherever ambiguity exists.
• Define constraints that can be applied when receiving messages or importing WSDLs so that interoperability is enhanced. When messages are sent, construct the message so that the constraints are satisfied.

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:

• Service invocation request message.
• System-generated error messages returned by a proxy service.
• HTTP status codes generated by a proxy service.

The Enforce WS-I Compliance checkbox is displayed as follows in the AquaLogic Service Bus Console:

Figure 2-17 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:

 

Contact BEA |  Feedback |  Privacy  |