The $header variable contains SOAP headers associated with a message. The $header variable points to a <SOAP:Header> element with headers as sub-elements. Note that if the proxy service is SOAP 1.2, the $header variable contains a SOAP 1.2 Header element. In the case of non-SOAP messages or SOAP messages with no headers, the <SOAP:Header> element is empty, with no sub-elements.

The $body variable represents the core message payload and always points to a <SOAP:Body> element. Note that if the proxy service is SOAP 1.2, $body contains a SOAP 1.2 Body element. The core payload for both SOAP and non-SOAP messages is available in the same variable and with the same packaging; that is, wrapped in a <SOAP:Body> element:

• In the case of SOAP messages, the SOAP body is extracted from the envelope and assigned to the $body variable.

• In the case of non-SOAP, non-binary, messages, the full message contents are placed within a newly created <SOAP:Body> element.

• In the case of binary messages, rather than inserting the message content into the $body variable, a <binary-content/> reference element is created and inserted into the <SOAP:Body> element. To learn how binary content is handled, see Binary Content in the Body and Attachments Variables.

• In the case of Java objects, a <java-content/> reference element is created and inserted into the <SOAP:Body> element. To learn how Java content is handled, see Java Content in the Body Variable.

The $attachments variable holds the attachments associated with a message. The attachments variable is defined by an XML schema. It consists of a single root node, <ctx:attachments>, with a <ctx:attachment> sub-element for each attachment. The sub-elements contain information about the attachment (derived from MIME headers) as well as the attachment content and any custom headers for the attachment.

As with most of the other message-related variables, $attachments is always set, but if there are no attachments, the $attachments variable consists of an empty <ctx:attachments> element. The $attachments variable contains the following for each attachment:

• The attachment, if the attachment is XML.

• A reference XML, if the attachment is binary.

• Text, if the attachment is text.

Each attachment element includes the set of sub-elements described in Table A-2.

With the exception of the untyped body element, all other elements contain string values that are interpreted in the same way as they are interpreted in MIME. For example, valid values for the Content-Type element include text/xml and text/xml; charset=utf-8.

The parsing of attachments is not recursive. If an attachment has a Content-Type of multipart/..., the body element holds the original unpacked MIME content as a stream of bytes and does not contain attachment sub-elements. Because the MIME stream may contain binary data, it is represented by a <binary-content> reference element. To learn how binary content is handled, see Binary Content in the Body and Attachments Variables.

Messages whose Content-Type is multipart/form-data are constructed at runtime as follows:

• Inbound: All parts of a received inbound multipart/form-data type message are assigned to the $attachments variable. The $body variable is left empty.

• Outbound: The content of an outbound multipart/form-data type message is built from the content of the $attachments variable. Nothing from $header or $body is included.

  Note:

  If the inbound message is of a different multipart type than multipart/form-data (for example, multipart/related) and the outbound message is multipart/form-data, you must explicitly preserve the headers and content of the inbound root part, because they will not otherwise be passed through.

Service Bus does not support sending attachments to EJB, Tuxedo, and DSP services.

In the case of both the $body and $attachments variables, text, XML, and MFL content is placed directly inside an XML element. For binary data, which can contain byte values that are illegal in XML, Service Bus does not place the binary content in the XML element. Consequently, the binary content cannot be manipulated, but it is handled efficiently.

When binary content is received, the Service Bus runtime stores it in an in-memory hash table and a reference to that content is inserted into the XML (body or attachments) element. This reference is represented by the following XML snippet:

<binary-content ref="..."/>

where the ref attribute contains a URI or URN that uniquely identifies the binary content. This XML can be manipulated in a pipeline pair, branch, or route node in the same way any other content can be manipulated, but only the reference and not the underlying binary content is affected.

For example:

• Binary content in the $body variable can be copied to an attachment by copying the reference XML to the body sub-element of an attachment element.

• Binary content in two different attachments can be swapped by swapping the snippets of reference XML or by swapping the values of the ref attributes.

When messages are dispatched from Service Bus, the URI in the reference XML is used to restore the relevant binary content in the outgoing message. For information about how outbound messages are constructed, see Constructing Messages to Dispatch.

Clients and certain transports, notably email, file, and FTP can use this same reference XML to implement pass-by-reference. In this case, the transport or client creates the reference XML rather than the proxy service runtime. Also, the value of the URI in the ref attribute is specified by the user who creates the reference XML. For these cases in which the reference XML is not created by the proxy service runtime—specifically, when the URI is not recognized as one referring to internally managed binary content—Service Bus does not de-reference the URI, and the content is not substituted into an outgoing message.

Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
        start="<rootpart@example.com>"
Content-Description: This is the optional message description.
--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <rootpart@example.com>

<?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">
    <m:SendClaim xmlns:m="http://example.com/mimewsdl“>
      <ClaimDetail>
          <Name>...</Name>
          <!-- additional claim details -->
      </ClaimDetail>
      <ClaimPhoto href="cid:4d7a5fa2-14af-451c-961b5c3abf786796@example.com"/>
    </m:SendClaim>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
 
--MIME_boundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <4d7a5fa2-14af-451c-961b5c3abf786796@example.com>
 
...MIME attachment of binary photograph...
--MIME_boundary—

The Service Bus pipeline supports Java objects as inputs and outputs to Java callout actions. A POJO returned by a Java callout is cached in the pipeline, and its key is returned wrapped in an XML message of the form <java-content ref="cid:kkkkeeeeyyyy"/>, where cid:kkkkeeeeyyyy is a key automatically generated by the producing action and used to index the object in the pipeline's POJO repository. Any subsequent action then passes that XML unmodified as an argument.

The content of a POJO variable is not directly accessible by pipeline actions at configuration time. Rather, the content can be handled in the following ways:

• The content's metadata (that is, its key) can be handled as any other XML, for example in an XQuery such as $pojo/java-content/@ref. This may be useful for logging or debugging, but the content of the object cannot be directly accessed.

• The content can be assigned to a new variable that automatically becomes typed (in the pipeline) as a POJO. The object itself is not touched. The <java-content.../> XML snippet is copied from the source variable to the target variable.

• The content can be passed to another appropriate action (like Java callout) as a variable (for example, $pojo). The object itself is not touched. The argument is automatically de-referenced to the actual object.

The Java object is removed from the pipeline's POJO repository when you delete all variables holding the object's key (in <java-content />) or when you delete all XPaths pointing to the <java-content /> snippet.

For processing message content, you can specify that the pipeline streams the content rather than loading it into memory. When you enable content streaming for a pipeline, you specify whether to buffer the streamed content to memory or a disk file as an intermediate step during the processing of the message. The creation of these temporary files might affect performance. For information about protecting temporary files, see "Protection of Temporary Files With Streaming body Content" in Administering Oracle Service Bus.

When you enable the streaming option, content streaming applies only to the $body variable.

In general, use content streaming:

• When processing large content messages. See the guidelines in Best Practices for Using Content Streaming.

• In use cases where Service Bus accesses the payload a small number of times.

• For content-based routing without transformations; content streaming results in better performance due to the benefits from partial parsing.

For processing message attachments, you can specify that Service Bus page MIME attachments to disk and then stream the contents rather than buffering the attachments in memory and parsing them into XML. This is particularly advantageous when working with large attachments. Using this approach, Service Bus buffers only the headers and exposes the rest of the message payload as a stream from which smaller portions can be read at a time. Streamed transfers can improve the scalability of a service by eliminating the need for large memory buffers.

When enabled for pipelines, the setting applies to the handling of inbound request messages. For HTTP business services, the setting applies in the handling of outbound response messages. The following actions allow outbound messages to be dispatched and support streaming attachments:

• Route, Dynamic Route, and Route Table

• Publish, Dynamic Publish, and Publish Table

When streaming is enabled, all attachments, including binary, text, and XML, are processed as opaque data, which means you cannot run XQueries or XPath expressions based on the XML content of the attachment.

<con:attachments xmlns:con="http://www.oracle.com/wli/sb/context">
    <con:attachment>
        <con:Content-Type>image/jpeg</con:Content-Type>
        <con:Content-ID>
            &lt;1.urn:uuid:BFB7D745CBAF21BA5B12023554608963@apache.org>
        </con:Content-ID>
        <con:Content-Transfer-Encoding>
            binary
        </con:Content-Transfer-Encoding>
        <con:body>
            <con:binary-content ref="cid:23976580:1183dd6aab9:-7fe0"/>
        </con:body>
    </con:attachment>
</con:attachments>

Service Bus enables you to configure pipelines to decode and parse inbound messages in XOP/MTOM format and to send responses using the XOP/MTOM format, when appropriate. Oracle also enables you to configure business services to encode outbound messages in XOP/MTOM format.

Service Bus supports pipelines with the following binding types to accept and decode incoming XOP/MTOM payloads:

• Any XML

• Messaging (XML)

• Any SOAP

• WSDL-based

Pipelines of any other service binding type that receive XOP/MTOM payloads treat them the same as any other MIME multipart request without MTOM-specific handling.

In addition, the following Service Bus transports support XOP/MTOM:

• HTTP/S

• Local

• SB (when applicable, such as with chained Service Bus domains)

Service Bus supports all existing actions that allow outbound messages to be dispatched, including the following:

• Route, Dynamic Route and Route Table

• Publish, Dynamic Publish and Publish Table

• Service Callout

Service Bus does not support combining MTOM and SOAP with Attachments (SwA).

Service Bus supports custom MIME headers for both inbound request/outbound response and outbound request/inbound response message patterns. When an inbound message includes a custom header and the message is read in the pipeline, the custom header information appears in the user-headers element in the XML, as shown in the example below.

<con:user-headers>
    <con:user-header name="MyCustomHeader" value="Custom Header Value" />
</con:user-headers>

For an outbound request with an inbound response, Service Bus converts any user-header elements to custom headers in the corresponding MIME part when Service Bus constructs the outbound request message. user-header elements can be the result of the (unpacked) inbound request or can be added manually in an explicit pipeline action, such as insert, replace or assign actions.

This section describes the sub-elements of the $inbound and $outbound context variables, including information about whether a given sub-element is initialized at runtime. To learn about how context variables are initialized, see Initializing Context Variables. The sub-elements include the following:

• service

• transport

• security

service_bus-home/config/plugins/

service_bus-home/config/plugins/

When an error is an XML parsing error, the malformed XML text is included in the PayloadDetail element in the error schema, as described in Error Details. Parsing errors are only detected when parsing inbound request messages to the pipeline and outbound response messages to the business services. Actions that explicitly change the payload, such as an assign action, that result in malformed XML are not included in this error detail.

Only the part of the payload that was read by the XML parser is included in the fault variable, so the PayloadDetail element might not include the entire XML text. By default, there is no limit to the number of characters that can be included in the error detail. To limit the size of the XML text included in the payload detail of the fault variable, set the system property com.bea.wli.sb.FaultPayloadDetailMaxSize to the size of the text you want to include (in bytes). Setting this property to 0 (zero) disables the feature, which means faults will not include the PayloadDetail element.

If the pipeline has content streaming enabled, the text placed in the PayloadDetail element is truncated to either 10KB or to the max size you set, if it is less than 10KB. If the payload contains binary characters, the payload is base64-encoded and placed in the base64 child element of the PayloadDetail element (up to the maximum payload detail size).

The $attachments context variable is initialized with any MIME attachments that accompany the message, but does not include the part representing the main message (whether it is SOAP, XML, MFL, and so on). Each <attachment> element is initialized using the MIME headers that accompany each part in the MIME package.

The contents of the <body> element in the <attachment> can be one of the following depending on the attachment's Content-Type:

• XML

• text

• A snippet of reference XML that refers to the attachment content (see Binary Content in the Body and Attachments Variables.)

This section describes how the initialization of $header and $body context variables is performed depending on the type of service: SOAP Services, XML Services (Non SOAP), Messaging Services.

The $body variable includes the <soap-env:Body>...</soap-env:Body> element. (If the service is SOAP 1.2, the $body variable contains a SOAP 1.2 Body element.) For example, if you assign data to the $body context variable using the Assign action, you must wrap it with the <soap-env:Body> element. In other words, you build the SOAP package by including the <soap-env:Body> element in the context variable.

There is an exception to this behavior for the case in which you build the Request Document Variable for the service callout action. Service callout actions work with the core payload (RPC parameters, documents, and so on) and Service Bus builds the SOAP package around the core payload. In other words, when you configure the Request Document Variable for a service callout action, you do not wrap the input document with <soap-env:Body>...</soap-env:Body>.

For information about configuring the service callout action, see Adding Service Callout Actions in JDeveloper.

The $header variable includes the <soap-env:Header>...</soap-env:Header> element. (If the proxy service is SOAP 1.2, the $header variable contains a SOAP 1.2 Header element.) For example, if you assign data to the $header context variable using the Assign action, you must wrap it with the <soap-env:Header> element. In other words, you build the SOAP package by including the <soap-env:Header> element in the context variable. This is true for all manipulations of $header, including the case in which you can set one or more SOAP headers for a service callout request. For information about configuring SOAP headers for a service callout action, see Adding Service Callout Actions in JDeveloper.

Extract the WS-Addressing Header—From: $header/wsa:From

Extract the Payload From a Non-SOAP Message: $body/*

Extract the user-header From an Outbound Response Message: $outbound/ctx:transport/ctx:response/tp:user-header[@name='myheader']/@value

When creating a $body input variable that is used for the request parameter in a service callout to a SOAP Service, you would define that variable's contents using $body/* (to remove the wrapper soap-env:Body), not $body (which results in keeping the soap-env:Body wrapper).

Assign Variable Contents for Request Parameter in a Service Callout: $body/*

An outgoing SOAP message is constructed by wrapping the contents of the $header and $body variables inside a <soap:Envelope> element. If the invoked service is a SOAP 1.2 service, the envelope created is a SOAP 1.2 envelope. If the invoked service is a SOAP 1.1 service, the envelope created is a SOAP 1.1 envelope. If the $body variable contains a piece of reference XML, it is sent as is; in other words, the referenced content is not substituted into the message.

If attachments are defined in the $attachments variable, a MIME package is created from the main message and the attachment data. The handling of the content for each attachment part is similar to how content is handled for messaging services.

The messages to XML-based services from Service Bus are constructed from the contents of the $body variable:

• If the $body variable is empty, then a zero-size message is sent.

• If the $body variable contains multiple XML snippets, then only the first snippet is used in the outbound message. For example, if <soap:Body> contains <abc/><xyz/>, only <abc/> is sent.

• If the content of the $body variable is text and not XML, an error is thrown.

• If the $body variable contains a piece of reference XML, it is sent as is; in other words, the referenced content is not substituted into the message.

• If attachments are defined in the $attachments variable, a MIME package is created from the XML message and the attachment data. In the case of a null XML message, the corresponding MIME body part is empty. The handling of the content for each attachment part is similar to how content is handled for messaging services.

Regardless of any data it contains, the $header variable does not contribute any content to the outbound message. For examples of how messages are constructed for service callout actions, see Working with Pipeline Actions in Oracle JDeveloper.

The messages to messaging services from Service Bus are constructed from the contents of the $body variable.

• If the $body variable is empty, then a zero-size message is sent, regardless of the outgoing message type.

• If the outgoing message type is XML, then the message is constructed in the same way as it is for XML Services (Non SOAP).

• If the outgoing message type is MFL, then the behavior is similar to that for XML message types except that the extracted XML is converted to MFL. An error occurs if the XML > MFL conversion cannot be performed.

• If the target service requires text messages, the contents of the $body variable are interpreted as text and sent. In this way, it is possible for Service Bus to handle incoming XML messages that must be delivered to a target service as text. In other words, you do not need to configure the message flow to handle such messages.

• For target services that expect binary messages, the $body variable must contain a piece of reference XML—the reference URI references the binary data stored in the Service Bus in-memory hash table. The referenced content is sent to the target service.

  For cases in which a client, a transport, or the designer of a service specifies the reference URI, the referenced data is not stored in Service Bus and thus cannot be de referenced to populate the outbound message. Consequently, the reference XML is sent in the message.

  If the $body variable contains a piece of reference XML, and the target service requires a message type other than binary, the reference XML inside the $body variable is treated as content. In other words, it is sent as XML, converted to text, or converted to MFL. This is true regardless of the URI in the reference XML.

Regardless of any data it contains, the $header variable does not contribute any content to the outbound message.

For examples of how messages are constructed for service callout actions, see Working with Pipeline Actions in Oracle JDeveloper.