User’s Guide

Message Context

This section describes the ALSB message context model and the predefined context variables that are used in message flows. It includes the following topics:

The Message Context Model

ALSB message context is a set of properties that hold message content as well as information about messages as they are routed through ALSB. These properties are referred to as context variables—for example, service endpoints are represented by predefined context variables. ALSB also supports user-defined context variables.

The message context is defined by an XML schema. You typically use XQuery expressions to manipulate the context variables in the message flow that defines a proxy service.

Predefined Context Variables

Table 5-1 describes the predefined context variables. The predefined context variables can be grouped into the following types: message-related variables, inbound and outbound variables, the operation variable, and the fault variable.

For information about the element types in the message context variables, see Message Context Schema.

Table 5-1 Predefined Context Variables in ALSB
Context Variable¹	Description	See Also...
`header`	For SOAP messages, `header` contains the SOAP header. (If the proxy service 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`	For the following cases: SOAP messages—contains the `<SOAP:Body>` part extracted from the SOAP envelope. (If the proxy service is SOAP 1.2, the `body` variable contains a SOAP 1.2 Body element.) Non-SOAP, non-binary messages—contains the entire message content wrapped in a `<SOAP:Body>` element. Binary messages—contains a `<SOAP:Body>` wrapped reference to an in-memory copy of the binary message. Java objects—contains a `<SOAP:Body>` wrapped reference to an in-memory copy of the Java object.	Message-Related Variables
`attachments`	Contains the MIME attachments for a given message.	Message-Related Variables
`inbound`	Contains: Information about the proxy service that received a message The inbound transport headers	Inbound and Outbound Variables
`outbound`	Contains: Information about the target service to which a message is to be sent The outbound transport headers	Inbound and Outbound Variables
`operation`	Identifies the operation that is being invoked on a proxy service.	Operation Variable
`fault`	Contains information about errors that have occurred during the processing of a message.	Fault Variable

¹The Message Context Schema specifies the element types for the message context variables.

Message-Related Variables

Together, the message-related variables header, body and attachments represent the canonical format of a message as it flows through ALSB. These variables are initialized using the message content received by a proxy service and are used to construct the outgoing messages that are routed or published to other services.

If you want to modify a message as part of processing it, you must modify these variables.

A message payload (that is, a message content exclusive of headers or attachments) is contained in the body variable. The decision about which variable’s content to include in an outgoing message is made at the point at which a message is dispatched (published or routed) from ALSB. That determination is dependent upon whether the target endpoint is expecting a SOAP or a non-SOAP message:

When a SOAP message is expected, the header and body variables are combined in a SOAP envelope to create the message.
When a non-SOAP message is expected, the contents of the Body element in the body variable constitutes the entire message.
In either case, if the service expects attachments, a MIME package is created from the resulting message and the attachments variable.

Header Variable

The header variable contains SOAP headers associated with a message. The header variable points to a <SOAP:Header> element with headers as sub-elements. (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.

Body Variable

The body variable represents the core message payload and always points to a <SOAP:Body> element. (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.

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

Each attachment element includes a set of sub-elements, as described in Table 5-2.

Table 5-2 Sub-Elements of the Attachments Variable
Elements of the Attachments Variable	Description¹
`Content-ID`	A globally-unique reference that identifies the attachment.The type is `string`.
`Content` `Type`	Specifies the media type and sub-type of the attachment. The type is `string`.
`Content-Transfer-Encoding`	Specifies how the attachment is encoded. The type is `string`.
`Content-Description`	A textual description of the content. The type is `string`.
`Content-Location`	A locally-unique URI-based reference that identifies the attachment. The type is `string`.
`Content-Disposition`	Specifies how the attachment should be handled by the recipient. The type is `string`.
`body`	Holds the attachment data. The type is `anyType`.

¹The Message Context Schema specifies the element types for the message context variables.

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 run-time 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.

Attachments are supported on inbound requests and on outbound responses (that is, in messages received by a proxy service) only when the transport is HTTP, HTTPS or e-mail. Attachments are supported for all transport types for outbound requests and inbound responses (that is for messages sent by a proxy service).

ALSB does not support sending attachments to EJB-based or Tuxedo-based services.

Binary Content in the body and attachments Variables

In the case of both the body and attachments variables, text-, XML- and MFL-based content is placed directly inside of an XML element. For binary data, which can contain byte values that are illegal in XML, ALSB 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 ALSB run time 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 ALSB pipeline, 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 ALSB, 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 e-mail, 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 run time. Also, the value of the URI in the ref attribute is specified by the user that creates the reference XML. For these cases in which the reference XML is not created by the proxy service run time—specifically, when the URI is not recognized as one referring to internally managed binary content—ALSB does not de-reference the URI, and the content is not substituted into an outgoing message.

Java Content in the body Variable

The ALSB 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 cache. 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 cache 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.

Streaming body Content

For processing message content, you can specify that the ALSB pipeline streams the content rather than loading it into memory. When you enable content streaming for a proxy service, 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 the AquaLogic Service Bus Security Guide.

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

Best Practices for Using Content Streaming

Use the following guidelines and recommendations:

When you enable streaming for large message processing, you cannot use the assign, replace, rename, for each, validate, and delete actions with respect to the body message context variable, because these actions require the input variable to be fully materialized in memory and full materialization is incompatible with the content streaming option.
You can use the results of an XQuery or XSL transformation from a very large $body with these pipeline actions:

Assign, insert, and replace actions—to update the value of another context variable (not $body). However, you must ensure that the result of the expression is small enough to be fully materialized and stored in the message context.
Java callouts—to pass input arguments. All input to Java callouts is fully materialized, therefore, the results of expressions used as input must be small enough to be fully materialized.
MFL transformations—to transform very large payloads without first materializing the input as an XML Bean. When using a very large $body as an input to an MFL transformation, declare a messaging service, binary message type proxy service. If you declare a messaging service, text message type proxy service, $body will get fully materialized to obtain an input stream for the transformation.
Alert, log, and report actions—to report the result of an XQuery or XSL transformation on a very large $body.
Service callouts

For XSL transformations, all input is fully materialized in order to perform the transformation, therefore, you must ensure that the input is small enough so that it can be fully materialized and processed by the XSLT processor.
With very large MFL input, you should use a MFL service instead of a MFL stage action to perform a MFL-to-XML transformation.
Do not use the test console to test proxy services with very large content messages because the content will be fully materialized, potentially causing an OOM exception, and displayed, causing a slowdown in the console window.
When writing XQueries, use proper indexing to achieve partial parsing.

For example, instead of writing $body/*:DateTimeStruct, which would consume the entire input stream, write:

($body/*:DateTimeStruct)[1] or $body[1]/*:DateTimeStruct[1]

By using indexing, only content up to and including the first DateTimeStruct element will be parsed.

Because each variable that is accessed by two or more consumers (expressions) is materialized, when writing XQueries, avoid statements such as:

let $labdata1 := $body/*
return <HEADER>{ $labdata1/HEADER/@*, $labdata1/HEADER/node() }</HEADER>

In this case, $labdata1 is bound to the whole document without the root element so the XQuery engine runs out of memory when trying to materialize it.

One way of changing this query to avoid excessive materialization would be to move the /HEADER path expression inside the let clause.

let $labdata1 := $body/*/HEADER
...

In this case, the XQuery engine will only materialize the HEADER element or elements.

Another way to avoid materialization would be to use the fn-bea:rename() function in which you can rename elements in a streaming mode.

fn-bea:rename($oldelements as element()*, $newname as element()) as element()*

For example:

fn-bea:rename($body/*/HEADER, <HEADER_NEW/>)

At run time, processing large messages is subjected to the limitations and restrictions of the underlying transport; for example, the message size handling limitations of the transport. Be aware of the JVM and RMI settings that limit the capacity of the transport to accept large messages.

Inbound and Outbound Variables

The inbound and outbound context variables contain information about the inbound and outbound endpoints. The inbound variable contains information about the proxy service that received the request message; the outbound variable contains information about the target business service to which a message is sent.

The outbound variable is set in the route action in route nodes and publish actions. You can modify $outbound by configuring request and response actions in route nodes and by configuring request actions in publish actions.

WARNING: Some modifications that you can make for the inbound and outbound context variables are not honored at run time. That is, the values of certain headers and metadata can be overwritten or ignored by the ALSB run time. The same limitations are true when you set the transport headers and metadata using the transport headers and service callout actions, and when you use the Test Console to test your proxy or business services. For information about the headers and metadata for which there are limitations, see Understanding How the Run Time Uses the Transport Headers Settings. Note also that any modifications you make to $outbound in the message flow outside of the request or response actions in route nodes and publish actions are ignored. In other words, those modifications are overwritten when $outbound is initialized in the route nodes and publish actions.

You cannot modify the outbound variable in service callout actions.

The inbound and outbound variables have the following characteristics:

Have the same XML schema—the inbound and outbound context variables are instances of the endpoint element as described in Message Context Schema.
Contain a single name attribute that identifies the name of the endpoint as it is registered in the service directory. The name attribute should be considered read-only for both inbound and outbound.

WARNING:

The read-only rule is not enforced. Changing read-only elements can result in unpredictable behavior.

Contain the service, transport and security sub-elements described in the following section.

Attachments are supported on inbound requests and outbound responses (that is, in messages received by a proxy service) only when the transport is HTTP, HTTPS or e-mail.

Attachments are supported for all transport types for outbound requests and inbound responses (that is for messages sent by a proxy service).

ALSB does not support sending attachments to EJB-based or Tuxedo-based services.

Sub-Elements of the inbound and outbound Variables

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

service

The service element is read-only for both inbound and outbound. Sub-elements include providerName and operation.

Sub-Elements¹

Description...

providerName

Specifies the name of the service key provider.

Initialized based on the configuration of publish and routing actions.

operation

(outbound only)

Used in the outbound variable, specifies the name of the operation to be invoked on the target business service.

Initialized based on the inbound and outbound.

Note: This element is used for the outbound variable only. In the case of inbound messages, the name of the operation to be invoked on the proxy service is specified by the operation variable.

¹The Message Context Schema specifies the element types for the message context variables.

transport

The transport element is read-only on inbound, except for the response element, which you can modify to set the response transport headers. The sub-elements of the transport element are described in Table 5-4.

Sub-Elements¹

Description...

uri

Identifies the URI of the endpoint:

When used in the inbound variable, this is the URI by which the message arrived.
When used in the outbound variable, this is the URI to use when sending the message—it overrides any URI value registered in the service directory.

Initialization

The URI element is initialized as follows:

Always initialized on the inbound variable
Never initialized on the outbound variable. You can set the URI on outbound when you want to override the set of URIs in the service configuration. URI failover is not supported if this element is set.

request

This element is read-only² in the inbound variable. You can modify it for the outbound variable.

Specifies transport-specific metadata about the request (including transport headers). The value for this element is defined by the transport protocol (specifically, the RequestMetaData XML defined by the transport SDK).Therefore, the structure of this element depends on the transport being used.

To learn about the transport-specific types for this element, see the appropriate transport schema, which are available in the following directory in your ALSB installation:

BEA_HOME/alsb_3.0/lib/transports/

where BEA_HOME represents the directory in which you installed ALSB.

Initialization

The URI element is initialized as follows:

Initialized on the inbound variable using information from the request message received by ALSB.
On the outbound variable, the request element is created with the proper typing. The typing is transport-dependent. The request element is typically initialized as an empty element, with the exception of certain important transport headers—for example, content-type and SOAPAction.

You can set a filename for an outbound message using the File transport protocol by configuring $outbound in a route node request action, as follows:

If the fileName only is specified, a file of that name is stored at the location specified by the endpoint URI of the target business service.
If isFilePath is set to true, the value of fileName is used as a relative path appended to the endpoint URI of the target business service. For example, if the endpoint URI is file:////apollo/ob/data, and the fileName header is set to ./foo/bar.xml, and isFilePath is set to true, the message will be stored at /apollo/ob/data/foo/bar.xml.

If a file already exists with that name, a new name is generated, following the format path/filename_random-number.xml, where random-number is an integer in the range of 0 to 999999.

response

This element is read-only in the outbound variable. You can modify it for the inbound. variable.

Specifies transport-specific metadata about the response (including transport headers). The value for this element is defined by the transport protocol (specifically, the ResponseMetaData XML defined by the transport SDK).Therefore, the structure of this element depends on the transport being used.

To learn about the transport-specific types for this element, see the appropriate transport schema, which are available in the following directory in your ALSB installation:

BEA_HOME/alsb_3.0/lib/transports/

where BEA_HOME represents the directory in which you installed ALSB.

Initialization

The URI element is initialized as follows:

Initialized on the outbound variable using information from the response message received by ALSB.
On the inbound variable, the response element is created with the proper typing. The typing is transport-dependent. The response element is typically initialized as an empty element, with the exception of certain important transport headers—for example, content-type and SOAPAction.

For a description of the standard HTTP headers, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

For a description of the standard JMS headers, see Value-Added Public JMS API Extensions.

Note: The following MQ headers do not have equivalents in BEA JMS: ApplOriginData, ApplIdentityData, Accounting Token

mode

Specifies whether the communication style is request (one-way) or request-response (two-way).

Initialization

Initialized on the inbound and outbound variables using information from the service and its operations (if applicable). For example, if a request-only operation is being invoked, the mode element is set to request, rather than to request-response.

qualityOfService

This element is read only for inbound.

You can modify it for the outbound case— in the outbound request actions of a publish or routing action.

Specifies the quality of service expected when sending or receiving a message. Valid values include best-effort and exactly-once:

best-effort means that each dispatch defines its own transactional context (if the transport is transactional).

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

For the scenario in which a message is dispatched as a result of a publish action, any dispatch errors are suppressed.

For the scenario in which a message is dispatched from a routing node, dispatch errors are not suppressed.
exactly-once means that the dispatch is included as part of the inbound transactional context (if one exists and if the outbound transport is transactional) and errors cause processing to abort and trigger the relevant error handler (in the case of both the route and publish scenarios).

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.

Initialization

The qualityOfService element is initialized on the inbound and outbound variables as follows:

In the inbound case, the quality of service (QoS) is dictated by the transport. For example, for the JMS/XA transport, the QoS is exactly once; for the HTTP transport, the QoS is best effort.
In the outbound case, the QoS is set differently for publishing and for routing, as follows:

Routing—When messages are routed to another service from a route node, the QoS is always initialized using the value from the inbound context variable. In other words, the outbound QoS is set to exactly once if (and only if) the inbound QoS is exactly once. Otherwise, the outbound QoS is set to best effort.

Publishing—When a message is published to another service as the result of a publish action, the quality of service (QoS) is always initialized to best effort regardless of the inbound setting.

retryCount

(outbound only)

Specifies the number of retries to attempt when sending a message from ALSB.

If retryCount is set, the setting overrides any retry count value configured in the target service configuration.

¹The Message Context Schema specifies the element types for the message context variables.

²The read-only rule is not enforced. Changing read-only elements can result in unpredictable behavior.

security

The sub elements of the security element are described in Table 5-5.

Sub-Elements¹

Description...

transportClient

(inbound only, read only²)

Specifies authenticated transport-level user information. The user information includes a username and any optional principals. The principals can themselves include zero or more groups, one for each group the subject belongs to.

Note: If the subject is anonymous, then the username is "anonymous" and there are no groups.

Initialized by ALSB. The inbound transportClient element is read-only.

messageLevelClient

(inbound only, read only²)

Specifies authenticated message-level user information. The user information includes a username and any optional principals. The principals can themselves include zero or more groups, one for each group the subject belongs to.

Note: If the subject is anonymous, then the username is "anonymous" and there are no groups.

Initialized by ALSB. The inbound messageLevelClient element is read-only.

doOutboundWss

(outbound only)

ALSB sets the value of this element during routing or publishing.

Some infrequently used design patterns set the value to false to preempt a proxy service from automatically generating the outbound WS-Security SOAP envelope.

Future releases of ALSB will provide an easier way to disable outbound WS-Security.

For more information, see “Disabling Outbound WS-Security” under Message-Level Security in AquaLogic Service Bus Security Guide.

¹The Message Context Schema specifies the element types for the message context variables.

²The read-only rule is not enforced. Changing read-only elements can result in unpredictable behavior.

Operation Variable

The operation variable is a read-only variable. It contains a string that identifies the operation to be invoked on a proxy service. If no operations are defined for a proxy service, the operation variable is not set and returns the equivalent of null.

ALSB provides the operation variable as a stand-alone variable, rather than as a sub-element of the inbound variable to optimize performance—the computation of the operation may be deferred until the operation variable is explicitly accessed rather than anytime the inbound variable is accessed.

Fault Variable

The fault variable is used to hold information about any error that has occurred during message processing. When an error occurs, this variable is populated with information before the appropriate error handler is invoked.

Note:

This variable is defined only in error handler pipelines and is not set in request and response pipelines, or in route or branch nodes.

The fault variable includes the errorCode, reason, details, and location sub-elements described in Table 5-6.

Table 5-6 Sub-Elements of the Fault Variable
Elements of the Fault Variables	Description¹...
`errorCode`	Specifies the error code as a string value
`reason`	Contains a text description of the error
`details`	Contains user-defined XML content related to the error
`location`	Identifies the node, pipeline and stage in which the error occurred. Also identifies if the error occurred in an error handler. The sub-elements include: node—the name of the pipeline, branch, or route node where an error occurred; a string. pipeline—the name of the Pipeline where an error occurred (if applicable); a string. stage—the name of the stage where an error occurred (if applicable); a string. error-handler—indicates if an error occurred from inside an error handler; a boolean.

¹The Message Context Schema specifies the element types for the message context variables.

The contents of the fault variable are modeled after SOAP faults to facilitate fault generation when replying from a SOAP-based proxy service. The values for error codes generated by ALSB correspond to system error codes and are prefixed with BEA string.

The error codes associated with the errors surface inside the element of the fault context variable. You can access the value using the following XQuery statement:

$fault/ctx:errorCode/text()

ALSB defines three generic error codes for the three classes of possible errors. The format of the generic codes is BEA-xxx000, where xxx represents a generic category as follows:

380 Transport
382 Proxy
386 Security
394 UDDI

This yields the generic codes as follows:

BEA– 380000—BEA– 380999

Indicates a transport error (for example, failure to dispatch a message).

BEA– 382000—BEA– 382499

Indicates a proxy service run-time error (for example, a stage exception).

BEA– 382500—BEA– 382999

Indicates an error in a proxy service action.

BEA– 386000—BEA– 386999

Indicates a WS-Security error (for example, authorization failure).

BEA– 394500—BEA– 394999

Indicates an error in the UDDI sub system.

ALSB defines unique codes for specific errors. For example:

BEA-382030—Indicates a message parse error (for example, a SOAP proxy service received a non-SOAP message).

BEA-382500—Reserved for the case in which a service callout action receives a SOAP Fault response.

For information about these and other specific error codes, see Error Codes in Using the AquaLogic Service Bus Console. See also Handling Errors in Message Flows.

Initializing Context Variables

The message context and its variables are initialized in the binding layer when a message is received and before message processing begins. Table 5-7summarizes how context variables are initialized.

Table 5-7 Initializing Context Variables
Context Variable	How Initialized
`outbound`	Initialized to null because no routing or errors have yet occurred. The outbound variable is initialized in the route action in route nodes and publish actions. You can modify `$outbound` through the request actions in routing nodes and publish actions (also in the response actions in routing nodes). For more information, see Inbound and Outbound Variables. For information about the initialization of sub-elements of `outbound`, see Sub-Elements of the inbound and outbound Variables.
`fault`
`inbound`	Initialized with service, transport and security information that is obtained from Service Bus metadata about the registered proxy service and transport-level metadata (transport headers, authenticated user information, and so on) about the specific incoming request. For information about the initialization of sub-elements of `inbound`, see Sub-Elements of the inbound and outbound Variables.
`header`	Initialized using the content of the inbound message. How the initialization is performed depends on the type of proxy service, as described in the subsequent topics in this section: Initializing the attachments Context Variable Initializing the header and body Context Variables The `header`, `body`, and `attachments` variables are re initialized after routing using the content of the response that is received. If no routing is performed or if the communication mode is request-only, then these variables are not re initialized. That is, they are not cleared of any content.
`body`
`attachments`
`operation`

Initializing the attachments Context Variable

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)

Initializing the header and body Context Variables

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

SOAP Services

Messages to SOAP-based services are SOAP messages containing XML that is contained in a <soap:Envelope> element. In the case that messages include attachments, the content of the inbound message is a MIME package that includes the SOAP envelope as one of the parts—typically the first part or one identified by the top-level Content-Type header. The context variables are initialized as follows:

header—initialized with the <soap:Header> element from the SOAP message
body—initialized with the <soap:Body> element from the SOAP message

XML Services (Non SOAP)

The messages to XML-based services are XML, but can be of any type allowed by the proxy service configuration. In the case that messages include attachments, the content of the inbound messages is a MIME package that includes the primary XML payload as one of the parts—typically the first part or one identified by the top-level Content-Type header.

The context variables are initialized as follows:

header—initialized with an empty <soap:Header/> element.
body—initialized with a <soap:Body> element that wraps the entire XML payload.

Messaging Services

Messaging services are those that can receive messages of one data type and respond with messages of a different data type. The supported data types include XML, MFL, text, untyped binary. The context variables are initialized as follows:

header—initialized with an empty <soap:Header/> element.
body—initialized with a <soap:Body> element that wraps the entire payload.

In the case of XML, MFL, and text content, it is placed directly within the <soap:Body> element.
In the case of binary content, a piece of reference XML is created and inserted inside the <soap:Body> element (see Binary Content in the body and attachments Variables). The binary content cannot be accessed or modified, but the reference XML can be examined, modified, and replaced with inline content.

Performing Operations on Context Variables

You interact with and manipulate the message context through actions in the pipelines, branch, or route nodes that define a proxy service. Most actions expose the XQuery language to do so. Each context variable is represented as an XQuery variable of the same name. For example, the header variable is accessible in XQuery as $header, the body variable is accessible as $body, and so on. The examples in this section show the use of XQuery to examine and manipulate context variables.

$body

The $body variable includes the <soap-env:Body>...</soap-env:Body> element. (If the proxy 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 in ALSB—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 ALSB 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 Proxy Services: Actions in Using the AquaLogic Service Bus Console.

$header

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 Proxy Services: Actions in Using the AquaLogic Service Bus Console.

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/*

Constructing Messages to Dispatch

When ALSB publishes or routes a message, the content of the message is constructed using the values of variables in the message context. For example, transport headers and other transport-specific metadata are taken from $outbound/transport/request. As is the case with initialization of the context, the message content for outbound messages is handled differently depending upon the type of the target service. How the outbound message content is created depends on the type of the target service, as described in the following topics:

SOAP Services

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.

XML Services (Non SOAP)

The messages to XML-based services from ALSB is 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 Proxy Services: Actions in Using the AquaLogic Service Bus Console.

Messaging Services

The messages to messaging services from ALSB 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 XMLMFL 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 ALSB 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 ALSB 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 proxy service specifies the reference URI, the referenced data is not stored in the ALSB 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 Proxy Services: Actions in Using the AquaLogic Service Bus Console.

About Sending Binary Content in Email Messages

For binary messages, ALSB does not insert the message content into the body variable. Instead, a <binary-content/> reference element is created and inserted into the <SOAP:Body> element (see Message-Related Variables). However, the email standard does not support sending binary content type as the main part of a message. If you want to send binary messages via email to a messaging service that accepts text or XML documents and optional attachments, you can do so as follows:

Transfer the binary-content reference XML from $body to $attachments.
Replace the content of $body with text or XML wrapped in a <SOAP:Body> element.

For the case in which the outgoing message type is MFL, the contents of $body is converted from XML to text or binary based on the MFL transformation:

If the target service expects to receive text message, you can set the content-type (the default is binary for MFL message type) as text/plain in $outbound
If the target service expects to receive binary messages, it is not possible to send MFL content via the email transport.

To learn more about how binary content is handled, see Binary Content in the body and attachments Variables.

Message Context Schema

The message context schema (MessageContext.xsd) that specifies the types for the message context variables is shown in Message Context.xsd.

When working with the message context variables, you need to reference MessageContext.xsd which is available in a JAR file, BEA_HOME/alsb_3.0/lib/sb-kernel-api.jar, and the transport-specific schemas, which are available at

BEA_HOME/alsb_3.0/lib/transports/

where BEA_HOME represents the directory in which you installed ALSB.

Message Context.xsd

<schema targetNamespace="http://www.bea.com/wli/sb/context"
        xmlns:mc="http://www.bea.com/wli/sb/context"
        xmlns="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="qualified"
        attributeFormDefault="unqualified">
    <!--============================================================== -->

    <!-- The context variable 'fault' is an instance of this element -->
    <element name="fault" type="mc:FaultType"/>

    <!-- The context variables 'inbound' and 'outbound' are instances of this element -->
    <element name="endpoint" type="mc:EndpointType"/>

    <!-- The three sub-elements within the 'inbound' and 'outbound' variables -->
    <element name="service" type="mc:ServiceType"/>
    <element name="transport" type="mc:TransportType"/>
    <element name="security" type="mc:SecurityType"/>

    <!-- The context variable 'attachments' is an instance of this element -->
    <element name="attachments" type="mc:AttachmentsType"/>

    <!-- Each attachment in the 'attachments' variable is represented by an instance of this element -->
    <element name="attachment" type="mc:AttachmentType"/>

    <!-- Element used to represent binary payloads and pass-by reference content -->
    <element name="binary-content" type="mc:BinaryContentType"/>

    <!-- =================================================================== -->

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

    <complexType name="BinaryContentType">
        <!-- URI reference to the binary or pass-by-reference payload -->
        <attribute name="ref" type="anyURI" use="required"/>
    </complexType>

    <!-- =================================================================== -->

    <complexType name="EndpointType">
        <all>
            <!-- Sub-elements holding service, transport, and security details for the endpoint -->
            <element ref="mc:service" minOccurs="0" />
            <element ref="mc:transport" minOccurs="0" />
            <element ref="mc:security" minOccurs="0" />
        </all>

        <!-- Fully-qualified name of the service represented by this endpoint -->
        <attribute name="name" type="string" use="required"/>
    </complexType>

    <!-- =================================================================== -->

    <complexType name="ServiceType">
        <all>
            <!-- name of service provider -->
            <element name="providerName" type="string" minOccurs="0"/>

            <!-- the service operation being invoked -->
            <element name="operation" type="string" minOccurs="0"/>
        </all>
    </complexType>

    <!-- =================================================================== -->

    <complexType name="TransportType">
        <all>
            <!-- URI of endpoint -->
            <element name="uri" type="anyURI" minOccurs="0" />

            <!-- Transport-specific metadata for request and response (includes transport headers) -->
            <element name="request" type="anyType" minOccurs="0"/>
            <element name="response" type="anyType" minOccurs="0" />

            <!-- Indicates one-way (request only) or bi-directional (request/response) communication -->
            <element name="mode" type="mc:ModeType" minOccurs="0" />

            <!-- Specifies the quality of service -->
            <element name="qualityOfService" type="mc:QoSType" minOccurs="0" />

            <!-- Retry values (outbound only) -->
            <element name="retryInterval" type="integer" minOccurs="0" />
            <element name="retryCount" type="integer" minOccurs="0" />
        </all>
    </complexType>

    <simpleType name="ModeType">
        <restriction base="string">
            <enumeration value="request"/>
            <enumeration value="request-response"/>
        </restriction>
    </simpleType>

    <simpleType name="QoSType">
        <restriction base="string">
            <enumeration value="best-effort"/>
            <enumeration value="exactly-once"/>
        </restriction>
    </simpleType>

    <!-- =================================================================== -->

    <complexType name="SecurityType">
        <all>
            <!-- Transport-level client information (inbound only) -->
            <element name="transportClient" type="mc:SubjectType" minOccurs="0"/>

            <!-- Message-level client information (inbound only) -->
            <element name="messageLevelClient" type="mc:SubjectType" minOccurs="0"/>
            
            <!-- Boolean flag used to disable outbound WSS processing (outbound only) -->
            <element name="doOutboundWss" type="boolean" minOccurs="0"/>
        </all>
    </complexType>

<complexType name="SubjectType">
  <sequence>
    <!-- User name associated with this tranport- or message-level subject -->
    <element name="username" type="string"/>
    <element name="principals" minOccurs="0">
     <complexType>
      <sequence>
      <!-- There is an element for each group this subject belongs to, as
        determined by the authentication providers -->
      <element name="group" type="string"
                     minOccurs="0" maxOccurs="unbounded"/>
      </sequence>
     </complexType>

<!-- =================================================================== -->

    <complexType name="FaultType">
        <all>
            <!-- A short string identifying the error (e.g. BEA38229) -->
            <element name="errorCode" type="string"/>

            <!-- Descriptive text explaining the reason for the error -->
            <element name="reason" type="string" minOccurs="0" />

            <!-- Any additional details about the error  -->
            <element name="details" type="anyType" minOccurs="0" />

            <!-- Information about where the error occured in the proxy -->
            <element name="location" type="mc:LocationType" minOccurs="0" />
        </all>
    </complexType>

    <complexType name="LocationType">
        <all>
            <!-- Name of the Pipeline/Branch/Route node where error occured -->
            <element name="node" type="string" minOccurs="0" />

            <!-- Name of the Pipeline where error occured (if applicable) -->
            <element name="pipeline" type="string" minOccurs="0" />

            <!-- Name of the Stage where error occured (if applicable) -->
            <element name="stage" type="string" minOccurs="0" />

            <!-- Indicates if error occured from inside an error handler -->
            <element name="error-handler" type="boolean" minOccurs="0" />
        </all>
    </complexType>
    <!-- Encapsulates any stack-traces that may be added to a fault <details> -->
    <element name="stack-trace" type="string"/>
</schema>

User’s Guide

Message Context

The Message Context Model

Predefined Context Variables

Message-Related Variables

Header Variable

Body Variable

Attachments Variable

Binary Content in the body and attachments Variables

Java Content in the body Variable

Streaming body Content

Best Practices for Using Content Streaming

Inbound and Outbound Variables

Sub-Elements of the inbound and outbound Variables

service

transport

security

Related Topics

Operation Variable

Fault Variable

Initializing Context Variables

Initializing the attachments Context Variable

Initializing the header and body Context Variables

SOAP Services

XML Services (Non SOAP)

Messaging Services

Performing Operations on Context Variables

$body

$header

Extract the WS-Addressing Header—From

Extract the Payload From a Non-SOAP Message

Extract the user-header From an Outbound Response Message

Assign Variable Contents for Request Parameter in a Service Callout

Related Topics

Constructing Messages to Dispatch

SOAP Services

XML Services (Non SOAP)

Messaging Services

About Sending Binary Content in Email Messages

Related Topics

Message Context Schema

Message Context.xsd

Related Topics