12 Modeling Message Flow in Oracle Service Bus

This chapter describes the high-level aspects and concepts of creating and configuring pipelines, or message flows, using the Oracle Service Bus Console. Topics include pipeline components, message transformation, routing and service callout, error handling, message context, and quality of service (QoS).

In Service Bus, a message flow defines the implementation of a pipeline. You can create and configure pipelines in Oracle Service Bus Console or Oracle JDeveloper. You can also define message flow in split-joins. For more information, see Improving Service Performance with Split-Join.

The following sections describe pipelines in Service Bus:

• Pipeline Components

• Branching in Pipelines

• Configuring Actions in Stages and Route Nodes

• Performing Transformations in Pipelines

• Constructing Service Callout Messages

• Using Attachments with Service Callout Messages

• Handling Errors as the Result of a Service Callout

• Handling Errors in Pipelines

• Using Dynamic Routing

• Accessing Databases Using XQuery

• Understanding Message Context

• Working with Variable Structures

• Quality of Service

• Using Work Managers with Service Bus

• Content Types, JMS Type, and Encoding

• Throttling Pattern

• WS-I Compliance

• Converting Between SOAP 1.1 and SOAP 1.2

For instructions on creating and configuring pipelines using the Oracle Service Bus Console, see:

• Working with Pipelines in Oracle Service Bus Console

• Working with Pipeline Actions in Oracle Service Bus Console

For instructions on creating and configuring pipelines using Oracle JDeveloper, see:

• Working with Pipelines in Oracle JDeveloper

• Working with Pipeline Actions in Oracle JDeveloper

12.1 Pipeline Components

A pipeline is composed of components that define the logic for routing and manipulating messages as they flow through a pipeline. Nodes are configured to route messages through the message flow. Stages and actions contain rules for processing and transforming messages.

Table 12-1 describes the components available for defining pipelines.

Table 12-1 Pipeline Components

Component Type	Summary
Start node	Every pipeline begins with a start node. All messages enter the pipeline through the start node, and all response messages are returned to the client through the start node. There is nothing to configure in a start node.
Pipeline pair node	A pipeline pair node combines a single request pipeline and a single response pipeline in one top-level element. A pipeline pair node can have only one direct descendant in the pipeline. During request processing, only the request pipeline is executed when Service Bus processes a pipeline pair node. The execution path is reversed when Service Bus processes the response pipeline.
Stage	Request pipelines, response pipelines, and error handlers can contain stages, where you configure actions to manipulate messages passing through the pipeline. See also Configuring Actions in Stages and Route Nodes.
Error handler	An error handler can be attached to any node or stage, to handle potential errors at that location. See also Handling Errors in Pipelines.
Branch node	A branch node allows processing to proceed along exactly one of several possible paths. Operational branching is supported for WSDL-based services, where the branching is based on operations defined in the WSDL file. Conditional branching is supported for conditions defined in an XPath-based switch table. REST branching is supported for untyped native REST services, where the branching is based on logic derived from the media type consumed, relative URI, and the HTTP verb. Operational branching is also supported for typed REST services, where the branching is based on methods defined in the WADL file. See also Branching in Pipelines.
Route node	A route node performs request/response communication with another service or component. It represents the boundary between request and response processing for the pipeline. When the route node dispatches a request message, the request processing is considered complete. When the route node receives a response message, the response processing begins. The route node supports conditional routing as well as request and response transformations. Because a route node represents the boundary between request and response processing, it cannot have any descendants in the pipeline. See also Configuring Actions in Stages and Route Nodes.

12.1.1 Building a Message Flow

In general, a message flow is likely to be designed in one of the following ways:

• For non-operational services (services that are not based on WSDL files with operations), the flow consists of a single pipeline pair at the root followed by a route node.

• For operational services, the flow consists of a single pipeline pair at the root, followed by a branch node based on an operation (or consumed media type, path, or HTTP verb, for a REST branch), with each branch consisting of a pipeline pair followed by a route node.

12.1.2 Message Execution

Table 12-2 and Table 12-3 briefly describe how request and response messages are processed in a typical message flow.

Table 12-2 Path of a Request Message During a Message Flow

Pipeline Node	What Happens During Message Processing?
Request Processing	Request Processing container.
Start node	Request processing begins at the start node.
Pipeline pair node	Executes the request pipeline only.
Branch node	Evaluates the branch table and proceeds down the relevant branch.
Route node	Performs the route along with any request transformations. In the pipeline, regardless of whether routing takes place or not, the route node represents the transition from processing a request to processing a response. At the route node, the direction of the message flow is reversed. If a request path does not have a route node, the response processing is initiated in the reverse direction without waiting for any response.

Table 12-3 Path of a Response Message During a Message Flow

Pipeline Node	What Happens During Message Processing?
Response Processing	Skips any branch nodes and continues with the node that preceded the branch.
Route node	Executes any response transformations.
Branch node	Skips any branch nodes and continues with the node that preceded the branch.
Pipeline pair node	Executes the response pipeline.
Start node	Sends the response back to the client.

12.2 Branching in Pipelines

Three kinds of branching are supported in pipelines: operational branching, configured in an operational branch node, conditional branching, configured in a conditional branch node, and REST branching, configured in a REST branch node.

12.2.1 Operational Branching

When message flows define WSDL-based pipeline services, operation-specific processing is required. When you create an operational branch node in a pipeline, you can build branching logic based on the operations defined in the WSDL file.

You must use operational branching when a pipeline is based on a WSDL file with multiple operations. You can consider using an operational branch node to handle messages separately for each operation. You can also use operational branching when a pipeline is based on a typed native REST service, where the branching is based on methods defined in the WADL file.

12.2.2 Conditional Branching

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 pipeline), or you can configure the condition to branch based on the results of an XPath expression defined in the branch itself.

At runtime, 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 pipeline: one for each branch, including the default branch. You should always define a default branch. You should design the pipeline 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 pipeline 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 using 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="http://www.openuri.org/";
declare namespace com="oracle.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 pipeline 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 pipeline or in a stage or route node. When making your decision, remember that configuring branches in the pipeline can be awkward in the design interface if a large number of branches extend from the branch node.

12.2.3 REST Branching

When message flows define REST-based pipeline services, operation-specific processing is required. When you create a REST branch node in a pipeline, you can build branching logic based on the consumed media type, relative URI, or HTTP Verb.

The REST Branch Node can only be used in untyped Native REST pipelines or untyped Native REST templates. See Adding REST Branches to Pipelines in JDeveloper and How to Add REST Branches to Pipelines in the Console for more information.

12.3 Configuring Actions in Stages and Route Nodes

Actions provide instructions for handling messages in pipeline stages, error handler stages, and route nodes. The context determines which actions are available, as described in the following sections:

• Communication Actions

• Flow Control Actions

• Message Processing Actions

• Reporting Actions

See Also

• Working with Pipeline Actions in Oracle Service Bus Console

• Working with Pipeline Actions in Oracle JDeveloper

12.3.1 Communication Actions

Communication actions control message flow. Table 12-4 describes the communication actions.

Table 12-4 Communication Actions

Action	Use to...	Available in
Dynamic Publish	Publish a message to a service specified by an XQuery expression.	Pipeline stage Error handler stage Route node
Publish	Identify a statically specified target service for a message and to configure how the message is packaged and sent to that service.	Pipeline stage Error handler stage Route node
Publish Table	Publish a message to zero or more statically specified services. Switch-style condition logic is used to determine at runtime which services will be used for the publish.	Pipeline stage Error handler stage Route node
Routing Options	Modify any or all of the following properties in the outbound request: URI, Quality of Service, Mode, Retry parameters, Message Priority, Verb, Relative Path, HTTP Accept Header, and Query parameters.	Route node
Service Callout	Configure a synchronous (blocking) callout to a Service Bus-registered proxy service, business service, pipeline or split-join. See Constructing Service Callout Messages.	Pipeline stage Error handler stage Route node
Transport Headers	Set the header values in messages. See Configuring Transport Headers in Pipelines.	Pipeline stage Error handler stage Route node
Dynamic Routing	Assign a route for a message based on routing information available in an XQuery resource.	Route Node
Routing	Identify a target service for the message and configure how the message is routed to that service.	Route Node
Routing Table	Select different routes based upon the results of a single XQuery expression.	Route Node

12.3.2 Flow Control 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 12-5 describes the flow control actions.

Table 12-5 Flow Control Actions

Action	Use to...	Available in
For each	Iterate over a sequence of values and execute a block of actions	Pipeline stage Error handler stage Route node
If... then...	Perform an action or set of actions conditionally, based on the Boolean result of an XQuery expression or an inline JavaScript expression.	Pipeline stage Route node Error handler stage
Raise error	Raise an exception with a specified error code (a string) and description.	Pipeline stage Error handler stage Route node
Reply	Specify that an immediate reply be sent to the invoker. The reply action can be used in the request, response or error pipeline. You can configure it to result in a reply with success or failure. In the case of reply with failure where the inbound transport is HTTP, the reply action specifies that an immediate reply is sent to the invoker.	Pipeline stage Error handler stage Route node
Resume	Resume message flow after an error is handled by an error handler. This action has no parameters and can only be used in error handlers.	Error handler stage
Skip	Specify that at runtime, the execution of this stage is skipped and the processing proceeds to the next stage in the pipeline. This action has no parameters and can be used in the request, response or error pipelines.	Pipeline stage Error handler stage Route node

12.3.3 Message Processing Actions

The actions in this category process the message flow. Table 12-6 describes the message processing actions.

Table 12-6 Message Processing Actions

Action	Use to...	Available in
Assign	Assign the result of an XQuery or XSLT expression to a context variable.	Pipeline stage Error handler stage Route node
Delete	Delete a context variable or a set of nodes specified by an XPath expression.	Pipeline stage Error handler stage Route node
Insert	Insert the result of an XQuery or XSLT expression at an identified place relative to nodes selected by an XPath expression.	Pipeline stage Error handler stage Route node
Java Callout	Invoke a Java method from within the pipeline.	Pipeline stage Error handler stage Route node
JavaScript	Manipulate an XML or JSON payload using a JavaScript expression.	Pipeline stage Error handler stage Route node
MFL Translate	Convert message content from XML to non-XML, or vice versa, in the message pipeline. An MFL is a specialized XML document used to describe the layout of binary data. It is an Oracle proprietary language used to define rules to transform formatted binary data into XML data, or vice versa.	Pipeline stage Error handler stage Route node
nXSD Translate	Convert message content from XML to native format data, or vice versa, in the message pipeline.	Pipeline stage Error handler stage Route node
Rename	Rename elements selected by an XPath expression without modifying the contents of the element.	Pipeline stage Error handler stage Route node
Replace	Replace a node or the contents of a node specified by an XPath expression. The node or its contents are replaced with the value returned by an XQuery expression. A replace action can be used to replace simple values, elements and even attributes. An XQuery expression that returns nothing is equivalent to deleting the identified nodes or making them empty, depending upon whether the action is replacing entire nodes or just node contents. The replace action is one of a set of Update actions.	Pipeline stage Error handler stage Route node
Validate	Validate elements selected by an XPath expression against an XML schema element or a WSDL resource. You can validate global elements only; Service Bus does not support validation against local elements.	Pipeline stage Error handler stage Route node

12.3.4 Reporting 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 12-7 describes the reporting actions.

Table 12-7 Reporting Actions

Action	Use to...	Available in
Alert	Generate alerts based on message context in a pipeline, to send to an alert destination. Unlike SLA alerts, notifications generated by the alert action are primarily intended for business purposes, or to report errors, and not for monitoring system health. Alert destination should be configured and chosen with this in mind. If pipeline alerting is not enabled for the service or enabled at the domain level, the configured alert action is bypassed during message processing.	Pipeline stage Error handler stage Route node
Log	Construct a message to be logged and to define a set of attributes with which the message is logged.	Pipeline stage Error handler stage Route node
Report	Enable message reporting for a pipeline. An XQuery/XSLT or JavaScript expression is used to create the data that is reported to the Service Bus dashboard. You use key value pairs to extract key identifiers from any message context variable or message payload, and ignore the rest of the message.	Pipeline stage Error handler stage Route node

12.3.5 Configuring Transport Headers in Pipelines

The transport header action is a communication type action, and it is available in pipeline stages and error handler stages.

12.3.5.1 Global Pass Through and Header-Specific Copy Options

The following options are available when you configure a transport headers action:

• The Pass all Headers through Pipeline option specifies that at runtime, the transport headers action passes all headers through from the inbound message to the outbound message or vice versa. Every header in the source set of headers is copied to the target header set, overwriting any existing values in the target header set.

• The Copy Header from Inbound Request option and the Copy Header from Outbound Response options specifies that at runtime, the transport headers action copies the specific header with which this option is associated from the inbound message to the outbound message or vice versa.

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.

Caution:

Because transport headers are specific to the transport types, it is recommended that the pass-through (or copy) options only be used to copy headers between services of the same transport type. Passing (or copying) headers between services of different transport types can result in an error if the header being passed is not accepted by the target transport. For the same reasons, be careful when you specify a header name using the Set Header option.

12.3.5.2 How the Runtime Uses Transport Headers Settings

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:

• Specified using an XQuery expression

• Passed through from the source to the target service

• Deleted while going from the source to the target service

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

Limitations to Transport Header Values you Specify in Transport Header Actions describes the transport headers that are ignored or overwritten at runtime and other limitations that exist for specific transport headers.

12.3.5.3 Limitations to Transport Header Values you Specify in Transport Header Actions

Table 12-8 describes the transport headers that are ignored or overwritten at runtime and other limitations that exist for specific transport headers.

Table 12-8 Limitations to Transport Header Values You Specify in Transport Header Actions

Transport	Description of Limitation...	Outbound Request Header	Inbound Response Header
HTTP	Service Bus runtime may overwrite these headers in the binding layer when preparing the message for dispatch. If these headers are modified, $inbound and $outbound are updated accordingly.	Content-Type	Content-Type
HTTP	The underlying transport may ignore these headers and use different values when sending the message. Any changes done by the transport will not be reflected in $inbound or $outbound.	Accept Content-Length Connection Host User-Agent	Content-Length Date Transfer-Encoding
JMS	Can only be set when the request is with respect to a one-way service or a request/response service based on JMSMessageID correlation. If sending to a request/response service based on JMSCorrelationID correlation, these headers are overwritten at runtime.	JMSCorrelationID	JMSCorrelationID
JMS	The Service Bus runtime sets these headers. In other words, any specifications you make for these headers at design time are overwritten at runtime. Note: Header names with the JMS_IBM prefix are to be used with respect to destinations hosted by an IBM MQ server.	JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount JMSXUserID JMS_IBM_PutDate JMS_IBM_PutTime JMS_IBM_PutApplType JMS_IBM_Encoding JMS_IBM_Character_Set	JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount JMSXUserID JMS_IBM_PutDate JMS_IBM_PutTime JMS_IBM_PutApplType JMS_IBM_Encoding JMS_IBM_Character_Set
JMS	Because IBM MQ does not allow certain properties to be set by a client application, if you set these headers with respect to an IBM MQ destination, a runtime exception is raised.	JMSXDeliveryCount JMSXUserID JMSXAppID	JMSXDeliveryCount JMSXUserID JMSXAppID
JMS	These headers cannot be deleted when the Pass all Headers through Pipeline option is also specified.	JMSDeliveryMode JMSExpiration JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount	JMSDeliveryMode JMSExpiration JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount JMSCorelationID—if the inbound message has the correlation ID set. For example, if the inbound response comes from a registered JMS business service
FTP and File	No limitations. In other words you can set or delete the header(s) for File and FTP transports and your specifications are honored by the Service Bus runtime. Note: For FTP and file proxies, there is an transport request header fileName. The value of this request header is the name of the file being polled.	N/A	N/A
Email	The Service Bus runtime sets these headers. In other words, any specifications you make for these headers at design time are overwritten at runtime.	Content-Type	Content-Type
Email	Service Bus does not use these headers in outbound requests. If you set them dynamically (that is, if you set them in the $outbound headers section), Service Bus ignores them. These headers are received in $inbound. Date is the time the mail was sent by the sender. From is retrieved from incoming mail headers.	From (Name) Date	N/A

Note:

The same limitations around setting certain transport headers and metadata are true when you set the inbound and outbound context variables, and when you use the Service Bus Test Console to test your proxy or business services.

12.4 Performing Transformations in Pipelines

Transformation maps describe the mapping between two data types. Service Bus 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 pipeline at which you specify a transformation depends on whether:

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

  Publish actions identify a target service for a message and configure how the message is packaged and sent to that service. Service Bus 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.

• You perform the transformation on the response or request message regardless of the route destination. In this case, you can configure the transformations in the request or response pipeline stages.

12.4.1 Transformations and Publish Actions

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

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 email, 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. After the publish action, the message in its state prior to the publish action continues through the message flow, as described in the following section.

12.4.1.1 Publish Action Behavior with Quality of Service

This section describes how the publish action behaves with different quality of service (QoS) settings.

Exactly-Once – When QoS is exactly-once, the publish action waits (blocking call) until the response from the target service is available, although the response itself is discarded. When the target is a business service, the publish action waits until the business service response is available. When the target is a proxy service, the publish action waits until the proxy service's response pipeline completes.

Best-Effort – When QoS is best-effort and the target service is a one-way proxy service or a one-way business service with retry count > 0, the publish action waits until the target service returns. With a one-way target service there is no response, but the publish action waits until the request is delivered.

If the target proxy or business service is request-response or a one-way business service with retry count = 0, the publish action does not wait for the response (non-blocking call).

12.4.2 Transformations and Route Nodes

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

• Message Context

• Transforming Data with XQuery and Transforming Data with XSLT

12.5 Constructing Service Callout Messages

When Service Bus makes a call to a service using 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:

• SOAP Document Style Services

• SOAP RPC Style Services

• XML Services

• Messaging Services

12.5.1 SOAP Document Style Services

Messages for SOAP Document Style services (including EJB document and document-wrapped services), can be constructed as follows:

• The variable assigned for the request document contains the SOAP body.

• The variable assigned for the SOAP request header contains the SOAP header.

• The response must be a single XML document—it is the content of the SOAP body plus the SOAP header (if specified)

To illustrate how messages are constructed during callouts to SOAP Document Style services, consider a service callout action configured as follows:

• Request Document Variable: myreq

• Response Document Variable: myresp

• SOAP Request Header: reqheader

• SOAP Response Header: respheader

Assume also that at runtime, the request document variable, myreq, is bound to the following XML.

Example - Content of Request Variable (myreq)

<sayHello xmlns="http://www.openuri.org/">
    <intVal>100</intVal>
    <string>Hello Oracle</string>
</sayHello>

At runtime, the SOAP request header variable, reqheader, is bound to the following SOAP header.

Example - Content of SOAP Request Header Variable (reqheader)

<soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing">
    <wsa:Action>...</wsa:Action>
    <wsa:To>...</wsa:To>
    <wsa:From>...</wsa:From>
    <wsa:ReplyTo>...</wsa:ReplyTo>
    <wsa:FaultTo>...</wsa:FaultTo>
  </soap:Header>

In this example scenario, the full body of the message sent to the external service is shown in the following example (the contents of the myreq and reqheader variables are shown in bold).

Example - Message Sent to the Service as a Result of Service Callout Action

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing">
        <wsa:Action>...</wsa:Action>
        <wsa:To>...</wsa:To>
        <wsa:From>...</wsa:From>
        <wsa:ReplyTo>...</wsa:ReplyTo>
        <wsa:FaultTo>...</wsa:FaultTo>
    </soap:Header>
    <soapenv:Body>
        <sayHello xmlns="http://www.openuri.org/">
            <intVal>100</intVal>
            <string>Hello Oracle</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 the following example.

Example - Response Message From the Service as a Result of Service Callout Action

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.
org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <env:Header/>
    <env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <m:sayHelloResponse xmlns:m="http://www.openuri.org/">
            <result xsi:type="xsd:string">This message brought to you by Hello Oracle and the number 100
            </result>
        </m:sayHelloResponse>
    </env:Body>
</env:Envelope>

In this scenario, the myresp variable is assigned the value shown in the following example.

Example - Content of Response Variable (myresp) as a Result of Service Callout Action

<m:sayHelloResponse xmlns:m="http://www.openuri.org/">
    <result ns0:type="xsd:string" xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance">
This message brought to you by Hello Oracle and the number 100
    </result>
</m:sayHelloResponse>

12.5.2 SOAP RPC Style Services

Messages for SOAP RPC Style services (including EJB RPC services) can be constructed as follows:

• Request messages are assembled from message context variables.

  • The SOAP body is built based on the SOAP RPC format (operation wrapper, parameter wrappers, and so on).

  • The SOAP header is the content of the variable specified for the SOAP request header, if one is specified.

  • Part as element—the parameter value is the variable content.

  • Part as simple type—the parameter value is the string representation of the variable content.

  • Part as complex type—the parameter corresponds to renaming the root of the variable content after the parameter name.

• Response messages are assembled as follows:

  • The output content is the content of SOAP header, if a SOAP header is specified.

  • Part as element—the output content is the child element of the parameter; there is at most one child element.

  • Part as simple/complex type—the output content is the parameter itself.

To illustrate how messages are constructed during callouts to SOAP RPC Style services, look at this example with the following configuration:

• A message context variable input1 is bound to a value 100.

• A message context variable input2 is bound to a string value: Hello Oracle.

• A service callout action configured as follows:

  • Request Parameter intval: input1

  • Request Parameter string: input2

  • Response Parameter result: output1

In this scenario, the body of the outbound message to the service is shown in the following example.

Example - Content of Outbound Message

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <sayHello2 xmlns="http://www.openuri.org/">
            <intVal>100</intVal>
            <string >Hello Oracle</string>
        </sayHello2>
    </soapenv:Body>
</soapenv:Envelope>

The response returned by the service to which the call was made is shown in the following example.

Example - Content of Response Message From the helloWorld Service

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <env:Header/>
    <env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <m:sayHello2Response xmlns:m="http://www.openuri.org/">
            <result xsi:type="n1:HelloWorldResult" xmlns:n1="java:">
                <message xsi:type="xsd:string">
                This message brought to you by Hello Oracle and the number 100
                </message>
            </result>
        </m:sayHello2Response>
    </env:Body>
</env:Envelope>

The message context variable output1 is assigned the value shown in the following example.

Example - Content of Output Variable (output1)

<message ns0:type="xsd:string" xmlns:ns0="http://www.w3.org/2001/XMLSchema-intance">
This message brought to you by Hello Oracle and the number 100</message>

12.5.3 XML Services

Messages for XML services can be constructed as follows:

• The request message is the content of the variable assigned for the request document.

• The content of the request variable must be a single XML document.

• The output document is the response message.

To illustrate how messages are constructed during callouts to XML services, take for example a service callout action configured as follows:

• Request Document Variable: myreq

• Response Document Variable: myresp

Assume also that at runtime, the request document variable, myreq, is bound to the following XML.

Example - Content of myreq Variable

<sayHello xmlns="http://www.openuri.org/">
    <intVal>100</intVal>
    <string>Hello Oracle</string>
</sayHello>

In this scenario:

• The outbound message payload is the value of the myreq variable, as shown in the previous example.

• The response and the value assigned to the message context variable, myresp, is shown in the following example.

Example - Content of myresp Variable

<m:sayHelloResponse xmlns:m="http://www.openuri.org/">
     <result xsi:type="xsd:string">This message brought to you by Hello Oracle and the number 100
     </result>
</m:sayHelloResponse>

12.5.4 Messaging Services

In the case of Messaging services:

• The request message is the content of the request variable. The content can be simple text, XML, or binary data represented by an instance of <binary-content ref=.../> reference XML.

• Response messages are treated as binary, so the response variable will contain an instance of <binary-content ref= ... /> reference XML, regardless of the actual content received.

For example, if the request message context variable myreq is bound to an XML document of the following format: <hello>there</hello>, the outbound message contains exactly this payload. The response message context variable (myresp) is bound to a reference element similar to the following:

<binary-content ref=" cid:1850733759955566502-2ca29e5c.1079b180f61.-7fd8"/>

12.6 Using Attachments with Service Callout Messages

You can specify an optional variable to hold attachments for the outbound request and another variable to hold attachments from the outbound response. The Request Attachments and Response Attachments variables are used to specify the request and response attachments respectively.

You can specify attachments for the request messages, response messages, or both. The following code shows the schema type for the Request Attachments and Response Attachments variables:

<!-- The schema type for  -->
    <complexType name="AttachmentsType">
        <sequence>
            <!-- the 'attachments' variable is just a series of attachment elements -->
            <element ref="mc:attachment" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <!-- Each attachment in the 'attachments' variable is represented by an instance of this element -->
    <element name="attachment" type="mc:AttachmentType"/>
    <complexType name="AttachmentType">
        <all>
            <!-- Set of MIME headers associated with attachment -->
            <element name="Content-ID" type="string" minOccurs="0"/>
            <element name="Content-Type" type="string" minOccurs="0"/>
            <element name="Content-Transfer-Encoding" type="string" minOccurs="0"/>
            <element name="Content-Description" type="string" minOccurs="0"/>
            <element name="Content-Location" type="string" minOccurs="0"/>
            <element name="Content-Disposition" type="string" minOccurs="0"/>
            <!-- Contains the attachment content itself, either in-lined or as <binary-content/> -->
            <element name="body" type="anyType"/>
        </all>
    </complexType>

The Request Attachments and Response Attachments variables are available regardless of the target service binding type and transport type.

12.6.1 Example of Using Attachments with SOAP-Document Style Services

The following example illustrates a sample WLS web service with a SOAP-document style JWS. The web service has a single method that returns the input argument as its return value. The input argument and the return value are sent and received as attachments.

Example - Sample SOAP-Document Style JWS

import javax.activation.DataHandler;

@WebService(name="AttachmentsService", targetNamespace="http://example.org")
@Binding(Binding.Type.SOAP12)
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="testAttachments", serviceUri="AttachmentsService")
public class AttachmentsServiceImpl
{
    @WebMethod(action="echoAttachmentAction")
      public DataHandler echoAttachment(DataHandler dh) 
      {
           return dh;
      }
}

The following example illustrates the WSDL document corresponding to the web service in the previous Sample SOAP-Document Style JWS example.

Example - WSDL Document Corresponding to the Web Service

<wsdl:definitions name="AttachmentsServiceImplServiceDefinitions"
 targetNamespace="http://example.org" 
                           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
                           xmlns:exam="http://example.org" 
                           xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/">
  <wsdl:types>
    <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
 targetNamespace="http://example.org" xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:import namespace="http://www.bea.com/servers/wls90/wsee/attachment"/>
      <xs:element name="echoAttachment">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="dh" type="att:datahandler"
 xmlns:att="http://www.bea.com/servers/wls90/wsee/attachment"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="echoAttachmentResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="return" type="att:datahandler"
 xmlns:att="http://www.bea.com/servers/wls90/wsee/attachment"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
    <xs:schema targetNamespace="http://www.bea.com/servers/wls90/wsee/attachment"
 xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:complexType name="datahandler">
        <xs:annotation>
          <xs:documentation>Internal type created by WebLogic - Do not
 edit!</xs:documentation>
        </xs:annotation>
      </xs:complexType>
    </xs:schema>
  </wsdl:types>
  <wsdl:message name="echoAttachment">
    <wsdl:part element="exam:echoAttachment" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="echoAttachmentResponse">
    <wsdl:part element="exam:echoAttachmentResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:portType name="AttachmentsService">
    <wsdl:operation name="echoAttachment" parameterOrder="parameters">
      <wsdl:input message="exam:echoAttachment"/>
      <wsdl:output message="exam:echoAttachmentResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="AttachmentsServiceImplServiceSoapBinding"
 type="exam:AttachmentsService">
    <soap12:binding style="document"
 transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="echoAttachment">
      <soap12:operation soapAction="echoAttachmentAction" style="document"/>
      <wsdl:input>
        <soap12:body parts="parameters" use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap12:body parts="parameters" use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="AttachmentsServiceImplService">
    <wsdl:port binding="exam:AttachmentsServiceImplServiceSoapBinding"
 name="AttachmentsServiceSoapPort">
      <soap12:address
 location="http://adc4110062:7001/testAttachments/AttachmentsService"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

Next, the preceding WSDL file is registered in Service Bus and a business service is registered with this WSDL SOAP port. The service callout action is configured as follows:

• Request Document Variable: reqDoc

• Response Document Variable: respDoc

• Request Attachments Variable: reqatt

• Response Attachments Variable: respatt

See Adding Service Callout Actions in the Console for more information on adding and configuring the service callout action.

The following examples show the values of the request document and request attachment context variables when the service callout action is invoked.

Example - Value of the Request Document Variable (reqDoc) at Service Callout Invocation

<m:echoAttachment xmlns:m="http://example.org">
      <m:dh href="cid:dh"/>
</m:echoAttachment>

Example - Value of the Request Attachments Variable (reqatt) at Service Callout Invocation

<con:attachments xmlns:con="http://www.bea.com/wli/sb/context">
  <con:attachment>
    <con:Content-Type>image/jpeg</con:Content-Type>
    <con:Content-ID><dh></con:Content-ID>
    <con:body>
      <con:binary-content ref="cid:-6175a307:131072c66ef:-7f56"/>
    </con:body>
  </con:attachment>
</con:attachments>

In the preceding example, the attachment body uses a binary content ref that points to a source stored in the source repository. This can be the result of java callout, MFL transformation, etc.

Note:

Make sure that the href value in the SOAP envelope matches the Content-ID header of the attachment part. This links the body of the message with the corresponding attachment. If the values do not match, you may receive a SOAP Fault from the JWS invocation.

The following example shows a sample outbound payload for the service callout action.

Example - Outbound Payload of the Service Callout

POST http://localhost:7001/default/test1

Content-Type: multipart/related;boundary="----=_Part_0
_39288954.1310192119320";type="text/xml";start="<soapPart>"

------=_Part_0_39288954.1310192119320
Content-Type: application/soap+xml; charset=utf-8
Content-Transfer-Encoding: 8bit
Content-ID: <soapPart>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
    <env:Header/>
   <env:Body>
      <m:echoAttachment xmlns:m="http://example.org">
           <m:dh href="cid:dh"/>
     </m:echoAttachment>
   </env:Body>
</env:Envelope>

------=_Part_0_39288954.1310192119320
Content-Type: image/jpeg
Content-ID: <dh>

... binary content of some JPG file ….
------=_Part_0_39288954.1310192119320--

The following example illustrates the JWS response to the service invocation.

Example - Java Web Service (JWS) Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: multipart/related;boundary="----=_Part_13
_1460020940.1310334461289";type="text/xml";start="<soapPart>"
------=_Part_13_1460020940.1310334461289
Content-Type: application/soap+xml; charset=utf-8
Content-Transfer-Encoding: 8bit
Content-ID: <soapPart>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
     <env:Body>
          <m:echoAttachmentResponse xmlns:m="http://example.org">
                 <return xmlns="http://example.org" href="cid:return"/>
          </m:echoAttachmentResponse>
     </env:Body>
</env:Envelope>

------=_Part_13_1460020940.1310334461289
Content-Type: image/jpeg
Content-ID: <return>


…. binary content of some JPG file …
------=_Part_13_1460020940.1310334461289--

The following examples show the values of the context variables in the service callout response.

Example - Value of the Response Document Variable (respDoc)

<m:echoAttachmentResponse xmlns:m="http://example.org">
     <return xmlns="http://example.org" href="cid:return"/>
</m:echoAttachmentResponse>

Example - Value of the Response Attachments Variable (respatt)

<con:attachments xmlns:con="http://www.bea.com/wli/sb/context">
  <con:attachment>
    <con:Content-Type>image/jpeg</con:Content-Type>
    <con:Content-ID><return></con:Content-ID>
    <con:body>
        <con:binary-content ref="cid:-6175a307:131072c66ef:-7f57"/>
    </con:body>
  </con:attachment>
</con:attachments>

12.6.2 Example of Using Attachments with SOAP RPC Style Service

The following example shows a SOAP RPC-style WSDL file. The WSDL file is registered in Service Bus as a business service. A service callout action is used to invoke this business service.

Example - WSDL Document for the Business Service

<?xml version="1.0"?>
<wsdl:definitions xmlns:types="http://example.com/mimetypes"
                  xmlns:ref="http://ws-i.org/profiles/basic/1.1/xsd"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
                  targetNamespace="http://example.com/mimewsdl"
                  xmlns:tns="http://example.com/mimewsdl">

    <wsdl:types>
        <xsd:schema targetNamespace="http://example.com/mimetypes"
                    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

            <xsd:import namespace="http://ws-i.org/profiles/basic/1.1/xsd" />
            <xsd:complexType name="ClaimDetailType">
                <xsd:sequence>
                    <xsd:element name="Name" type="xsd:string"/>
                    <xsd:element name="ClaimForm" type="ref:swaRef"/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:schema>
    </wsdl:types>

    <wsdl:message name="ClaimIn">
        <wsdl:part name="ClaimDetail" type="types:ClaimDetailType"/>
        <wsdl:part name="ClaimPhoto" type="xsd:base64Binary"/>
    </wsdl:message>

    <wsdl:message name="ClaimOut">
        <wsdl:part name="ClaimRefNo" type="xsd:string"/>
    </wsdl:message>

    <wsdl:portType name="ClaimPortType">
        <wsdl:operation name="SendClaim">
            <wsdl:input message="tns:ClaimIn"/>
            <wsdl:output message="tns:ClaimOut"/>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="ClaimBinding" type="tns:ClaimPortType">
        <soapbind:binding style="rpc"
                          transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="SendClaim">
            <soapbind:operation soapAction="http://example.com/soapaction"/>
            <wsdl:input>
                <mime:multipartRelated>
                    <mime:part>
                        <soapbind:body use="literal"
                                       parts="ClaimDetail"
                                       namespace="http://example.com/mimetypes"/>
                    </mime:part>
                    <mime:part>
                        <mime:content part="ClaimPhoto"
                                      type="image/jpeg"/>
                    </mime:part>
                </mime:multipartRelated>
            </wsdl:input>
            <wsdl:output>
                <soapbind:body use="literal"
                               namespace="http://example.com/mimetypes"/>
            </wsdl:output>
        </wsdl:operation>
 </wsdl:binding>
</wsdl:definitions>

The service callout action is configured as follows:

• Request Parameter: claimDetail

• Response Parameter: claimRefNo

• Request Attachments Variable: reqatt

• Response Attachments Variable: respatt

See Adding Service Callout Actions in the Console and Adding Service Callout Actions in JDeveloperfor more information on adding and configuring the service callout action.

The following examples show the values of the message context variables when the service callout is invoked.

Example - Value of the Request Parameter (claimDetail)

<ClaimDetail xmlns=" http://example.com/mimetypes">
      <Name>...</Name>
      <ClaimForm>cid:[e-mail]</ClaimForm>
</ClaimDetail>

Example - Value of the Request Attachment Variable (reqatt)

<con:attachments xmlns:con="http://www.bea.com/wli/sb/context">
  <con:attachment>
    <con:Content-Type>text/xml</con:Content-Type>
    <con:Content-ID><[e-mail]></con:Content-ID>
    <con:body>
      <form>...XML contents of claim form referenced by the swaRef... </form>
    </con:body>
  </con:attachment>
  <con:attachment>
    <con:Content-Type>image/jpeg</con:Content-Type>
    <con:Content-ID><ClaimPhoto=[e-mail]></con:Content-ID>
    <con:body>
      <con:binary-content ref="cid:-6175a307:131072c66ef:-7f58"/>
    </con:body>
  </con:attachment>
</con:attachments>

The following example shows a sample outbound request.

Example - Sample Outbound Request

Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
        start="<[e-mail]>"

--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <[e-mail]>

<?xml version='1.0' ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body xmlns:types="http://example.com/mimetypes">
        <types:SendClaim>
            <ClaimDetail>
                <Name>...</Name>
                <ClaimForm>cid:[e-mail]</ClaimForm>
            </ClaimDetail>
        </types:SendClaim>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

--MIME_boundary
Content-Type: text/xml
Content-Transfer-Encoding: 8bit
Content-ID: <[e-mail]>

...claim form referenced by the swaRef...

--MIME_boundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <ClaimPhoto=[e-mail]>

...MIME attachment of binary photograph...
--MIME_boundary--

The following example shows a sample response.

Example - Sample Response

Content-Type: text/xml; charset=UTF-8

<?xml version='1.0' ?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body xmlns:types="http://example.com/mimetypes">
        <types:SendClaimResponse>
            <ClaimRefNo>.............................</ClaimRefNo>
        </types:SendClaimResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The message context variables (claimRefNo and respatt) corresponding to the response get set. The following example shows the value of the respatt variable.

Example - Value of the Response Attachments Variable (respatt)

<con:attachments xmlns:con=http://www.bea.com/wli/sb/context />

12.6.3 MTOM/XOP Support

You can use SOAP Message Transmission Optimization Mechanism (MTOM) with a service callout. MTOM uses XML-binary Optimized Packaging (XOP) to transfer the binary data.

However, you cannot mix MTOM and attachments. If the target service supports MTOM and there are attachments in the outbound request, then you get the following error:

"Mixing of XOP/MTOM and attachments is not allowed"

If the target service is MTOM-enabled, you should not configure any attachment variables.

12.6.4 Page Attachments to Disk

Service callouts support page attachments to disk. It is possible to use the contents of a previously paged attachment for the outbound request.

When the service callout is processing the outbound response, any business service configured to page attachments to disk is invoked accordingly.

12.7 Handling Errors as the Result of a Service Callout

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.

12.7.1 Transport Errors

When a transport error is received from an external service and there is no error response payload returned to Service Bus by the transport provider (for example, if an HTTP business service accepts response types other than XML or SOAP and therefore cannot receive HTTP response codes), the service callout action throws an exception, which in turn causes the pipeline to raise an error. The fault variable in a user-configured error handler is bound to a message formatted similarly to that shown in the following example.

Example - Contents of the fault Variable—Transport Error, no Error Response Payload

<con:fault xmlns:con="http://www.bea.com/wli/sb/context">
  <con:errorCode>OSB-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: OSB-382502.

The following conditions must be met for a OSB-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:

• (HTTP) The response code must be any code 300 or greater.

• (JMS) The response must have a property set to indicate that it is an error response—the transport metadata status code set to1 indicates an error.

• The content type must be text/xml, application/any_string+xml, or multipart/related.

• If the service is AnySoap or WSDL-based SOAP, then it must have a SOAP envelope. The body inside the SOAP envelope must be XML format; it cannot be text.

• If the service type is AnyXML, REST, or a messaging service of type text returns XML content with a non-successful response code (any code other than 200 or 202).

If the transport is HTTP, the ErrorResponseDetail element will also contain the HTTP error code returned with the response. The ErrorResponseDetail element in the fault contains error response payload received from the service. The following example shows an example of the ErrorResponseDetail element.

Example - Contents of the fault Variable—Transport Error, with Error Response Payload

<ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context">
    <ctx:errorCode>OSB-382502<ctx:errorCode>
    <ctx:reason> Service callout has received an error response from the server</ctx:reason>
    <ctx:details>
        <alsb:ErrorResponseDetail xmlns:alsb="http://www.oracle.com/...">
            <alsb:detail> <![CDATA[
. . .                 
]]>
            </alsb:detail>           <alsb:http-response-code>500</alsb:http-response-code>
        </alsb:ErrorResponseDetail>
    </ctx:details>
    <ctx:location>. . .</ctx:location>
</ctx:Fault>

Note:

The XML schema for the service callout-generated fault is shown in Unexpected Responses.

12.7.2 SOAP Faults

In case an external service returns a SOAP fault, the Service Bus runtime 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 a Service Bus fault element.

Take for example a scenario in which a service returns the following error.

Example - SOAP Fault Returned From Service Callout

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> 
  <SOAP-ENV:Body> 
    <SOAP-ENV:Fault> 
      <faultcode>SOAP-ENV:Client</faultcode>
      <faultstring>Application Error</faultstring>
      <detail>
        <message>That's an Error!</message>
        <errorcode>1006</errorcode>
      </detail>
    </SOAP-ENV:Fault> 
  </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

The <faultcode>, <faultstring>, and <detail> elements are extracted and wrapped in an <alsb:ReceivedFault> element. Note that the faultcode element in the example in Unexpected Responses contains a QName—any related namespace declarations are preserved. If the transport is HTTP, the ReceivedFault element will also contain the HTTP error code returned with the fault response.

The generated <alsb:ReceivedFault> element, along with the custom error code and the error string are used to construct the contents of the fault context variable, which in this example takes a format similar to that shown in the previous example.

Example - Contents of the Service Bus Fault Variable—SOAP Fault

<ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context">
    <ctx:errorCode>OSB-382500<ctx:errorCode>
    <ctx:reason> service callout received a soap Fault response</ctx:reason>
    <ctx:details>
        <alsb:ReceivedFault xmlns:alsb="http://www.oracle.com/...">
            <alsb:faultcode
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">SOAP-ENV:Client
            </alsb:faultcode>
            <alsb:faultstring>Application Error</alsb:faultstring> 
            <alsb:detail> 
                <message>That's an Error!</message> 
                <errorcode>1006</errorcode> 
            </alsb:detail> 
          <alsb:http-response-code>500</alsb:http-response-code>
        </alsb:ReceivedFault>
    </ctx:details>
    <ctx:location> </ctx:location>
</ctx:Fault>

Note:

The unique error code OSB-382500 is reserved for the case when service callout actions receive SOAP fault responses.

When chaining local proxy services, SOAP fault details are not propagated from one pipeline to the next in the $fault variable. To propagate SOAP faults from proxy service to proxy service, use an error handler with a Reply with Failure action, as described in Propagating SOAP Faults Between Proxy Services in the Developing Services with Oracle Service Bus.

12.7.3 Unexpected Responses

When a service returns a response message that is not what the proxy service runtime expects, a message context fault will be generated and initialized with the custom error code OSB-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 the following example.

Example - XML Schema for the Service Callout-Generated Fault Details

<xs:complexType name="ReceivedFaultDetail">
        <xs:sequence>
            <xs:element name="faultcode" type="xs:QName"/>
            <xs:element name="faultstring" type="xs:string"/>
            <xs:element name="detail" minOccurs="0" >
               <xs:complexType>
                 <xs:sequence>
                        <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax" /> 
                 </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax" /> 
               </xs:complexType>
            </xs:element>
            <xs:element name="http-response-code" type="xs:int" minOccurs="0"/>\
type="xs:int" minOccurs="0"/>
        </xs:sequence>
</xs:complexType>

<xs:complexType name="UnrecognizedResponseDetail">
        <xs:sequence>
            <xs:element name="detail" minOccurs="0" type="xs:string" />
        </xs:sequence>
</xs:complexType>

<xs:complexType name="ErrorResponseDetail">
        <xs:sequence>
            <xs:element name="detail" minOccurs="0" type="xs:string" />
        </xs:sequence>
</xs:complexType>

12.8 Handling Errors in Pipelines

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 pair request or response, or for an entire pipeline.

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. Table 12-9 summarizes the scope of the error handlers at various levels in the pipeline.

Table 12-9 Scope of Error Handlers

Level	Scope
Stage	Handles all the errors within a stage.
Pipeline	Handles all the errors in a pipeline, along with any unhandled errors from any stage in a pipeline.
Service	Handles all the errors in a pipeline, along with any unhandled errors in any pipeline pair requests or responses in a service. Note: All WS-Security errors are handled at this level.
System	Handles all the errors that are not handled anywhere else in a pipeline.

Note:

There are exceptions to the scope of error handlers. For example, an exception thrown by a non-XML transformation at the stage level is only caught by the service-level error handler. Suppose a transformation occurs that transforms XML to MFL for an outgoing proxy service response message, it always occurs in the binding layer. Therefore, for example, if a non-XML output is missing a mandatory field at the stage level, only a service-level error handler can catch this error.

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 a higher level in the pipeline.

In general, it is easier to handle specific errors at a stage level of the pipeline 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.

12.8.1 Generating the Error Message, Reporting, and Replying

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.

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 an 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 Oracle Service Bus Console to track the message to obtain an accurate picture of the message flow. This allows you to view the original reported message indicating the message was submitted for processing, and also the subsequent reported error indicating that the message was not processed correctly. To learn how to configure a report action and use the data reported at runtime, see Working with Pipeline Actions in Oracle Service Bus Console.

12.8.2 Different Behavior of Security Fault Handling in Service Bus 11g and 12c

Service Bus 12c handles security faults in the message flow differently than in Service Bus 11g.

In Service Bus 11g, any security errors raised as a result of failed OWSM policies or custom token message level authentication on inbound requests can be handled by a user-configured service error handler in the pipeline message flow. For example, on a service with username-token authentication policy, any authentication failures trigger a service-level error handler, if one is configured.

In Service Bus 12c, any security errors raised by security processing of inbound requests is not handled in the pipeline service-level error handler; rather, this results in a SOAP Fault automatically generated by the default inbound system error handler. These faults cannot be customized. It is not possible to route the failed request to the next component (for example, a pipeline or business service).

12.8.3 Example of Action Configuration in Error Handlers

This example shows how you can configure the report and reply actions in error handlers. The pipeline shown in Figure 12-1 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 Oracle Service Bus Console as shown in Figure 12-1.

Figure 12-1 Error Handler Pipeline

Description of "Figure 12-1 Error Handler Pipeline"

The stage is, in turn, configured with actions (replace, report, and reply) as shown in Figure 12-2.

Figure 12-2 Actions in Stage Error Handler

Description of "Figure 12-2 Actions in Stage Error Handler"

The actions control the behavior of the stage in the pipeline error handler as follows:

• Replace: The contents of a specified element of the body variable are replaced with the contents of the fault context variable. The body variable element is specified by an XPath expression. The contents are replaced with the value returned by an XQuery expression—in this case $fault/ctx:reason/text()

• Report: Messages from the reporting action are written to the Service Bus reporting data stream if the error handler configured with this action is invoked. The JMS Reporting Provider reports the messages on the Service Bus Dashboard in Fusion Middleware Control. Service Bus provides the capability to deliver message data to one or more reporting providers. Message data is captured from the body of the message and from any other variables associated with the message, such as header or inbound variables. You can use the message delivered to the reporting provider for functions such as tracking messages or regulatory auditing.

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

  To configure a report action and use the data reported at runtime, see Working with Pipeline Actions in Oracle Service Bus Console.

• Reply: At runtime, an immediate reply is sent to the invoker of the loanGateway3 proxy service (see Figure 12-2) indicating that the message had a fault The reply is With Failure.

12.9 Using Dynamic Routing

When you do not know the service you need to invoke from the pipeline you are creating, you can use dynamic routing. For any given pipeline, you can use one of the following techniques to dynamically route messages:

• In a message flow pipeline, design an XQuery expression to dynamically set the fully qualified service name in Service Bus and use the dynamic route or dynamic publish actions.

  Note:

  Dynamic Routing can be achieved in a route node, whereas dynamic publishing can be achieved in a stage in a request pipeline or a response pipeline.

  With this technique, the pipeline dynamically uses the service account of the endpoint business service to send user names and passwords in its outbound requests. For example, if a pipeline is routing a request to Business Service A, then the invoking proxy service uses the service account from Business Service A to send user names and passwords in its outbound request. See Implementing Dynamic Routing.

• Configure a pipeline to route or publish messages to a business service. Then, in the request actions section for the route action or publish action, add a Routing Options action that dynamically specifies the URI of a service.

  With this technique, to send user names and passwords in its outbound requests, the proxy service uses the service account of the statically defined business service, regardless of the URI to which the request is actually sent.

  For information on how to use this technique, see Implementing Dynamic Routing.

  Note:

  This technique is used when the overview of the interface is fixed. The overview of the interface includes message types, port types, and binding, and excludes the concrete interface. The concrete interface is the transport URL at which the service is located.

For a working example of dynamic service invocation, see the Service Bus samples at http://www.oracle.com/technetwork/middleware/service-bus/learnmore/index.html.

12.9.1 Implementing Dynamic Routing

You can use dynamic routing to determine the destination during the runtime of a pipeline. To achieve this you can use a routing table in an XML file to create an XQuery resource.

Note:

Instead of using the XQuery resource, you can also directly use the XML file from which the resource is created.

An XML file or the XQuery resource can be maintained easily. At runtime you provide the entry in the routing table that will determine the routing or publishing destination of the pipeline.The XML file or the XQuery resource contains a routing table, which maps a logical identifier (such as the name of a company) to the physical identifier (the fully qualified name of the service in Service Bus). The logical identifier, which is extracted from the message, maps on to the physical identifier, which is the name of the service you want to invoke.

Note:

To use the dynamic route action, you need the fully qualified name of the service in Service Bus.

In a pipeline the logical identifier is obtained with an XPath into the message.You assign the XML table in the XQuery resource to a variable. You implement a query against the variable in the routing table to extract the physical identifier based on the corresponding logical identifier. Using this variable you will be able to invoke the required service. The following sections describe how to implement dynamic routing.

• Sample XML File

• Creating an XQuery Resource From the Sample XML

• Creating and Configuring the Pipeline to Implement Dynamic Routing

• Guidelines for Implementing Identity-Based Routing

12.9.1.1 Sample XML File

You can create an XQuery resource from the following XML file. Save this as sampleXquery.xml.

Example - Sample XML File

<routing>
   <row>
      <logical>Oracle</logical>
      <physical>default/goldservice</physical>
   </row>
   <row>
      <logical>ABC Corp</logical>
      <physical>default/silverservice</physical>
   </row>
</routing>

12.9.1.2 Creating an XQuery Resource From the Sample XML

To create an XQuery resource from the sample XML in the Oracle Service Bus Console:

1. If you have not already done so, click Create to create a new session or click Edit to enter an existing session.
2. From the top right of the Oracle Service Bus Console window, click the Designer tab. The Project Navigator appears.
3. Expand the All Projects node by clicking the Expand (arrow) icon before it.
4. Right-click the project name to which you wish to add the XQuery resource.
5. From the context menu, click Create, and then click Resource.
6. From the Resource Gallery, click Transformations, and then click XQuery. The Create XQuery dialog appears.
7. In the Resource Name field, enter the name of the resource. This is a mandatory.
8. In the Resource Description field, provide the a description for the resource. This is optional.
9. Click Choose File to select the XML file you are using as the XQuery resource.
10. Click Create to create the XQuery resource.
11. Activate the session.

12.9.1.3 Creating and Configuring the Pipeline to Implement Dynamic Routing

To implement dynamic routing with a pipeline:

1. In the Project Navigator, select the project to which you want to add a pipeline, and then click the down arrow next to the Create icon.
2. Select Pipeline from the list of options.

   The Create Pipeline dialog appears.

3. In the Pipeline Name field of the General section, enter the name of the pipeline. This is mandatory. Optionally, specify a Description for the pipeline.
4. Select the Service Type for the pipeline. For more information on selecting the service type, see Service Types and Protocols for Proxy Services.
5. Select Expose as Proxy Service to create a proxy service corresponding to the pipeline message flow. Specify the name and other details for the proxy service to be created.
6. Click Create to create the pipeline resource. The pipeline is created and opened up for editing.
7. Click the Open Message Flow icon near the top right corner of the window. The Edit Message Flow page appears. The message flow initially consists of a single icon.
8. Click the start node (pipeline icon), and select Add Pipeline Pair to add a pipeline pair to the message flow.
9. Click Request Pipeline icon select Add Stage from the menu.
10. Click the Stage1 icon to and select Edit Stage from the menu. The Edit Stage Configuration page appears.
11. Click Add Action icon. Choose Add an Action item from the menu.
12. Choose the Assign action from Message Processing.
13. Click Expression. The XQuery Expression Editor is displayed.
14. Click XQuery Resources. The browser displays the page where you can import the XQuery resource. Click the Browse to locate the XQuery resource.
15. Click Validate to validate the imported XQuery resource.
16. Save the imported XQuery resource on successful validation.
17. On the Edit Stage Configuration page, enter the name of the variable in the field.

    This assigns the XQuery resource to this variable. The variable now contains the externalized routing table.

18. Add another Assign action.
19. Enter the following XQuery:

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

20. Click Validate to validate the XQuery.
21. Save the XQuery on successful validation.
22. On the Edit Stage Configuration page, enter the name of the variable (for example, routeresult) in the field.

    This extracts the XML used by the dynamic route action into this variable.

23. Click the pipeline icon to add a route node to the end of the pipeline.
24. Click the Route Node icon and select Edit from the menu.
25. Click the Add Action icon. Choose Add an Action item from the menu.
26. Choose the Dynamic Route action.
27. Click Expression. The XQuery Expression Editor is displayed.
28. Enter the variable; for example, $routeresult.

12.9.1.4 Guidelines for Implementing Identity-Based Routing

If you want to dynamically route message based on the identity of an authenticated user, Service Bus stores information such as user name, group membership (/principals/group), and the name of the subject (/subject-properties/property/name in the following inbound context variables:

• $inbound/ctx:security/ctx:transportClient/*

• $inbound/ctx:security/ctx:messageLevelClient/*

For more information on these context variables, see Table A-6.

Using the guidance provided in Using Dynamic Routing, use XQuery or simple XML to map authenticated user identity characteristics to different endpoints using the desired mapping technique.

The following predefined Service Bus XQuery functions are also available to perform security checks in identity-based routing:

• fn-bea:lookupBasicCredentials

• fn-bea:isUserInGroup

• fn-bea:isUserInRole

For a working example of dynamic service invocation, see the Service Bus samples at http://www.oracle.com/technetwork/middleware/service-bus/learnmore/index.html.

12.10 Accessing Databases Using XQuery

Service Bus provides read-access to databases from pipelines without requiring you to write a custom EJB or custom Java code and without the need for a separate database product like Oracle Data Service Integrator. 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 pipeline. Take for example a scenario in which a Service Bus pipeline receives "request for quote" messages. The pipeline 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 pipeline 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 a Service Bus pipeline.

The following databases and JDBC drivers are supported using the execute-sql() function:

• The sample database provided by WebLogic Server.

  IBM DB2/NT 8

• Microsoft SQL Server 2000, 2005

• Oracle9i, Oracle Database 10g, Oracle Database 11g, Oracle Database 12c

• Sybase 12.5.2 and 12.5.3

• WebLogic Type 4 JDBC drivers

• Third-party drivers supported by WebLogic Server

Use non-XA drivers for datasources you use with the fn-bea:execute-sql() function—the function supports read-only access to the datasources.

Caution:

In addition to specifying a non-XA JDBC driver class to use to connect to the database, you must ensure that you disable global transactions and two-phase commit. (Global transactions are enabled by default in the Oracle WebLogic Server Administration Console for JDBC data sources.) These specifications can be made for your data source using the Oracle WebLogic Server Administration Console. See "Create JDBC Data Sources" in the Oracle WebLogic Server Administration Console Online Help.

For complete information about database and JDBC drivers support in Service Bus, see Oracle Fusion Middleware Supported System Configurations at:

http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html

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 pipeline, 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 pipeline. For information about using the inline XQuery editor, see Creating Variable Structure Mappings.

12.11 Understanding Message Context

The message context is a set of variables that hold message context and information about messages as they are routed through Service Bus. Together, the header, body, and attachments variables, (referenced as $header, $body and $attachments in XQuery statements) represent the message as it flows through 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 Service Bus message context.

Table 12-10 describes the Service Bus message context variables.

Table 12-10 Predefined Context Variables in Service Bus

Context Variable	Description	See Also
header	For SOAP messages, $header contains the SOAP header. If the pipeline is SOAP 1.2, $header contains a SOAP 1.2 Header element. For message types other than SOAP, $header contains an empty SOAP header element.	Message-Related Variables
body	This varies depending on the message type, as described below: SOAP messages: The <SOAP:Body> part extracted from the SOAP envelope. If the pipeline is SOAP 1.2, the $body variable contains a SOAP 1.2 Body element. Non-SOAP, non-binary messages: The entire message content wrapped in a <SOAP:Body> element. Binary messages: A <SOAP:Body> wrapped reference to an in-memory copy of the binary message. Java objects: A <SOAP:Body> wrapped reference to an in-memory copy of the Java object.	Message-Related Variables
attachments	The MIME attachments for a given message.	Message-Related Variables
inbound	The inbound transport headers along with information about the proxy service that received a message.	Inbound and Outbound Variables
outbound	The outbound transport headers along with information about the target service to which a message is to be sent.	Inbound and Outbound Variables
operation	The operation being invoked on a pipeline.	Operation Variable
fault	Information about errors that have occurred during the processing of a message.	Fault Variable
messageId	The transport provider-specific message identifier. This ID should uniquely identify the message among other messages going through the Service Bus runtime, but it is not required that this value be unique.	messageID Variable

12.11.1 Message Context Components

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 pipeline. 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 pipeline, the message contents are used to initialize the header, body, and attachments variables. For SOAP services, the Header and Body elements are taken directly from the envelope of the received SOAP message and assigned to $header and $body respectively. For non-SOAP services, the entire content of the message is typically wrapped in a Body element (qualified by the SOAP 1.1 namespace) and assigned to $body, and an empty Header element (qualified by the SOAP 1.1 namespace) is assigned to $header.

Binary and MFL messages are initialized differently. For MFL messages, the equivalent XML document is inserted into the Body element that is assigned to $body. For binary messages, the message data is stored internally and a piece of reference XML is inserted into the Body element that is assigned to $body. The reference XML looks like <binary-content ref="..."/>, where "..." contains a unique identifier assigned by the pipeline.

The message context is defined by an XML schema. You must use XQuery expressions to manipulate the context variables in the pipeline. The predefined context variables provided by Service Bus can be grouped into the following types:

• Message-related variables

• Inbound and outbound variables

• Operation variable

• Fault variable

For information about the predefined context variables, see Predefined Context Variables.

The $body contains message payload variable. When a message is dispatched from Service Bus you can decide the variables, whose you want to include in the outgoing message. That determination is dependent upon whether the target endpoint is expecting a SOAP or a non-SOAP message:

• For a binary, any text or XML message content inside the Body element in $body is sent.

• For MFL messages, the Body element in $body contains the XML equivalent of the MFL document.

• For text messages, the Body element in $body contains the text. For text attachments, the body element in $attachments contains the text. If the contents are XML instead of simple text, the XML is sent as a text message.

• For XML messages, the Body element in $body contains the XML. For XML attachments, the body element in $attachments contains the XML.

• SOAP messages are constructed by wrapping the contents of the header and body variables inside a <soap:Envelope> element. (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 Oracle XQuery Mapper, you need to reference MessageContext.xsd, which is available in a JAR file, OSB_ORACLE_HOME/lib/sb-schemas.jar, and the transport-specific schemas, which are available at

OSB_ORACLE_HOME/lib/transports/

To learn about the message context schema and the transport specific schemas, see Message Context Schema.

12.11.2 Guidelines for Viewing and Altering Message Context

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

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

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

  To obtain the second attachment

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

• A context variable can be empty or it can contain a single XML element or a string value. However, an XQuery expression often returns a sequence. When you use an XQuery expression to assign a value to a variable, only the first element in the sequence returned by the expression is stored as the variable value. For example, if you want to assign the value of a WS-Addressing Message ID from a SOAP header (assuming there is one in the header) to a variable named idvar, the assign action specification is:

  assign data($header/wsa:messageID to variable idvar 
  

  Note:

  In this case, if two WS-Addressing MessageID headers exist, the idvar variable will be assigned the value of the first one.

• The variables $header, $body, and $attachments are never empty. However, $header can contain an empty SOAP Header element, $body can contain an empty SOAP Body element, and $attachments can contain an empty attachment element.

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

  $body/* [1]
  

  The result of the transformation can be put back in $body with a replace action. That is replace the content of $body, which is the content of the Body element. For more information, see Transforming Data with XQuery and Transforming Data with XSLT.

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

12.11.3 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, Service Bus does not propagate any information (such as the transport headers and JMS properties) from the inbound variable to the outbound variable.

The transport headers for the proxy service's request and response messages are in $inbound and the transport headers for the invoked business service's request and response are in $outbound.

For example, the following XQuery expression can be used in a case where the user-defined JMS properties for a one-way message (an invocation with no response) need to be copied from inbound message to outbound message:

Use the transport headers action to set

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

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 Adding Transport Header Actions in the Console.

12.12 Working with Variable Structures

This section includes the following topics:

• Using the Inline XQuery Expression Editor

• Using Variable Structures

You can find examples at Creating Variable Structure Mappings.

12.12.1 Using the Inline XQuery Expression Editor

Service Bus allows you to import XQueries that have been created with an external tool such as the Oracle XQuery Mapper. You can use these XQueries anywhere in the pipeline by binding the XQuery resource input to an Inline XQuery, and binding the XQuery resource output to an action that uses the result as the input; for example, the assign, replace, or insert actions.

However, you can enter the XQuery inline as part of the action definition instead of entering the XQuery as a resource. You can also use Inline XQueries for the condition in an If...Then... action.

Use the Inline XQuery Expression Editor to enter simple XQueries that consist of the following:

• Fragments of XML with embedded XQueries.

• Simple variable paths along the child axis.

  Note:

  For more complex XQueries, it is recommended that you use the XQuery Mapper, especially if you are not familiar with XQuery.

Inline XQueries can be used effectively to:

• Create variable structures by using the Inline XQuery Expression Editor. See Using Variable Structures.

• Extract or access a business document or RPC parameter from the SOAP envelope elements in $header or $body.

• Extract or access an attachment document in $attachments.

• Set up the parameters of a service callout action by extracting it from the SOAP envelope.

• Insert the result parameter of a service callout action into the SOAP envelope.

• Extract a sequence from the SOAP envelope to drive a for loop.

• Update an item in the sequence in a for loop with an Update action.

  Note:

  You can also use the Inline XQuery Expression Editor to create variable structures. For more information, see Using Variable Structures.

12.12.1.1 Inline XQueries

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-based 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 Oracle functions and operators, see Service Bus XQuery Functions.

12.12.1.2 Uses of the Inline XQuery Expression Editor

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

• Fragments of XML with embedded XQueries.

• Simple variable paths along the child axis.

  Note:

  For more complex XQueries, we recommend that you use the Oracle XQuery Mapper, an editor with drag-and-drop functionality. See "Creating Transformations with the XQuery Mapper" in the Developing SOA Applications with Oracle SOA Suite.

Examples of good uses of inline XQueries are:

• Extract or access a business document or RPC parameter from the SOAP envelope elements in $header or $body.

• Extract or access an attachment document in $attachments.

• Set up the parameters of a service callout by extracting it from the SOAP envelope.

• Fold the result parameter of a service callout into the SOAP envelope.

• Extract a sequence from the SOAP envelope to drive a for loop.

• Update an item in the sequence in a for loop with an Update action.

You can also use the Inline XQuery Expression Editor to create variable structures. For more information, see Using Variable Structures.

12.12.1.2.1 Best Practices for Type-Dependent Expressions

To help ensure expected results when using type-dependent expressions, manually cast values to the desired types. For example, the following statement casts counter as an integer for the XQuery compiler, which ensures a single return value:

<Body><result>{$foo/item[xs:int($counter)]}</result></Body>

12.12.2 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 Administration Console rather than viewing the XML schema of the XPath variable. For examples of using variable structures in the Oracle Service Bus Console, see Creating Variable Structure Mappings.

Note:

It is not necessary to create variable structures for your runtime to work. Variable structures define the structure of the variable or the variable path but do not create the variable. Variables are created at runtime as the target of the assign action in the stage.

In a typical programming language, the scope of variables is static. Their names and types are explicitly declared. The variable can be accessed anywhere within the static scope.

In Service Bus, there are some predefined variables, but you can also dynamically create variables and assign value to them using the assign action or using the loop variable in the for-loop. When a value is assigned to a variable, the variable can be accessed anywhere in the pipeline. The variable type is not declared but the type is essentially the underlying type of the value it contains at any point in time.

Note:

The scope of the for-loop variable is limited and cannot be accessed outside the stage.

When you use the Inline XQuery Expression Editor, the XQuery has zero or more inputs and one output. Because you can display the structure of the inputs and the structure of the output visually in the Expression Editor itself, you do not need to open the XML schema or WSDL resources to see their structure when you create the Inline XQuery. The graphical structure display also enables you to drag and drop simple variable paths along the child axis without predicates, into the composed XQuery.

Each variable structure mapping entry has a label and maps a variable or variable path to one or more structures. The scope of these mappings is the stage or route node. Because variables are not statically typed, a variable can have different structures at different points (or at the same point) in the stage or route node. Therefore, you can map a variable or a variable path to multiple structures, each with a different label. To view the structure, select the corresponding label with a list.

Note:

You can also create variable structure mappings in the Inline XPath Expression Editor. However, although the variable or a variable path is mapped to a structure, the XPaths generated when you select from the structure are XPaths relative to the variable. An example of a relative XPath is ./ctx:attachment/ctx:body.

12.13 Quality of Service

The following sections discuss quality of service features in Service Bus messaging:

• Delivery Guarantees

• Outbound Message Retries

12.13.1 Delivery Guarantees

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 service is configured to be transactional; 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 Service Bus, shown in Table 12-11.

Table 12-11 Delivery Guarantee Types

Delivery Reliability	Description
Exactly-once	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 means reliability is optimized. Exactly-once delivery reliability is a hint, not a directive. When exactly-once is specified, exactly-once reliability is provided if possible. If exactly-once is not possible, then at-least-once delivery semantics are attempted; if that is not possible, best-effort delivery is performed. Proxy services configured to be transactional have exactly-once quality of service. The default value of the qualityOfService element is also exactly-once for a route node action for the following inbound transports: email FTP SFTP File JMS (transactional) Tuxedo (transactional) MQ (with Backout Threshold set to zero) WS Note: Do not retry the outbound transport when the QoS is exactly-once
At-least-once	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. Delivery is considered satisfied even if the target service responds with a transport-level error. However it is not satisfied in the case of a time-out, a failure to connect, or a broken communication link. If failover URLs are specified, at-least-once semantics is provided with respect to at least one of the URLs. At-least-once delivery semantics is attempted if exactly-once is not possible but the qualityOfService element is exactly-once.
Best-effort	Best-effort means that there is no reliable messaging and there is no elimination of duplicate messages—however, performance is optimized. It is performed if the qualityOfService element is best-effort. Best-effort delivery is also performed if exactly-once and at-least-once delivery semantics are not possible but the qualityOfService element is exactly-once. The default value of the qualityOfService element for a route node is best-effort for the following inbound transports: HTTP JMS (non-transactional) Tuxedo (non-transactional) MQ (with Backout Threshold set to greater than zero) The default value of the qualityOfService element is always best-effort for the following: Service callout action – always best-effort, but can be changed if required. Publish action – defaults to best-effort, modifiable For more information on QoS behavior in publish actions, see Transformations and Publish Actions. Note: When the value of the qualityOfService element is best-effort for a publish action, all errors are ignored. However, when the value of the qualityOfService element is best-effort for a route node action or a Service Callout action, any error will raise an exception.

For more detailed information about quality of service for other transports, see "Transports" in the Developing Services with Oracle Service Bus.

12.13.1.1 Overriding the Default Element Attribute

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 pipeline actions:

• Publish

• Dynamic Publish

• Publish Table

• Service Callout

• Routing

• Dynamic Routing

• Routing Table

To override the qualityOfService element attribute, add a Routing Options action to any of the above actions, select the QoS option, and choose the override value.

12.13.1.2 Delivery Guarantee Rules

The delivery guarantee supported when a pipeline publishes a message or routes a request to a business service depends on the following conditions:

• The value of the qualityOfService element.

• The inbound transport (and connection factory, if applicable).

• The outbound transport (and connection factory, if applicable).

However, if the inbound proxy service is 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 Creating and Configuring Proxy Services and Creating and Configuring Business Services.

Note:

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

The following rules govern delivery guarantees, shown in Table 12-12.

Table 12-12 Delivery Guarantee Rules

Delivery Guarantee Provided	Rule
Exactly-once	The proxy service inbound transport is transactional and the value of the qualityOfService element is exactly-once to an outbound transport.
At-least-once	The proxy service inbound transport is file, FTP, or email and the value of the qualityOfService element is exactly-once.
At-least-once	The proxy service inbound transport is transactional and the value of the qualityOfService element, where applicable, is exactly-once to an outbound transport that is not transactional.
No delivery guarantee	All other cases, including all response processing cases.

Note:

To support at-least-once and exactly-once delivery guarantees with JMS, you must exploit JMS transactions and configure a retry count and retry interval on the JMS queue to ensure that the message is redelivered in the event of a server crash or a failure that is not handled in an error handler with a Reply or Resume action. File, FTP, and email transports also internally use a JMS/XA queue. The default retry count for a proxy service with a JMS/XA transport is 1.

The following are additional delivery guarantee rules:

• If the transport of the inbound proxy service propagates or starts a transaction, the request processing is performed in a transaction.

  • When the qualityOfService element is set to exactly-once, any route node actions executed in the request flow to a transactional destination are performed in the same transaction. Publish and Service Callout actions in a transaction context are best-effort by default and therefore execute outside of the transaction context. Setting those actions to exactly-once causes them to execute in the transaction context.

  • When the qualityOfService element is set to best-effort for any action in a route node, service callout or publish actions are executed outside of the request flow transaction. Specifically, for JMS, Tuxedo, Transactional Tuxedo, or EJB transport, the request flow transaction is suspended and the Transactional Tuxedo work is done without a transaction or in a separate transaction that is immediately committed.

  • If an error occurs during request processing, but is caught by a user error handler that manages the error (by using the resume or reply action), the message is considered successfully processed and the transaction commits. A transaction is aborted if the system error handler receives the error—that is, if the error is not handled before reaching the system level. The transaction is also aborted if a server failure occurs during request pipeline processing.

• If a response is received by a proxy service that uses a JMS/XA transport to business service (and the proxy inbound is not Transactional Tuxedo), the response processing is performed in a single transaction.

  • When the qualityOfService element is set to exactly-once, all route, service callout, and publish actions are performed in the same transaction.

  • When the qualityOfService element is set to best-effort, all publish actions and service callout actions are executed outside of the response flow transaction. Specifically, for JMS, 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.

  • Proxy service responses executed in the response flow to a JMS/XA destination are always performed in the same transaction, regardless of the qualityOfService element setting.

• If the proxy service inbound transport is transactional Tuxedo, or if you set the "Same Transaction for Response" option on a proxy service, both the request processing and response processing are done in this transaction.

  Note:

  You will encounter a runtime error when the inbound transport is transactional Tuxedo and the outbound is an asynchronous transport, for example, JMS/XA.

12.13.1.3 Threading Model

The Service Bus threading model works as follows:

• Proxy service request and response pipelines always execute in separate threads.

• When invoking an external service, threads may be blocking or non-blocking depending on the pipeline action, the Quality of Service option and the transport used.

  Service callouts are always blocking. An HTTP route or publish action is non-blocking (for request/response or one-way invocation), if the value of the qualityOfService element is best-effort.

  JMS route actions or publish actions are always non-blocking, but the response is lost if the server restarts after the request is sent because Service Bus has no persistent message processing state.

  Note:

  In a request or response flow publish action, responses are always discarded because publish actions are inherently a one-way message send.

• When using blocking calls, a work manager having a Min Thread constraint must be associated with the response to prevent server deadlock. A Min Thread constraint guarantees a minimum number of threads for processing.

  For general information about Work Managers, see "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server. For information about Work Managers and threading in Service Bus, see Work Managers and Threading.

12.13.1.4 Splitting Proxy Services

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

• When HTTP is the inbound and outbound transport for a proxy service, you may want to incorporate enhanced reliability into the middle of the pipeline. To enable enhanced reliability in this way, split the proxy service into a front-end HTTP proxy service and a back-end JMS (one-way or request/response) proxy service with an HTTP outbound transport. In the event of a failure, the first proxy service must quickly place the message in the queue for the second proxy service, in order to avoid loss of messages.

• To disable the direct invocation optimization for a non-JMS transport when a proxy service, say loanGateway1 invokes another proxy service, say loanGateway2. Route to the proxy service loanGateway2 from the proxy service loanGateway1 where the proxy service loanGateway2 uses JMS transport.

• To have an HTTP proxy service publish to a JMS queue but have the publish action rollback if there is a exception later on in the request processing, split the proxy service into a front-end HTTP proxy service and a back-end JMS proxy service. The publish action specifies a qualityOfService element of exactly-once and uses an XA connection factory.

12.13.2 Outbound Message Retries

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.

Note:

For HTTP transports, any HTTP status other than 200 or 202 is considered an error by Service Bus and must be retried. Because of this algorithm, it is possible that 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 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.

For quality of service=exactly-once, failover or retries will not be executed.

12.14 Using the JavaScript Action and JavaScript Expressions

Service Bus provides a JavaScript action, which is used in pipelines The JavaScript action allows you to include snippets of JavaScript code to be executed during pipeline processing.

The most common case for using JavaScript is when dealing with JSON objects in REST services. Rather than converting the payload to XML and using XQuery or XSLT for manipulation, using JavaScript allows you to manipulate the JSON object directly. The JavaScript engine used in Service Bus also allows you to easily reference XML elements, making it easier to handle both JSON and XML-style payloads in JavaScript.

JavaScript is not limited to REST services; you can use JavaScript in any service. You can also use JavaScript in other areas where an expression is created for evaluation.

Tip:

The JavaScript action is available for any pipeline type, not just Native REST pipelines.

Rhino, an open-source implementation of JavaScript written entirely in Java, is the JavaScript engine used by Service Bus. See https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino

In order to facilitate JavaScript retrieving variable bindings from the message context and updating the message context with new variable bindings, Service Bus uses a JavaScript engine construct that you use to read/update variable values. Before invoking a script, Service Bus binds a globally-scoped object called process, which you use to read and update variable values. You invoke variables in expressions using dot (.) notation, like process.body or process.xyz.

The expression process.varName returns one of the following:

• When the variable is JSON, the expression returns a JSON scriptable object

• When the variable is XML, the expression returns an XML or XMLList object in E4X (JavaScript XML) format

• String

• Boolean

For example, an incoming request payload like the following:

{
     "employees": [
           { "firstName":"John" , "lastName":"Doe" },
            { "firstName":"Anna" , "lastName":"Smith" },
            { "firstName":"Peter" , "lastName":"Jones" }
      ]
}

Is parsed into a JSON-specific POJO model expected by the JavaScript engine, bound as a $body variable. Using an expressions in a script like the following:

var $body  = process.body;
var name = $body.employees[0].firstName + ” “ + $body.employees[0].lastName

Contains the string John Doe.

If the variable $foo is bound to the following XML:

 <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22­rdf­syntax­ns#" xmlns="http://purl.org/rss/1.0/">
    <rdf:item value="5"/>
    <rdf:textNode>Hello World</rdf:textNode>
    <item value="10"/>
    <rdf:item>17</rdf:item>
</rdf:RDF>

and the prefixes rdf and rss are defined in the execution scopes, either mapped from the stage context or explicitly declared in JavaScript snippets in the following manner:

var rdf = new Namespace("http://www.w3.org/1999/02/22-rdf-syntax-ns#");
var rss = new Namespace("http://purl.org/rss/1.0/");

Then the JavaScript expressions in the following example are possible:

process.foo.rdf::item.@value  =>  5
process.foo.rdf::textNode.text() => “Hello World”
process.foo.rss::item.@value => 10
process.foo.rdf::item[1].text() => 17

The following E4X expression returns the value of the inbound HTTP Content-Type header:

process.inbound.ctx::transport.ctx::request.tp::headers.http::[“Content-Type”].text()

Note:

The brackets around Content-Type in the example above are present because of the hyphen in the XML element name. While hyphens are valid in XML elements, they are not allowed in JavaScript identifier names. Some other headers, such as SOAPAction, do not need brackets. For instance, http::SOAPAction is valid. For the same reason, known namespace prefixes with hyphens, such as fn-bea or soap-env, are bound into the engine with underscores instead, such asfn_bea::bar.fn_bea::zot.text().

Service Bus automatically declares the identifiers in the example above (ctx, tp, and http) to their corresponding namespace URIs, much like it does for XQuery and XPath expressions.

As an example, the following E4X expression sets the inbound HTTP response code value:

process.inbound.ctx::transport.ctx::response.http::["http-response-code"] = 202;

12.14.1 JavaScript Action and Message Context Variables

You can consume and update Service Bus message context variables with the JavaScript action.

The JavaScript action can consume the following types of message context variables:

• XML

• XMLList (for instance, the contents of $body with multiple root elements in a SOAP Doc Literal style)

• String

• Boolean

• JSON

  Note:

  JavaScript expressions should use the language feature JSON.parse() to parse text into JSON POJOs.

The JavaScript action can update the following types of message context variables:

• XML

• XMLList

• String

• Boolean

• JSON

12.14.2 Update Context Variables Using JavaScript Expressions

You can use the JavaScript action to update Service Bus message context variables.

To update $body contents to JSON objects, use one of the following expressions:

• process.body = JSON.parse(‘{“example1” : “example2”});

• process.body = { “example1” : “example2” };

Note:

You can create JSON-typed variables in the pipeline using only the following methods:

• Sending a JSON payload to a Native-REST typed service (in $body)

• Assigning a JSON object to a variable using the JavaScript action

To update $body contents to XML, use an expression like process.body = <example />;.

To update $body contents to text, use an expression like process.body = “example”;.

To update $body contents to an XML list containing elements like <example1/> and <example2/>, use an expression like process.body = <> <example1/><example2/> </>;.

12.14.3 Creating Variables Using JavaScript Expressions

You can create variables using JavaScript expressions in the JavaScript action.

To create a variable in the Service Bus message context, use an expression like the following:

process.newVar = …;

12.14.4 Deleting Variables Using JavaScript Expressions

You can use JavaScript expressions to delete message context variables.

To delete a variable, use the JavaScript delete operator:

delete process.var;

For example, you can delete a JSON element by using the following expression:

delete process.jsonvar2.foo;

You can delete an XML element or attribute from a structure by using the following expression:

delete process.xmlvar2.(@number='1234').name.first;

12.14.5 About XQuery, XPath, and JSON Variables

JSON variables are bound into the XQuery engine with their string representations.

The following example shows a JSON variable bound to the XQuery engine:

process.foo = { "foo" : "bar" }

When you specify $foo as an input argument to an XQuery resource, the XQuery engine receives the value "{ "foo" : "bar" }".

Note:

Executing XPath expressions with respect to JSON variables is not supported. Doing so results in a runtime error.

12.14.6 Streaming $body Variables and the JavaScript Action

Reading and writing streaming $body content using the JavaScript action is not recommended.

Instead, you should use a pipeline action that uses the streaming XQuery engine to read or manipulate the XML payload, such as the Assign or Replace actions.

However, if you do decide to query streaming $body content using the JavaScript action, the contents of $body are fully materialized and bound to the engine with the E4X façade.

12.14.7 JavaScript Action and Custom Java Functions

Previous versions of Service Bus support the registration of custom Java functions and invocation of these custom functions from XQuery and XPath expressions. This version of Service Bus supports invoking these same functions from JavaScript expressions.

The following example shows a custom Java function being invoked from a JavaScript expression.

isAdmin = IsUserInRoleFunction.isUserInRole($body.users[0].userName, "Admin");

The Service Bus runtime has been enhanced to automatically import the packages of all registered custom functions. You do not have to use importPackage() constructs in your expressions to use these functions. Additionally, JavaScript expressions are executed in the context of a classloader that contains the classes from the custom java function jars from the Service Bus configuration directories.

12.14.8 Logging and Reporting the Result of JavaScript Expressions

Logging and Reporting the result of a JavaScript expression is supported.

You can log the result of expressions similar to those shown in the following example:

process.myJsonVar.Orders.items[0].name
   or
process.xmlvar2.(@number='1234').name.first
   or
process.myJsonVar.Orders.items[0].name.length() > 56

12.15 Using Work Managers with Service Bus

WebLogic Server helps you optimize the performance of your applications and web services environment as well as maintain service-level agreements with a feature called Work Managers. You create Work Manager resources and configure them by defining work execution rules. WebLogic Server uses the rules in a Work Manager to help prioritize work and allocate threads in whatever application or component the Work Manager is placed.

For general information about Work Managers, see "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server. For information about Work Managers and threading in Service Bus, see Work Managers and Threading.

In Service Bus, several transports for proxy and business services provide a configuration option called "Dispatch Policy" that lets you associate a Work Manager with a service to prioritize service work. This section describes how proxy and business services use Work Managers.

By configuring the Dispatch Policy of a Service Bus proxy service, the startup and execution of its request pipeline are governed by the rules of the Work Manager. For example, given a proxy service using a Dispatch Policy with a Max Constraint of 5, the proxy service will have no more than 5 request pipeline tasks executing simultaneously.

While the request pipeline is governed by the proxy service's Dispatch Policy, the response pipeline is governed by the business service or Split-Join Dispatch Policy. The RouteTo action specifies a business service or Split-Join to route the message to, and the response is subject to any Dispatch Policy on that business service or Split-Join.

When a RouteTo action specifies a local proxy service, the Dispatch Policy of the original proxy applies to work done in the local proxy's request pipeline. When the local proxy or chain of local proxies reaches a RouteTo action that invokes a business service or Split-Join, the business service, Split-Join, and all the following response pipelines are governed by the Dispatch Policy of that business service or Split-Join.

If an error occurs in the request, the error response is handled in the same thread as the request pipeline.

The quality of service (QoS) specified in the outbound metadata can also impact the way requests are threaded and thus impact what you see when monitoring Work Managers. The QoS on the RouteTo action defaults to the inbound QoS. For example, some inbound transactional transports set QoS to "exactly-once," such as JMS/XA, SB, Tuxedo, and WS (WS-RM). Other inbound transports, such as HTTP, set QoS to “best-effort" by default. The QoS on the RouteTo action is inherited from the inbound unless overridden by user settings in the RouteTo action.

When “best-effort" is used, the Route node invokes the business service asynchronously. In the case of “best-effort," the work thread returns to the pool and does not wait for the response; therefore, there is not a thread counting against a Work Manager constraint even though there is pending work due back asynchronously. But if “exactly-once" is selected, the request thread sends the request, blocks waiting for the response, and counts against the Work Manager constraints. In the case of “exactly-once," the waiting thread applies to the Work Manager assigned to the proxy service. Once a positive response arrives, a new thread processes the response pipeline using the Dispatch Policy assigned to the business service or Split-Join.

While using “exactly-once" is more expensive from performance, memory, and threading standpoints, “exactly-once" is necessary to maintain integrity on transactional inbound and outbound resources.

For more information on QoS, see Quality of Service.

12.16 Content Types, JMS Type, and Encoding

To support interoperability with heterogeneous endpoints, Service Bus allows you to control the content type, the JMS type, and the encoding used.

Service Bus does not make assumptions about what the external client or service needs, but uses the information configured for this purpose in the service definition. 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 protocols.

If the service type is:

• XML or SOAP with or without a WSDL file, the content type is text/XML.

• Messaging and the interface is MFL or binary, the content type is binary/octet-stream.

• Messaging and the interface is text, the content type is text/plain.

• Messaging and the interface is XML, the content type is text/XML.

• Messaging and the interface is Java, the content type is a Java Object.

Additionally, there is a JMS type, which can be byte or text for non-Java-type messages. You configure the JMS type to use when you define the service in Oracle Service Bus Console or in Oracle JDeveloper.

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 Creating and Configuring Proxy Services and Creating and Configuring Business Services.

12.17 Throttling Pattern

In Service Bus, 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 "Configuring Business Services for Message Throttling" in Administering Oracle Service Bus.

12.18 WS-I Compliance

Service Bus provides Web Service Interoperability (WS-I) compliance for SOAP 1.1 services in the runtime environment. The WS-I basic profile has the following goals:

• Disambiguate the WSDL and SOAP specifications wherever ambiguity exists.

• Define constraints that can be applied when receiving messages or importing WSDL files so that interoperability is enhanced. When messages are sent, construct the message so that the constraints are satisfied.

The WS-I basic profile is available at the following URL: http://www.ws-i.org/Profiles/BasicProfile-1.1.html

When you configure a proxy service or business service based on a WSDL file, you can use the Oracle Service Bus Console or Oracle JDeveloper to specify whether you want Service Bus to enforce WS-I compliance for the service. For more information, see Security and Security Policies for Business Services.

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. Oracle 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 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 Service Bus should satisfy all of the supported WS-I compliance checks. This includes the following content:

• Service invocation request message.

• System-generated error messages returned by a proxy service.

• HTTP status codes generated by a proxy service.

The Enforce WS-I Compliance check box is displayed as shown in Figure 12-3.

Figure 12-3 Enforce WS-I Compliance Check Box

Description of "Figure 12-3 Enforce WS-I Compliance Check Box"

12.18.1 WS-I Compliance Checks

Note:

WS-I compliance checks require that the system knows what operation is being invoked on a service. For request messages received by a proxy service, that means that the context variable $operation should not be null. That depends upon the operation selection algorithm being configured properly. For response messages received from invoked services, the operation should be specified in the action configurations for route, publish, and service callout.

When you configure WS-I compliance checking for a proxy service or a business service, Service Bus carries out the following checks, shown in Table 12-13.

Table 12-13 Service Bus WS-I Compliance Checks

Check	WS-I Basic Profile Details	Service Bus Description
3.1.1 SOAP Envelope Structure	R9980 An Envelope must conform to the structure specified in SOAP 1.1, Section 4, "SOAP Envelope" (subject to amendment).	This check applies to request and response messages. If a response message is checked and the message does not possess an outer Envelope tag, a soap:client error is generated. If the message is an Envelope tag but possesses a different namespace, it is handled by the 3.1.2 SOAP Envelope Namespace.
3.1.2 SOAP Envelope Namespace	R1015 A Receiver must generate an error if they encounter an envelope whose document element is not soap:Envelope.	This check applies to request and response messages and is related to the 3.1.1 SOAP Envelope Structure. If a request message has a local name of Envelope, but the namespace is not SOAP 1.1, a soap:VersionMismatch error is generated.
3.1.3 SOAP Body Namespace Qualification	R1014 The child elements of the soap:body element in an Envelope must be namespace qualified.	This check applies to request and response messages. All request error messages generate a soap:Client error.
3.1.4 Disallowed Constructs	R1008 An Envelope must not contain a Document Type Declaration.	This check applies to request and response messages. All request error messages generate a soap:Client error.
3.1.5 SOAP Trailers	R1011 An Envelope must not have any child elements of soap:Envelope following the soap:body element.	This check applies to request and response messages. All request error messages generate a soap:Client error.
3.1.9 SOAP attributes on SOAP 1.1 elements	R1032 The soap:Envelope, soap:header, and soap:body elements in an Envelope must not have attributes in the namespace http://schemas.xmlsoap.org/soap/envelope/	This check applies to request and response messages. Any request error messages generate a soap:client error.
3.3.2 SOAP Fault Structure	R1000 When an Envelope is a fault, the soap:Fault element must not have element children other than faultcode, faultstring, faultactor, and detail.	This check only applies to response messages.
3.3.3 SOAP Fault Namespace Qualification	R1001 When an Envelope is a Fault, the element children of the soap:Fault element must be unqualified.	This check only applies to response messages.
3.4.6 HTTP Client Error Status Codes	R1113 An instance should use a "400 Bad Request" HTTP status code if a HTTP request message is malformed. R1114 An instance should use a "405 Method not Allowed" HTTP status code if a HTTP request message is malformed. R1125 An instance must use a 4xx HTTP status code for a response that indicates a problem with the format of a request.	Only applies to responses for a proxy service where you cannot influence the status code returned due to errors in the request.
3.4.7 HTTP Server Error Status Codes	R1126 An instance must return a "500 Internal Server Error" HTTP status code if the response envelope is a fault.	This check applies differently to request and response messages. For request messages, any faults generated have a 500 Internal Server Error HTTP status code. For response messages, an error is generated if fault responses are received that do not have a 500 Internal Server Error HTTP status code.
4.7.19 Response Wrappers	R2729 An envelope described with an rpc-literal binding that is a response must have a wrapper element whose name is the corresponding wsdl:operation name suffixed with the string Response.	This check only applies to response messages. Service Bus never generates a non-fault response from a proxy service.
4.7.20 Part Accessors	R2735 An envelope described with an rpc-literal binding must place the part accessor elements for parameters and return value in no namespace. R2755 The part accessor elements in a message described with an rpc-literal binding must have a local name of the same value as the name attribute of the corresponding wsdl:part element.	This check applies to request and response messages. Any request error messages generate a soap:client error.
4.7.22 Required Headers	R2738 An envelope must include all soapbind:headers specified on a wsdl:input or wsdl:output of a wsdl:operation of a wsdl:binding that describes it.	This check applies to request and response messages. Any request error messages generate a soap:client error.
4.7.25 Describing SOAPAction	R2744 A HTTP request message must contain a SOAPAction a HTTP header field with a quoted value equal to the value of the soapAction attribute of soap:operation, if present in the corresponding WSDL description. R2745 A HTTP request message must contain a SOAP action a HTTP header field with a quoted empty string value, if in the corresponding WSDL description, the SOAPAction of soapbind:operation is either not present, or present with an empty string as its value.	This check applies to request messages and a soap:client error is returned.

12.19 Converting Between SOAP 1.1 and SOAP 1.2

Service Bus supports SOAP 1.1 and SOAP 1.2. A SOAP 1.1 proxy service can invoke a SOAP 1.2 business service or vice versa. However, due to differences between SOAP 1.1 and 1.2, Service Bus cannot automatically convert between the two in every situation. Use the following guidance to ensure proper conversion between SOAP 1.1 and 1.2:

• The SOAP namespace is automatically changed by Service Bus before invoking the business service. If a fault comes back from the business service it is automatically changed to the SOAP version of the proxy service. It is, however, up to the pipeline actions to map the SOAP header-related XML attributes (like MustUnderstand) between the two versions. It is also up to the pipeline actions to change the SOAP encoded namespace for encoded envelopes.

• Automatic conversion from SOAP 1.1 to SOAP 1.2 will work correctly only if the payload uses doc/ or rpc/literal encoding.

• In SOAP 1.1, the encodingStyle attribute is allowed on any element in the envelope. In SOAP 1.2, the encodingStyle attribute is allowed only on child elements of the Body. Automatic conversion from SOAP 1.1 to SOAP 1.2 may result in an invalid envelope if the encodingStyle attribute in SOAP 1.1 is present outside of child elements of Body, Header, and Fault detail. You must perform SOAP conversion in the proxy service pipeline to ensure a valid envelope.

• If the SOAP 1.1 and SOAP 1.2 services use different encoding styles, such as rpc/encoded to doc/literal, you must perform SOAP conversion in the proxy service pipeline.