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

This section includes the following topics:

 


About AquaLogic Service Bus Message Flow

Message flow defines the implementation of a proxy service. Message flows are constructed by connecting together one or more instances of the following nodes types: Pipeline Pair, Route, Branch, or Echo. To learn how to implement message flow, see "Viewing and Changing Message Flow" in Proxy Services in the AquaLogic Service Bus Console Online Help.

This section includes the following topics:

Pipelines

A principle component in a proxy'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 together and organized into a single node called a pipeline pair node. Pipeline pair nodes are organized along with two other types of nodes into a single-rooted tree structure that represents the message flow. 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. 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 message flow is constructed by chaining together instances of the top-level components detailed in the following table.

Table 2-1 Message Flow Components

Node Type

Description

Pipeline pair node

A pipeline pair node 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.

To learn how to add a pipeline pair node, see "Adding a Pipeline Pair Node" in Proxy Services in the AquaLogic Service Bus Console Online Help.

Branch node

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 an single XPath expression (for example, ./ns:PurchaseOrder/ns:totalCost on $body). Whichever condition is satisfied first determines which branch is followed. For more information, see Message Context in the AquaLogic Service Bus Console Online Help. 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 in the AquaLogic Service Bus Console Online Help.

Route node

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

Echo node

An echo node is a node that routes (or echoes) a message from the end of the request pipeline to the start of the response pipeline. In other words, the message is not routed from the proxy service to another service. It remains within the proxy service.

Message Execution

The following table demonstrates the journey of a message in a typical message flow.

Table 2-2 Message Journey

Node

What Happens to the Message?

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 a change from request processing to response processing. When a response comes in, it reverses the path it took for the request. The same thing occurs for any request path that ends without a route node - it initiates response processing and walks back up the flow, but without waiting for any response.

Response Processing

See Route.

Branch

Continues with the node that preceded the branch.

Pipeline Pair

Executes the response pipeline.

Root of the Flow

Sends the response back to the client.

Route

Executes any response transformations.

Echo

Routes the message from the end of the request pipeline to the start of the response pipeline.

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 may be chained together. For example, two pipeline pair nodes may be chained together without a branching 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 response processing begins immediately. However, in general a message flow is likely to come in two forms: for non-operational services, the flow is likely to consist of a single pipeline pair at the root followed by a route node. For 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.

Operational Branching

Since message flow is typically used with WSDL-based 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.

To learn how to add an operational branch node, see "Adding an Operational Branch Node" in Proxy Services in the AquaLogic Service Bus Console Online Help.

 


Performing Transformations

This section presents guidelines to follow when you are designing 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 the AquaLogic Service Bus Console Online Help. For information on using the BEA XQuery Mapper to create XQueries, see Transforming Data Using the XQuery Mapper in the BEA XQuery Mapper Online Help.

The location where you perform a transformation depends on whether or not:

If the message format you need to transform to or from depends on the target services, you must perform the transformation in a route action or publish action. In the case of a publish action, the transformations own 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.

For example, when dealing with a large purchase order, it may be necessary to send a summary of the purchase order to a manager via email. A summary is created that details the main 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 data is transformed in the purchase order into a summary order and all the attachments in $attachements are deleted because they are not included 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 and the second destination requires that the document in the SOAP body must be transformed to a newer version. In this situation, configure the route node to conditionally route to one of the two destinations. Transform the document in the route action 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 AquaLogic Service Bus Console Online Help for information about the subelements of the inbound and outbound variables and how the content of messages is constructed using the values of variables in the message context.

If you need to perform a transformation on the request or response message regardless of the route destination, you should configure the transformation in the request or response pipeline stage.

For more information on pipelines, see "Pipelines" in "Overview of Message Flow" in Proxy Services in the AquaLogic Service Bus Console Online Help. For more information on actions, see Adding an Action" in Proxy Services in the AquaLogic Service Bus Console Online Help and for more information on route nodes, see Adding a Route Node" in Proxy Services in the AquaLogic Service Bus Console Online Help.

 


Branching in Message Flows

This section details the situations in which to use operational branching and the ones in which you can use conditional branching.

You should use operational branching to handle messages separately for each operation in situations where a proxy service is based on a Web Services Description Language (WSDL) with multiple operations. For more information, see "Viewing and Changing Operational Branch Details" in Proxy Services in the AquaLogic Service Bus Console Online Help. However, if the proxy service is not based on a WSDL and receives multiple document types, consider using a conditional branching node instead.

For example, if 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 for each message type received. For more information on Any SOAP or Any XML, see "Adding a Proxy Service" in Proxy Services in the AquaLogic Service Bus Console Online Help.

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 within the route node, you can expose or highlight this branching in the message flow itself and use simple route nodes as the subflows for each of the branches.

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

 


Configuring Single or Multiple Stages in Pipelines

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 more information on configuring a stage, see "Adding a Stage" in Proxy Services in the AquaLogic Service Bus Console Online Help.

Stages are a container for actions and the actions can perform any of the following tasks:

Using Multiple Stages

Consider the following characteristics of stages and actions to 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 in the AquaLogic Service Bus Console Online Help.

 


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. For a more detailed explanation of error messages and handling, see "Error Messages and Handling" in Proxy Services in the AquaLogic Service Bus Console Online Help.

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

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 anticipate errors in the pipelines, you can only handle WS-Security related errors at the service level.

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

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

For more information, see "Error Messages and Handling" in Proxy Services in the AquaLogic Service Bus Console Online Help.

 


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 may send or receive attachments using MIME.

The following table displays the types of service types and transports 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.


 

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

The benefits of using a WSDL in this situation include:

If you decide to 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 is bound to a port on the WSDL and the URL accurately reflects the URL of the proxy service. This may be important to some client tools. The URL in the WSDL port bound to the service is not used, except to populate the URL in the WSDL port as the default URL for a business service during service definition. 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 the AquaLogic Service Bus Console Online Help.

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

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 "mustunderstand" 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 Adding an Action" in Proxy Services in the AquaLogic Service Bus Console Online Help. For more information on XQuery conditional expressions, see "Editing an XQuery Condition" in Proxy Services in the AquaLogic Service Bus Console Online Help.

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

 


Dynamic Routing

In a situation where you are designing a proxy service and do not know the concrete service to invoke, 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, porttypes, 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. This means that the URL is supplied at run time and eliminates the need to know it when you design and configure your service.

 


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

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

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

Key Context Manipulation Facts

Consider the following guidelines when you want to alter the context:

Copying JMS Properties

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:

Insert $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 insert and other actions in the AquaLogic Service Bus Console, see "Adding an Action" in Proxy Services in the AquaLogic Service Bus Console Online Help.

 


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

The above service has 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 above WSDL is used for a request, the value of the body variable ($body) that the SOAP RPC proxy 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 only.

Listing 2-2 Body Variable Value

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

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

If the business service that the proxy is routing to 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.

When the above 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>

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 the service. This java class can be used to invoke the proxy service that uses this WSDL.

Document Style SOAP

You can configure proxy services as SOAP style proxies 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>

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 above WSDL is used for a request, the value of the body variable ($body) that the document style proxy obtains is displayed in the following listing.

Listing 2-5 Body Variable Value

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

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 that the proxy is routing to 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>

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 the service. This java class can be used to invoke the proxy service that uses this WSDL.

 


Quality of Service

This section covers the following quality of service issues:

Delivery Guarantees

AquaLogic Service Bus supports reliable messaging. When messages are routed to another service from a route node, the default quality of service (QoS) is exactly once if the proxy transport is JMS/XA. Otherwise, it is best-effort. Exactly once reliability means that messages are delivered from inbound to outbound exactly once, assuming a terminating error does not occur before the outbound message send is initiated. Exactly once delivery reliability is a hint, not a directive. When exactly once is specified, exactly once reliability is provided if possible. If exactly once is not possible, then at least once delivery semantics are attempted; if that is not possible, best effort delivery is performed.

At least once semantics means the message is delivered to the outbound from the inbound at least once, assuming a terminating error does not occur before the outbound message send is initiated. If fail over URLs are specified, at least once semantics are provided with respect to at least one of the URLs.

Best effort means that there is no reliable messaging and no elimination of duplicate messages—however, performance is optimized.

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

If the proxy inbound is JMS/XA and if the outbound transport for a publish action or a route action is JMS/XA, then the system ensures that the message is transferred exactly once from the input transport to the output transport without loss of the message or duplication of delivery. For the remainder of the transport protocols (email, FTP, file, HTTP, HTTPS, JMS/nonXA), when the proxy inbound is JMS/XA, the system ensures the message is transferred at least once from the input transport to the output transport without loss of the message. For more information on transport protocols, see "Adding a Proxy Service" and "Adding a Business Service" in Proxy Services in the AquaLogic Service Bus Console Online Help.

Delivery guarantees are based on JMS inbound retries. The retrycount and what to do if the count is exhausted can be configured in the WebLogic Server Administration Console (this cannot be configured in the AquaLogic Service Bus Console). By default, for queues created by AquaLogic Service Bus, the retry count is 1 and the message is discarded after the count is exhausted. For a list of the default JMS queues created by AquaLogic Service Bus, see the BEA AquaLogic Service Bus Deployment Guide.

The guarantee of delivering the message at least once for HTTP(S) requires further explanation. Even for a case in which a target service responds (with a fault or HTTP status), it is assumed that the delivery completed. 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, if the proxy server or the target server crashes during message transfer, the target server is not running, or the response times out, the message is redelivered.

If you need to configure a business service or a proxy service that uses an unreliable transport like HTTP and you want more reliability, follow these guidelines:

  1. For a proxy service using an unreliable transport (for example HTTP), split the service into two proxy services. The first one uses the unreliable transport whose only task is to quickly route to the second proxy service that uses a JMS/XA transport. Using this technique, the message that arrives is immediately persisted in the JMS queue by the first proxy, and the second proxy can reliably process it in the background without fear of losing the message and with a guarantee of an at least once semantics (or in some cases an exactly once semantics) with respect to the second proxy.
  2. For a business service using an unreliable transport (for example HTTP), front-end it with a JMS/XA proxy service that other proxy services can route to. With this approach, the wrapper proxy service will redeliver the message to the business service for ensuring at least once semantics.

Outbound Message Retries

In addition to configuring inbound retries for JMS 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 AquaLogic Service Bus Console Online Help.

Note that for HTTP(S) transports, any HTTP status other than 200 or 202 is considered an error by AquaLogic Service Bus and must be retried. Because of this algorithm, it is possible that AquaLogic Service Bus retries errors like authentication failure that may never be rectified for that URL within the time period of interest. On the other hand, if AquaLogic Service Bus also fails over to a different URL for subsequent attempts to send a given message, the new URL may not give the error.

 


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

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

 


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 getJMCCorrelationID on the inbound message and setJMCCorrelationID 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 AquaLogic Service Bus Console Online Help.

You can obtain the JMCCorrelationID 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)

About the JMS Transport URI Format

When using the JMS binding to configure a business service, the SOAP/JMS URI format you must provide in the AquaLogic Service Bus Console is:

jms://host:port/factoryJndiName/destJndiName

However, BEA WebLogic Workshop expects the following format:

://host:port/factoryJndiName/destJndiName?URI=/process/myprocess.jpd

To overcome this problem, you must set the URI as a JMS property inside the message flow on the outbound variable ($outbound) before it is sent. For information about setting $outbound, see "Inbound and Outbound Variables" in Message Context in the AquaLogic Service Bus Console Online Help.

 

Skip navigation bar  Back to Top Previous Next