text: In ALSB, a message flow defines the implementation of a proxy service. You can create and configure ALSB proxy services in the ALSB Console or the ALSB Plug-in for WorkSpace Studio. This section describes message flows and presents guidelines for designing them.
  The following sections describe message flows in ALSB:
  For instructions on creating and configuring message flows in the ALSB Console, see:
  For instructions on creating and configuring message flows in the ALSB Plug-in for WorkSpace Studio, see:
  A message flow is composed of components that define the logic for routing and manipulating messages as they flow through a proxy service. Nodes are configured to route messages through the message flow, and stages and actions contain rules for processing and transforming messages.
  Most of the processing logic in a message flow is handled in pipelines. A pipeline is a named sequence of stages representing a non-branching one-way processing path. Pipelines belong to one of the following categories:
  To implement the processing logic of a proxy service, request and response pipelines are paired together in pipeline pair nodes. These pipeline pair nodes can be combined with other nodes into a single-rooted tree structure to control overall flow.
  Table 3-1 describes the components available for defining message flows.
  Figure 3-1 shows a high level view of components in a message flow definition.
  The only components required in a message flow are a start node and a route node. No restrictions exist on what other components can be chained together in the message flow. You could create a single route node that contained all the logic for the flow. Or, you could link two pipeline pair nodes without a branch node in between. If you use branch nodes, each branch node could start with a different element. One branch could terminate with a route node, another could be followed by a pipeline pair, and yet another could have no descendant. (When a branch with no descendants is executed at run time, response processing begins immediately.)
  However, in general, a message flow is likely to be designed in one of the following ways:
  Table 3-2 briefly describes how messages are processed in a typical message flow.
  Two kinds of branching are supported in message flows: operational branching, configured in an operational branch node, and conditional branching, configured in a conditional branch node.
  When message flows define WSDL-based proxy services, operation-specific processing is required. When you create an operational branch node in a message flow, you can build branching logic based on the operations defined in the WSDL.
  You must use operational branching when a proxy service is based on a WSDL with multiple operations. You can consider using an operational branch node to handle messages separately for each operation.
  Use conditional branching to branch based on a specified condition, for example the document type of a message.
  Conditional branching is driven by a lookup table with each branch tagged with simple, unique string values, for example,
  QuantityEqualToOrLessThan150 and
  QuantityMoreThan150.
  You can configure a conditional branch to branch based on the value of a variable in the message context (declared, for example, in a stage earlier in the message flow), or you can configure the condition to branch based on the results of an XPath expression defined in the branch itself.
  At run time, the variable or the expression is evaluated, and the resulting value is used to determine which branch to follow. If no branch matches the value, the default branch is followed. A branch node may have several descendants in the message flow: one for each branch, including the default branch. You should always define a default branch. You should design the proxy service in such a way that the value of a lookup variable is set before reaching the branch node.
  For example, consider the following case using a lookup variable. A proxy service is of type any SOAP or any XML, and you need to determine the type of the message so you can perform conditional branching. You can design a stage action to identify the message type and then design a conditional branching node later in the flow to separate processing based on the message type.
  Now consider the following case using an XPath expression in the conditional branch node. You want to branch based on the quantity in an order. That quantity is passed via a variable that can be retrieved from a known location in
  $body. You could define the following XPath expression to retrieve the quantity:
  declare namespace openuri="";
  declare namespace com="bea.com/demo/orders/cmnCust";
  ./openuri:processCust/com:cmnCust/com:Order_Items/com:Item/com:Quantity
  The condition (for example,
  <500) is then evaluated in order down the message flow against the expression. Whichever condition is satisfied first determines which branch is followed. If no branch condition is satisfied, then the default branch is followed.
  You can use conditional branching to expose the routing alternatives for the message flow at the top level flow view. For example, consider a situation where you want to invoke service A or service B based on a condition known early in the message flow (for example, the message type). You could configure the conditional branching in a routing table in the route node. However, that makes the branching somewhat more difficult to follow if you are just looking at the top level of the flow. Instead, you could use a conditional branch node to expose 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 be awkward in the design interface if a large number of branches extend from the branch node.
  Actions provide instructions for handling messages in pipeline stages, error handler stages, and route nodes. The context determines which actions are available in the ALSB Console or in the ALSB Plug-in for WorkSpace Studio, as described in the following sections:
  Communication actions control message flow. Table 3-3 describes the communication actions.
  Flow controls actions implement conditional routing, conditional looping, and error handling. You can also use them to notify the invoker of success or to skip the rest of the actions in the stage. Table 3-4 describes the flow control actions.
  The actions in this category process the message flow. Table 3-5 describes the message processing actions.
  You use the actions in this category to log or report errors and generate alerts if required in a message flow within a stage. Table 3-4 describes the reporting actions.
  The transport header action is a communication type action, and it is available in pipeline stages and error handler stages.
  The following options are available when you configure a transport headers action:
  Use the options in a way that best suits your scenario. Both options result in the headers in the source header set being copied to the target header set, overwriting any existing value in the target set. Note that the Pass all Headers through Pipeline option is executed before the header-specific Copy Header options. In other words, for a given transport headers action configuration, if you select Pass all Headers through Pipeline, there is no need to select the Copy Header option for given headers.
  However, you can select Pass all Headers through Pipeline to copy all headers, and subsequently configure the action such that individual headers are deleted by selecting Delete Header for specific headers.
  As described above, you can use transport header actions to configure the values of the transport headers for outbound requests (the messages sent out by a proxy service in route, publish, or service callout actions) and inbound responses (the response messages a proxy service sends back to clients). In general, the header values can be:
  The transport headers action allows you to set, delete, or pass-through the headers in
  $inbound or
  $outbound. If you set or delete these headers and then log
  $inbound or
  $outbound, you can see the effects of your changes. However, when the message is sent out, the ALSB binding layer may modify or remove some headers in
  $inbound or
  $outbound and the underlying transport may in turn, ignore some of these headers and use its own values. An important distinction is that any modifications done by the binding layer on a header are done directly to
  $inbound and
  $outbound, whereas modifications done by the transport affects only the message's wire format. For example, although you can specify a value for the outbound
  Content-Length header, the binding layer deletes it from
  $outbound when sending the message. Consequently, the modification is visible in the response path (for example, you can see the modified value if you log
  $outbound). If you set the
  User-Agent header in
  $outbound, the HTTP transport ignores it and use its own value—however, the value in
  $outbound is not changed.
  Table 3-7 describes the transport headers that are ignored or overwritten at run time and other limitations that exist for specific transport headers.
  Transformation maps describe the mapping between two data types. ALSB supports data mapping that uses the XQuery and the eXtensible Stylesheet Language Transformation (XSLT) standards. XSLT maps describe XML-to-XML mappings. XQuery maps can describe XML-to-XML, XML to non-XML, and non-XML to XML mappings.
  The point in a message flow at which you specify a transformation depends on whether:
  Publish actions identify a target service for a message and configure how the message is packaged and sent to that service. ALSB also provides publish table actions. A publish table action consists of a set of routes wrapped in a switch-style condition table. It is a shorthand construct that allows different routes to be selected, based upon the results of a single XQuery expression.
  When transformations are designed in publish actions, the transformations have a local copy of the
  $outbound variable and message-related variables (
  $header,
  $body, and
  $attachments). Any changes you make to an outbound message in a publish action affect only the published message. In other words, the changes you make in the publish action are rolled back before the message flow proceeds to any actions that follow the publish action in your message flow.
  For example, consider a message flow that deals with a large purchase order, and you have to send the summary of the purchase order, through e-mail, to the manager. The summary of the of the purchase order is created in the SOAP body of the incoming message when you include a publish action in the request pipeline. In the publish action, the purchase order data is transformed into a summary of the purchase order—for example, all the attachments in
  $attachments can be deleted because they are not required in the summary of the purchase order.
  You may need to route messages to one of two destinations, based on a WS-addressing header. In that case, content-based routing and the second destination require the newer version of the document in the SOAP body. In this situation, you can configure the route node to conditionally route to one of the two destinations. You can configure a transformation in the route node to transform the document for the second destination.
  You can also set the control elements in the outbound context variable (
  $outbound) to influence the behavior of the system for the outbound message (for example, you can set the Quality of Service).
  See Inbound and Outbound Variables and Constructing Messages to Dispatch for information about the sub-elements of the inbound and outbound variables and how the content of messages is constructed using the values of the variables in the message context.
  See also:
  When ALSB makes a call to a service via a service callout action, the content of the message is constructed using the values of variables in the message context. The message content for outbound messages is handled differently depending upon the type of the target service. How the message content is created depends on the type of the target service and whether you choose to configure the SOAP body or the payload (parameters or document), as described in the following topics:
  Messages for SOAP Document Style services (including EJB document and document-wrapped services), can be constructed as follows:
  To illustrate how messages are constructed during callouts to SOAP Document Style services, consider a service callout action configured as follows:
  myreq
  myresp
  reqheader
  respheader
  Assume also that at run time, the request document variable,
  myreq, is bound to the following XML.
  <sayHello xmlns="">
  <intVal>100</intVal>
  <string>Hello AquaLogic</string>
  </sayHello>
  At run time, the SOAP request header variable,
  reqheader, is bound to the following SOAP header.
  <soap:Header xmlns:soap=
  xmlns:
  <wsa:Action>...</wsa:Action>
  <wsa:To>...</wsa:To>
  <wsa:From>...</wsa:From>
  <wsa:ReplyTo>...</wsa:ReplyTo>
  <wsa:FaultTo>...</wsa:FaultTo>
  </soap:Header>
  In this example scenario, the full body of the message sent to the external service is shown in Listing 3-3 (the contents of the
  myreq and
  reqheader variables are shown in bold).
  <?xml version="1.0" encoding="UTF-8"?>
  <soapenv:Envelope xmlns:
  <soap:Header xmlns:soap=
  xmlns:
  <wsa:Action>...</wsa:Action>
  <wsa:To>...</wsa:To>
  <wsa:From>...</wsa:From>
  <wsa:ReplyTo>...</wsa:ReplyTo>
  <wsa:FaultTo>...</wsa:FaultTo>
  </soap:Header>
  <soapenv:Body>
  <sayHello xmlns="">
  <intVal>100</intVal>
  <string>Hello AquaLogic</string>
  </sayHello>
  </soapenv:Body>
  </soapenv:Envelope>
  Based on the configuration of the service callout action described above, the response from the service is assigned to the
  myresp variable. The full response from the external service is shown in Listing 3-4.
  <?xml version="1.0" encoding="UTF-8"?>
  <env:Envelope xmlns:env=""
  xmlns:xsi=""
  xmlns:soapenc=".
  org/soap/encoding/" xmlns:
  <env:Header/>
  <env:Body env:
  <m:sayHelloResponse xmlns:
  <result xsi:This message brought to you by Hello AquaLogic and the number 100
  </result>
  </m:sayHelloResponse>
  </env:Body>
  </env:Envelope>
  In this scenario, the
  myresp variable is assigned the value shown in Listing 3-5.
  <m:sayHelloResponse xmlns:
  <result ns0:
  This message brought to you by Hello AquaLogic and the number 100
  </result>
  </m:sayHelloResponse>
  Messages for SOAP RPC Style services (including EJB RPC services) can be constructed as follows:
  To illustrate how messages are constructed during callouts to SOAP RPC Style services, look at this example with the following configuration:
  input1is bound to a value 100.
  input2is bound to a string value:
  Hello AquaLogic.
  In this scenario, the body of the outbound message to the service is shown in Listing 3-6.
  <?xml version="1.0" encoding="UTF-8"?>
  <soapenv:Envelope xmlns:
  <soapenv:Body>
  <sayHello2 xmlns="">
  <intVal>100</intVal>
  <string >Hello AquaLogic</string>
  </sayHello2>
  </soapenv:Body>
  </soapenv:Envelope>
  The response returned by the service to which the call was made is shown in Listing 3-7.
  <?xml version="1.0" encoding="UTF-8"?>
  <env:Envelope xmlns:env=""
  xmlns:xsi=""
  xmlns:soapenc=""
  xmlns:
  <env:Header/>
  <env:Body env:
  <m:sayHello2Response xmlns:
  <result xsi:
  <message xsi:
  This message brought to you by Hello AquaLogic and the number 100
  </result>
  </m:sayHello2Response>
  </env:Body>
  </env:Envelope>
  The message context variable
  output1 is assigned the value shown in Listing 3-8.
  <message ns0:
  This message brought to you by Hello AquaLogic and the number 100</message>
  Messages for XML services can be constructed as follows:
  To illustrate how messages are constructed during callouts to XML services, take for example a service callout action configured as follows:
  Assume also that at run time, the request document variable,
  myreq, is bound to the following XML.
  <sayHello xmlns="">
  <intVal>100</intVal>
  <string>Hello AquaLogic</string>
  </sayHello>
  In this scenario:
  myreqvariable, as shown in Table 3-9.
  myresp, is shown in Listing 3-10.
  <m:sayHelloResponse xmlns:
  <result xsi:This message brought to you by Hello AquaLogic and the number 100
  </result>
  </m:sayHelloResponse>
  In the case of Messaging services:
  <binary-content ref=.../>reference XML.
  <binary-content ref= ... />reference XML, regardless of the actual content received.
  For example, if the request message context variable myreq is bound to an XML document of the following format:
  <hello>there</hello>, the outbound message contains exactly this payload. The response message context variable (myresp) is bound to a reference element similar to the following:
  <binary-content
  You can configure error handling at the message flow, pipeline, route node, and stage level. The types of errors that are received from an external service as the result of a service callout include transport errors, SOAP faults, responses that do not conform to an expected response, and so on.
  The
  fault context variable is set differently for each type of error returned. You can build your business and error handling logic based on the content of the
  fault variable. To learn more about
  $fault, see Fault Variable.
  When a transport error is received from an external service and there is no error response payload returned to ALSB by the transport provider (for example, in the case that an HTTP 403 error code is returned), the service callout action throws an exception, which in turn causes the pipeline to raise an error. The fault variable in a user-configured error handler is bound to a message formatted similarly to that shown in Listing 3-11.
  <con:fault xmlns:
  <con:errorCode>BEA-380000</con:errorCode>
  <con:reason>Not Found</con:reason>
  <con:details>
  .......
  </con:details>
  <con:location>
  <con:node>PipelinePairNode1</con:node>
  <con:Pipeline>PipelinePairNode1_request</con:Pipeline>
  <con:Stage>Stage1</con:Stage>
  </con:location>
  </con:fault>
  In the case that there is a payload associated with the transport error—for example, when an HTTP 500 error code is received from the business service and there is XML payload in the response—a message context fault is generated with the custom error code: BEA-382502.
  The following conditions must be met for a BEA-382502 error response code to be triggered as the result of a response from a service—when that service uses an HTTP or JMS transport:
  If the transport is HTTP, the
  ErrorResponseDetail element will also contain the HTTP error code returned with the response. The
  ErrorResponseDetail element in the fault contains error response payload received from the service. Listing 3-12 shows an example of the
  ErrorResponseDetail element.
  <ctx:Fault xmlns:
  <ctx:errorCode>BEA-382502<ctx:errorCode>
  <ctx:reason> Service callout has received an error response from the server</ctx:reason>
  <ctx:details>
  <alsb:ErrorResponseDetail xmlns:
  <alsb:detail> <![CDATA[
  . . .
  ]]>
  </alsb:detail> <alsb:http-response-code>500</alsb:http-response-code>
  </alsb:ErrorResponseDetail>
  </ctx:details>
  <ctx:location>. . .</ctx:location>
  </ctx:Fault>
  In case an external service returns a SOAP fault, the ALSB run time sets up the context variable
  $fault with a custom error code and description with the details of the fault. To do so, the contents of the 3 elements under the
  <SOAP-ENV:Fault> element in the SOAP fault are extracted and used to construct an ALSB fault element.
  Take for example a scenario in which a service returns the following error.
  <SOAP-ENV:Envelope xmlns:
  <SOAP-ENV:Body>
  <SOAP-ENV:Fault>
  <faultcode>SOAP-ENV:Client</faultcode>
  <faultstring>Application Error</faultstring>
  <detail>
  <message>That’s an Error!</message>
  <errorcode>1006</errorcode>
  </detail>
  </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>
  The
  <faultcode>,
  <faultstring>, and
  <detail> elements are extracted and wrapped in an
  <alsb:ReceivedFault> element. Note that the
  faultcode element in Listing 3-15
  contains a QName—any related namespace declarations are preserved. If the transport is HTTP, the
  ReceivedFault element will also contain the HTTP error code returned with the fault response.
  The generated
  <alsb:ReceivedFault> element, along with the custom error code and the error string are used to construct the contents of the
  fault context variable, which in this example takes a format similar to that shown in Listing 3-14.
  <ctx:Fault xmlns:hat’s an Error!
  <ctx:errorCode>BEA-382500<ctx:errorCode>
  <ctx:reason> service callout received a soap Fault response</ctx:reason>
  <ctx:details>
  <alsb:ReceivedFault xmlns:
  <alsb:faultcode
  xmlns:SOAP-ENV:Clien
  </alsb:faultcode>
  <alsb:faultstring>Application Error</alsb:faultstring>
  <alsb:detail>
  <message>T
  <errorcode>1006</errorcode>
  </alsb:detail>
  <alsb:http-response-code>500</alsb:http-response-code>
  </alsb:ReceivedFault>
  </ctx:details>
  <ctx:location> </ctx:location>
  </ctx:Fault>
  When a service returns a response message that is not what the proxy service run time expects, a message context fault will be generated and initialized with the custom error code BEA-382501. The details of the fault include the contents of the SOAP-Body element of the response. If the transport is HTTP, the
  ReceivedFault element will also contain the HTTP error code returned with the fault response.
  The XML schema definition of the service callout-generated fault details is shown in Listing 3-15.
  <xs:complexType
  <xs:sequence>
  <xs:element
  <xs:element
  <xs:element
  <xs:complexType>
  <xs:sequence>
  <xs:any
  </xs:sequence>
  <xs:anyAttribute
  </xs:complexType>
  <>
  The process described in the next paragraph constitutes an error handling pipeline for the stage of an error handler. In addition, an error pipeline can be defined for a pipeline (request or response) or for an entire proxy service.
  The error handler at the stage level is invoked for handling an error; If the stage-level error handler is not able to handle a given type of error, the pipeline error handler is invoked. If the pipeline-level error handler also fails to handle the error, the service-level error handler is invoked. If the service-level error handler also fails, the error is handled by the system.The following table summarizes the scope of the error handlers at various levels in the message flow.
  For more information on error messages and error handling, see “Error Messages and Handling” in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.
  You can handle errors by configuring a test that checks if an assertion is true and use the reply action configured false. You can repeat this test at various levels. Also you can have an error without an error handler at a lower level and handle it through an error handler at an higher level in message flow. In general, it is easier to handle specific errors at a stage level of the message flow and use error handlers at the higher level for more general default processing of errors that are not handled at the lower levels. It is good practice to explicitly handle anticipated errors in the pipelines and allow the service-level handler to handle unanticipated errors.
  A predefined context variable (the
  fault variable) is used to hold information about any error that occurs during message processing. When an error occurs, this variable is populated with information before the appropriate error handler is invoked. The
  fault variable is defined only in error handler pipelines and is not set in request and response pipelines, or in route or branch nodes. For additional information about
  $fault, see Predefined Context Variables
  .
  In the event of errors for request/response type inbound messages, it is often necessary to send a message back to the originator outlining the reason why an error occurred. You can accomplish this by using a Reply with Failure action after configuring the message context variables with the response you want to send. For example, when an HTTP message fails, Reply with Failure generates the
  HTTP 500 status. When a JMS message fails, Reply with Failure sets the
  JMS_BEA_Error property to true. The ALSB error actions are discussed in “Error Messages and Handling” in
  Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.
  An error handling pipeline is invoked if a service invoked by a proxy service returns a SOAP fault or transport error. Any received SOAP fault is stored in
  $body, so if a Reply with Failure is executed without modifying
  $body, the original SOAP fault is returned to the client that invoked the service. If a reply action is not configured, the system error handler generates a new SOAP fault message. The proxy service recognizes that a SOAP fault is returned because a HTTP error status is set, or the JMS property
  SERVER_Error is set to true.
  Some use cases require error reporting. You can use the report action in these situations. For example, consider a scenario in which the request pipeline reports a message for tracking purposes, but the service invoked by the route node fails after the reporting action. In this case, the reporting system logged the message, but there is no guarantee that the message was processed successfully, only that the message was successfully received.
  You can use the ALSB Console to track the message to obtain an accurate picture of the message flow. This allows you to view the original reported message indicating the message was submitted for processing, and also the subsequent reported error indicating that the message was not processed correctly. To learn how to configure a report action and use the data reported at run time, see Proxy Services: Actions in Using the AquaLogic Service Bus Console.
  This example shows how you can configure the report and reply actions in error handlers. The message flow shown in Figure 3-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 ALSB Console as shown in Figure 3-2.
  The stage is, in turn, configured with actions (replace, report, and reply) as shown in Figure 3-3.
  The actions control the behavior of the stage in the pipeline error handler as follows:
  faultcontext variable. The body variable element is specified by an XPath expression. The contents are replaced with the value returned by an XQuery expression—in this case
  $fault/ctx:reason/text()
  When an error occurs, the contents of the fault context variable are reported. The key name is
  errorCode, and the key value is extracted from the fault variable using the following XPath expression:
  ./ctx:errorCode. Key/value pairs are the key identifiers that identify these messages in the Dashboard at run time.
  To configure a report action and use the data reported at run time, see Proxy Services: Actions in Using the AquaLogic Service Bus Console.
  With Failure.
  For configuration information, see “Error Messages and Handling” in Proxy Services: Error Handlers in Using the AquaLogic Service Bus Console.
  When you do not know the service you need to invoke from the proxy service you are creating, you can use dynamic routing.
  For any given proxy service, you can use one of the following techniques to dynamically route messages:
  With this technique, the proxy service dynamically uses the service account of the endpoint business service to send user names and passwords in its outbound requests. For example, if a proxy service is routing a request to Business Service A, then the proxy service uses the service account from Business Service A to send user names and passwords in its outbound request. See Implementing Dynamic Routing.
  With this technique, to send user names and passwords in its outbound requests, the proxy service uses the service account of the statically defined business service, regardless of the URI to which the request is actually sent.
  For information on how to use this technique, see Implementing Dynamic Routing.
  You can use dynamic routing to determine the destination during the runtime of a proxy service. To achieve this you can use a routing table in an XML file to create an XQuery resource.
  An XML file or the Xquery resource can be maintained easily. At runtime you provide the entry in the routing table that will determine the routing or publishing destination of the proxy service.The XML file or the XQuery resource contains a routing table, which maps a logical identifier to (such as the name of a company) to the physical identifier (the fully qualified name of the service in ALSB). The logical identifier, which is extracted from the message, maps on to the physical identifier, which is the name of the service you want to invoke.
  In a pipeline the logical identifier is obtained with an XPath into the message.You assign the XML table in the XQuery resource to a variable. You implement a query against the variable in the routing table to extract the physical identifier based on the corresponding logical identifier. Using this variable you will be able to invoke the required service. The following sections describe how to implement dynamic routing.
  You can create an XQuery resource from the following XML file. Save this as sampleXquery.xml.
  <routing>
  <row>
  <logical>BEA Systems</logical>
  <physical>default/goldservice</physical>
  </row>
  <row>
  <logical>ABC Corp</logical>
  <physical>default/silverservice</physical>
  </row>
  </routing>
  This assigns the XQuery resource to this variable. The variable now contains the externalized routing table.
  <ctx: route>
  <ctx: service isProxy=’false’> {$routingtable/row[logical/text()=$logicalidentifier]/physical/text()}
  </ctx: service>
  </ctx: route>
  In the above code, replace
  $logicalidentifier by the actual XPath to extract the logical identifier from the message (example from
  $body).
  This extracts the XML used by the dynamic route action into this variable.
  ALSB provides read-access to databases from proxy services without requiring you to write a custom EJB or custom Java code and without the need for a separate database product like AquaLogic Data Services Platform. You can use the
  execute-sql() function to make a simple JDBC call to a database to perform simple database reads. Any SQL query is legal, from a query that gets a single tax rate for the supplied location to a query that does a complex join to obtain an order's current status from several underlying database tables.
  A database query can be used to get data for message enrichment, for routing decisions, or for customizing the behavior of a proxy service. Take for example a scenario in which an ALSB proxy service receives “request for quote” messages. The proxy service can route the requests based on the customer's priority to one of a number of quotation business services (say, standard, gold, or platinum level services). The proxy service can then perform a SQL-based augmentation of the results that those services return—for example, based on the selected ship method and the weight of the order, the shipping cost can be looked up and that cost added to the request for quote message.
  fn-bea:execute-sql()
  describes the syntax for the function and provides examples of its use. The
  execute-sql() function returns typed data and automatically translates values between SQL/JDBC and XQuery data models.
  You can store the returned element in a user-defined variable in an ALSB message flow.
  The following databases and JDBC drivers are supported using the
  execute-sql() function:
  Use non-XA drivers for datasources you use with the fn-bea:execute-sql() function—the function supports read-only access to the datasources.
  For complete information about database and JDBC drivers support in ALSB, see Supported Database Configurations in Supported Configurations for AquaLogic Service Bus.
  Databases other than the core set described in the preceding listing are also supported. However, for the core databases listed above, the XQuery engine does a better recognition and mapping of data types to XQuery types than it does for the non-core databases—in some cases, a core database’s proprietary JDBC extensions are used when fetching data. For the non-core databases, the XQuery engine relies totally on the standard type codes provided by the JDBC driver and standard JDBC resultset access methods.
  When designing your proxy service, you can enter XQueries inline as part of an action definition instead of entering them as resources. You can also use inline XQueries for conditions in If...Then... actions in message flows. For information about using the inline XQuery editor, see Creating Variable Structure Mappings.
  The message context is a set of variables that hold message context and information about messages as they are routed through the ALSB. Together, the
  header,
  body, and
  attachments variables, (referenced as
  $header,
  $body and
  $attachments in XQuery statements) represent the message as it flows through ALSB. The canonical form of the message is SOAP. Even if the service type is not SOAP, the message appears as SOAP in the ALSB message context.
  In a Message Context,
  $header contains a SOAP header element and
  $body contains a SOAP Body element. The Header and Body elements are qualified by the SOAP 1.1 or SOAP 1.2 namespace depending on the service type of the proxy service. Also in a Message Context,
  $attachments contains a wrapper element called attachments with one child attachment element per attachment. The attachment element has a body element with the actual attachment.
  When a message is received by a proxy service, the message contents are used to initialize the header, body, and attachments variables. For SOAP services, the Header and Body elements are taken directly from the envelope of the received SOAP message and assigned to
  $header and
  $body respectively. For non-SOAP services, the entire content of the message is typically wrapped in a Body element (qualified by the SOAP 1.1 namespace) and assigned to
  $body, and an empty Header element (qualified by the SOAP 1.1 namespace) is assigned to
  $header.
  Binary and MFL messages are initialized differently. For MFL messages, the equivalent XML document is inserted into the Body element that is assigned to
  $body. For binary messages, the message data is stored internally and a piece of reference XML is inserted into the Body element that is assigned to
  $body. The reference XML looks like
  <binary-content, where
  "..." contains a unique identifier assigned by the proxy service.
  The message context is defined by an XML schema. You must use XQuery expressions to manipulate the context variables in the message flow that defines a proxy service.
  The predefined context variables provided by ALSB can be grouped into the following types:
  For information about the predefined context variables, see Predefined Context Variables.
  The
  $body contains message payload variable. When a message is dispatched from ALSB you can decide the variables, whose you want to include in the outgoing message. That determination is dependent upon whether the target endpoint is expecting a SOAP or a non-SOAP message:
  $bodyis sent.
  $bodycontains the XML equivalent of the MFL document.
  $bodycontains the text. For text attachments, the body element in
  $attachmentscontains the text. If the contents are XML instead of simple text, the XML is sent as a text message.
  $bodycontains the XML. For XML attachments, the body element in
  $attachmentscontains the XML.
  <soap:Envelope>element. (The SOAP 1.1 namespace is used for SOAP 1.1 services, while the SOAP 1.2 namespace is used for SOAP 1.2 services.) If the body variable contains a piece of reference XML, it is sent.That is the referenced content is not substituted in the message.
  For non-SOAP services, if the Body element of
  $body contains a binary-content element, then the referenced content stored internally is sent ‘as is’, regardless of the target service type.
  For more information, see Message Context.
  The types for the message context variables are defined by the message context schema (
  MessageContext.xsd). When working with the message context variables in the BEA XQuery Mapper, you need to reference
  MessageContext.xsd, which is available in a JAR file,
  BEA_HOME/alsb_3.0/lib/sb-kernel-api.jar, and the transport-specific schemas, which are available at
  BEA_HOME/alsb_3.0/lib/transports/
  where
  BEA_HOME represents the directory in which you installed ALSB.
  To learn about the message context schema and the transport specific schemas, see Message Context Schema.
  Consider the following guidelines when you want to inspect or alter the message context:
  Content-Descriptionof the first attachment in a message:
  $attachments/ctx:attachment[1]/ctx:content-Description
  To obtain the second attachment
  $attachments/ctx:attachment[2]/ctx:body/*
  idvar, the assign action specification is:
  assign data($header/wsa:messageID to variable idvar
  $header,
  $body, and
  $attachmentsare never empty. However,
  $headercan contain an empty SOAP Header element,
  $bodycan contain an empty SOAP Body element, and
  $attachmentscan contain an empty attachment element.
  $body) as input to a transformation:
  The result of the transformation can be put back in
  $body with a replace action. That is replace the content of
  $body, which is the content of the Body element. For more information, see
  XQuery Transformations and
  XSL Transformations in Using the AquaLogic Service Bus Console.
  $inboundto
  $outbound. For information on adding an action, see “Adding an Action” in Proxy Services: Actions in Using the AquaLogic Service Bus Console. For an example, see Copying JMS Properties From Inbound to Outbound.
  It is assumed that the interfaces of the proxy services and of the invoked business service may be different. Therefore, ALSB does not propagate any information (such as the transport headers and JMS properties) from the inbound variable to the outbound variable.
  The transport headers for the proxy service’s request and response messages are in
  $inbound and the transport headers for the invoked business service’s request and response are in
  $outbound.
  For example, the following XQuery expression can be used in a case where the user-defined JMS properties for a one-way message (an invocation with no response) need to be copied from inbound message to outbound message:
  Use the transport headers action to set
  $inbound/ctx:transport/ctx:request/tp:headers/tp:user-header
  as the first child of:
  ./ctx:transport/ctx:request/tp:headers
  in the outbound variable.
  To learn how to configure the transport header action, see:
  The following sections describe 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.
  Use the Inline XQuery Expression Editor to enter simple XQueries that consist of the following:
  Inline XQueries can be used effectively to:
  $headeror
  $body.
  $attachments.
  for loop.
  for loopwith an Update action. 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.
  The inline XQuery and XPath editors allow you to declare a variable’s structure by mapping it to a type or element and then creating path expressions with a drag and drop action from the graphical representation of the structure. You can also enter the path expressions manually.
  You can use this feature directly for all user-defined variables, as well as
  $inbound,
  $outbound, and
  $fault. However, you cannot use it directly to access XML attachments in
  $attachments, headers in
  $header, or documents and RPC parameters in
  $body, with one exception— you can use it directly to access documents and parameters in
  $body for request messages received by a WSDL proxy service.
  To learn more about creating variable structures, see Creating Variable Structure Mappings.
  To learn more about XQuery engine support and the relationship with the DSP functions and operators, see XQuery Implementation.
  You typically use the Inline XQuery Expression Editor to enter simple XQueries that consist of the following:
  Examples of good uses of inline XQueries are:
  $headeror
  $body.
  $attachments.
  for loop.
  for loopwith an Update action.
  You can also use the Inline XQuery Expression Editor to create variable structures. For more information, see Using Variable Structures.
  You can use the Inline XQuery Expression Editor to create variable structures, with which you define the structure of a given variable for design purposes. For example, it is easier to browse the XPath variable in the console rather than viewing the XML schema of the XPath variable.
  In a typical programming language, the scope of variables is static. Their names and types are explicitly declared. The variable can be accessed anywhere within the static scope.
  In ALSB, there are some predefined variables, but you can also dynamically create variables and assign value to them using the assign action or using the loop variable in the for-loop. When a value is assigned to a variable, the variable can be accessed anywhere in the proxy service message flow. The variable type is not declared but the type is essentially the underlying type of the value it contains at any point in time.
  When you use the Inline XQuery Expression Editor, the XQuery has zero or more inputs and one output. Because you can display the structure of the inputs and the structure of the output visually in the Expression Editor itself, you do not need to open the XML schema or WSDL resources to see their structure when you create the Inline XQuery. The graphical structure display also enables you to drag and drop simple variable paths along the child axis without predicates, into the composed XQuery.
  Each variable structure mapping entry has a label and maps a variable or variable path to one or more structures. The scope of these mappings is the stage or route node. Because variables are not statically typed, a variable can have different structures at different points (or at the same point) in the stage or route node. Therefore, you can map a variable or a variable path to multiple structures, each with a different label. To view the structure, select the corresponding label with a drop-down list.
  The following sections describe how to create several types of variable structure mappings:
  This sample WSDL is used in most of the examples in this section. You need to save this WSDL as a resource in your configuration. For more information, see Creating the Resources You Need for the Examples.
  <definitions
  name="samplewsdl"
  targetNamespace=""
  xmlns=""
  xmlns:s0=""
  xmlns:s1=""
  xmlns:
  <types>
  <xs:schema
  attributeFormDefault="unqualified"
  elementFormDefault="qualified"
  targetNamespace=""
  xmlns:
  <xs:element
  <xs:complexType
  <xs:all>
  <xs:element
  <xs:element
  </xs:all>
  </xs:complexType>
  <xs:element
  <xs:complexType
  <xs:all>
  <xs:element
  <xs:element
  </xs:all>
  </xs:complexType>
  </xs:schema>
  </types>
  <message name="POTypeMsg">
  <part name="PO" type="s0:POType"/>
  <message name="InvoiceTypeMsg">
  <part name="InvReturn" type="s0:InvoiceType"/>
  <portType name="POPortType">
  <operation name="GetInvoiceType">
  <input message="s1:POTypeMsg"/>
  <output message="s1:InvoiceTypeMsg"/>
  </operation>
  </portType>
  <binding name="POBinding" type="s1:POPortType">
  <soap:binding
  <operation name="GetInvoiceType">
  <soap:operation
  <input>
  <soap:body
  </input>
  <output>
  <soap:body
  </output>
  </operation>
  </binding>
  </definitions>
  To make use of the examples that follow, you save the sample WSDL as a resource in your configuration and create the sample business service and proxy service that use the sample WSDL.
  The instructions that follow tell how to accomplish the tasks in the ALSB Console:
  SampleWSDL. This is a required field.
  SampleWSDLis included in the list of resources and saved in the current session. You must now create a proxy service that uses this WSDL, see Create a Proxy Service That Uses the Sample WSDL.
  ProxywithSampleWSDL. This is a required field.
  SampleWSDL, then select
  POBindingin the Select WSDL Definitions pane.
  ProxywithSampleWSDLis included in the list of resources and saved in the current session.To build message flow for this proxy service, see Build a Message Flow for the Sample Proxy Service.
  ProxywithSampleWSDLproxy service.
  ProxywithSampleWSDLicon, then click Add Pipeline Pair. PipelinePairNode1 is displayed, which includes request and response pipelines.
  ProxywithSampleWSDLproxy service.
  BusinesswithSampleWSDL. This is a required field.
  SampleWSDL, then select
  POBindingin the Select WSDL Definitions pane.
  BusinesswithSampleWSDLis included in the list of resources and is saved in the current session.
  In this example, you select a predefined variable structure using the proxy service
  ProxyWithSampleWSDL, which has a service type WSDL Web Service that uses the binding
  POBinding from
  SampleWSDL.
  The proxy service message flow needs to know the structure of the message in order to manipulate it. To achieve this, ALSB automatically provides a predefined structure that maps the
  body variable to the SOAP body structure as defined by the WSDL of the proxy service for all the messages in the interface. This predefined structure mapping is labeled
  body.
  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 in Figure 3-4.
  Suppose the proxy service
  ProxyWithSampleWSDL invokes a service callout to the business service
  BusinessWithSampleWSDL, which also has a service type WSDL Web Service that uses the binding
  POBinding from
  SampleWSDL. The operation
  GetInvoiceType is invoked.
  In this example, the message flow needs to know the structure of the response parameter in order to manipulate it. To achieve this, you can create a new variable structure that maps the response parameter variable to the type
  InvoiceType.
  To map a variable to a type:
  InvoiceTypeas 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.
  $InvoiceTypeas the path of the variable at run time.
  The variable structure InvoiceType is displayed in Figure 3-6.
  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:
  Invoiceas the meaningful display name for the variable structure you want to create.
  $Invoiceas the path of the variable structure at run time.
  SampleWSDL, then select Invoice under Elements in the Select WSDL Definitions pane.
  The variable structure Invoice is displayed in Figure 3-7.
  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
  PO element is a child of the Body element.
  SOAP Body element and theSOAP Body element and the
  To map a variable to a child element:
  body to
  PO
  as the meaningful display name for the variable structure you want to create.as the meaningful display name for the variable structure you want to create.
  $bodyas the path of the variable structure at run time.
  POelement:
  SampleWSDL, then select
  POunder Elements in the Select WSDL Definitions pane.
  POelement as a child of the body to
  POvariable structure.
  The variable structure body to PO is displayed in Figure 3-8.
  The
  ProxyWithSampleWSDL proxy service routes the message to the
  BusinessWithSampleWSDL business service, which also has a service type WSDL Web Service that uses the binding
  POBinding from
  SampleWSDL. In this example, the message flow must then manipulate the response. To achieve this, you can define a new structure that maps the body variable to the
  BusinessWithSampleWSDL business service. This results in a map of the body variable to the SOAP body for all the messages in the WSDL interface of the service.
  To map a variable to a business service:
  BusinessServiceas the meaningful display name for the variable structure.
  $bodyis already set as the default. This is the path of the variable structure at run time.
  BusinessWithSampleWSDLbusiness service, then click Submit. The business service is displayed under the Service field.
  BusinessServiceis included under Service Interface in the drop-down list of variable structures.
  The variable structure
  BusinessService is displayed in Figure 3-9.
  Modify the
  SampleWSDL so that the
  ProxyWithSampleWSDL proxy service receives a single attachment. The attachment is a Purchase Order. In this example, the proxy service message flow must then manipulate the Purchase Order. To achieve this, you can define a new structure that maps the body element in
  $attachments to the
  PO element, which is specified as a child element. The body element is specified as a variable path of the form:
  $attachments/ctx:attachment/ctx:body
  You can select and copy the body element from the predefined attachments structure, paste this element as the variable path to be mapped in the new mapping definition.
  To map a child element to another child element:
  The variable structure attachments is displayed in Figure 3-10.
  bodychild element in the attachments structure. The variable path of the body element is displayed in the Property Inspector on the right side of the page:
  $attachments/ctx:attachment/ctx:body
  bodyelement.
  PO
  attachmentas the meaningful display name for this variable structure.
  $attachments/ctx:attachment/ctx:body
  This is the path of the variable structure at run time.
  POelement:
  SampleWSDL, then select
  POunder Elements in the Select WSDL Definitions pane.
  POattachment is included under XML Type in the drop-down list of variable structures.
  $attachments/ctx:attachment/ctx:body/bea:PO/bea:id
  $attachments/ctx:attachment[2]/ctx:body/bea:PO/bea:id
  The following sections discuss quality of service features in ALSB messaging:
  ALSB 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 service transport is defined as JMS/XA; otherwise best effort QoS is supported.
  Quality of service is set in the
  qualityOfService element in the
  $outbound context variable.
  The following delivery guarantee types are provided in ALSB, shown in Table 3-9.
  For more detailed information about quality of service for other transports, see the documentation for the transport, at AquaLogic Service Bus Transports.
  To override the default exactly once quality of service attribute, you must set the
  qualityOfService in the outbound message context variable (
  $outbound). For more information, see Message Context Schema.
  You can override the default
  qualityOfService element attribute for the following:
  To override the
  qualityOfService element attribute, you must use the route options action to route or publish, and also select the checkbox for a service callout action. See Message Context Schema.
  The delivery guarantee supported when a proxy service publishes a message or routes a request to a business service depends on the following conditions:
  qualityOfServiceelement.
  However, if the inbound proxy service is a Local Transport and is invoked by another proxy service, the inbound transport of the invoking proxy service is responsible for the delivery guarantee. That is because a proxy service that invokes another proxy service is optimized into a direct invocation if the transport of the invoked proxy service is a Local Transport. For more information on transport protocols, see Proxy Services and Business Services in Using the AquaLogic Service Bus Console.
  The following rules govern delivery guarantees, shown in Table 3-10.
  The following are additional delivery guarantee rules:
  qualityOfServiceelement is set to
  exactly-once, any route node and publish actions executed in the request flow to a transactional destination are performed in the same transaction.
  qualityOfServiceelement is set to
  best-effort forany action in a route node, service callout or publish actions are executed outside of the request flow transaction. Specifically, for JMS, Tuxedo, Transactional Tuxedo, or EJB transport, the request flow transaction is suspended and the Transactional Tuxedo work is done without a transaction or in a separate transaction that is immediately committed.
  qualityOfServiceelement is set to
  exactly-once, all route, service callout, and publish actions are performed in the same transaction.
  qualityOfServiceelement is set to
  best-effort, all publish actions and service callout actions are executed outside of the response flow transaction. Specifically, for JMS, EJB, or transactional Tuxedo types of transports, the response flow transaction is suspended and the service is invoked without a transaction or in a separate transaction that is immediately committed.
  qualityOfServiceelement setting.
  The ALSB threading model works as follows:
  qualityOfServiceelement is
  best-effort.
  You may want to split a proxy service in the following situations:
  loanGateway1invokes another proxy service, say
  loanGateway2.Route to the proxy service
  loanGateway2from the proxy service
  loanGateway1where the proxy service
  loanGateway2uses JMS transport.
  qualityOfServiceelement of
  exactly-onceand uses an XA connection factory.
  In addition to configuring inbound retries for messages using JMS, you can configure outbound retries and load balancing. Load balancing, failover, and retries work in conjunction to provide performance and high availability. For each message, the list of URLs you provide as failover URLs is automatically ordered based on the load balancing algorithm into a failover sequence. If the retry count is N, the entire sequence is retried N times before stopping. The system waits for the specified retry interval before commencing subsequent loops through the sequence. After completing the retry attempts, if there is still an error, the error handler pipeline for the route node is invoked. For more information on the error handler pipeline, see “Adding Pipeline Error Handling” in Proxy Services in Using the AquaLogic Service Bus Console.
  To support interoperability with heterogeneous endpoints, ALSB allows you to control the content type, the JMS type, and the encoding used.
  ALSB does not make assumptions about what the external client or service needs, but uses the information configured for this purpose in the service definition. ALSB derives the content type for outbound messages from the service type and interface. Content type is a part of the e-mail and HTTP protocols.
  If the service type is:
  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 ALSB Console or in the ALSB Plug-in for WorkSpace Studio.
  You can override the content type in the outbound context variable (
  $outbound) for proxy services invoking a service, and in the inbound context variable (
  $inbound) for a proxy service response. For more information on
  $outbound and
  $inbound context variables, see Inbound and Outbound Variables.
  Encoding is also explicitly configured in the service definition for all outbound messages. For more information on service definitions, see Proxy Services in and Business Service in Using the AquaLogic Service Bus Console.
  In ALSB, you can restrict the message flow to a business service. This technique of restricting a message flow to a business service is known as throttling. For information, see Throttling in ALSB in the AquaLogic Service Bus Operations Guide.
  ALSB provides Web Service Interoperability (WS-I) compliance for SOAP 1.1 services in the run-time environment. The WS-I basic profile has the following goals:
  The WS-I basic profile is available at the following URL:.
  When you configure a proxy service or business service based on a WSDL, you can use the ALSB Console or the ALSB Plug-in for WorkSpace Studio to specify whether you want ALSB to enforce WS-I compliance for the service. For information on how to do this, see
  When you configure WS-I compliance for a proxy service, checks are performed on inbound request messages received by that proxy service. When you configure WS-I compliance for an invoked service, checks are performed when any proxy receives a response message from that invoked service. BEA recommends that you create an error handler for these errors, since by default, the proxy service SOAP client receives a system error handler-defined fault. For more information on creating fault handlers, see:
  For messages sent from a proxy service, whether as outbound request or inbound response, WS-I compliance checks are not explicitly performed. That is because the pipeline designer is responsible for generating most of the message content. However, the parts of the message generated by ALSB should satisfy all of the supported WS-I compliance checks. This includes the following content:
  The Enforce WS-I Compliance checkbox is displayed as shown in Figure 3-11.
  When you configure WS-I compliance checking for a proxy service or a business service, ALSB carries out the following checks, shown in Table 3-11.
  ALSB supports SOAP 1.1 and SOAP 1.2. A SOAP 1.1 proxy service can invoke a SOAP 1.2 business service or vice versa. The SOAP namespace is automatically changed by ALSB before invoking the business service. If a fault comes back from the business service it is automatically changed to the SOAP version of the proxy service. It is, however, up to the pipeline actions to map the SOAP header-related XML attributes (like
  MustUnderstand) between the two versions. It is also up to the pipeline actions to change the SOAP encoded name space for encoded envelopes.