Console Online Help
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
This section describes the BEA AquaLogic Service Bus message context model and specifically the predefined context variables that are used in the AquaLogic Service Bus message flow. It includes the following topics:
The BEA AquaLogic Service Bus message context is a set of properties that holds message context as well as information about messages as they are routed through AquaLogic Service Bus. These properties are referred to as context variables—for example, service endpoints are represented by predefined context variables. AquaLogic Service Bus 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.
The following table describes the predefined context variables. The predefined context variables can be grouped into the following types: the message-related variables, the inbound and outbound variables, the operation variable, the fault variable.
For information about the element types in the message context variables, see Message Context Schema.
Table A-1 Predefined Context Variables in AquaLogic Service Bus
Context Variable1 | ||
---|---|---|
Contains the SOAP headers for SOAP messages (for SOAP messages that contain a SOAP header). The |
||
Contains the information about the proxy service that received a message. |
||
Contains the information about the target service to which a message is to be sent. |
||
Identifies the operation that is being invoked on a proxy service. |
||
Contains information about errors that have occurred during the processing of a message. |
Together, the message-related variables header, body and attachments represent the canonical format of a message as it flows through AquaLogic Service Bus. 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 AquaLogic Service Bus. That determination is dependent upon whether the target endpoint is expecting a SOAP or a non-SOAP message:
header
and body
variables are combined in a SOAP envelope to create the message.body
variable constitutes the entire message. attachments
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 case of non-SOAP messages or SOAP messages with no headers, the <SOAP:Header>
element is empty, and has no sub-elements.
The body
variable represents the core message payload and always points to a <SOAP: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:
body
variable. <SOAP:Body>
element.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.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 the following table.
Table A-2 Sub-Elements of the Attachments Variable
Description1 |
|
---|---|
A globally-unique reference that identifies the attachment.The type is |
|
Specifies the media type and sub-type of the attachment. The type is |
|
Specifies how the attachment is encoded. The type is |
|
A locally-unique URI-based reference that identifies the attachment. The type is |
|
Specifies how the attachment should be handled by the recipient. The type is |
|
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-Typ
e 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.
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, AquaLogic 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 AquaLogic Service Bus 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:
where the ref attribute contains a URI or URN that uniquely identifies the binary content. This XML can be manipulated in a AquaLogic Service Bus 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.
body
variable can be copied to an attachment by copying the reference XML to the body
sub-element of an attachment element. When messages are dispatched from AquaLogic 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 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—AquaLogic Service Bus does not de-reference the URI, and the content is not substituted into an outgoing message.
The inbound
and outbound
context variables contain information about the inbound and outbound endpoints. The inbound
variable ($inbound
) contains information about the proxy service that received the request message; the outbound
variable ($outbound
) 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
using the request actions you configure in routing nodes and publish actions (also in the response actions in routing nodes).
Warning: Any modifications you make to $outbound
in the message flow outside of the request or response actions in routing nodes and publish actions are ignored. In other words, those modifications are overwritten when $outbound
is initialized in the routing nodes and publish actions.
You cannot modify the outbound variable in WS-Callout actions.
The inbound
and outbound
variables have the following characteristics:
inbound
and outbound
context variables are instances of the endpoint
element as described in Message Context Schema.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.
service
, transport
and security
sub-elements described in the following section.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:
The service
element is read-only for both inbound
and outbound
. Sub-elements include providerName
and operation
.
Table A-3 Sub-Elements of the service Element
Sub-Elements1 |
|
Specifies the name of the proxy service provider. Initialized based on the configuration of publish and routing actions. |
|
Used in the Initialized based on the inbound and outbound. Note: This element is used for the |
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 the following table.
Table A-4 Sub-Elements of the transport Element
Sub-Elements1 | |
---|---|
This element is read-only2 in the |
Specifies transport-specific metadata about the request (including transport headers). The value for this element is defined by the transport protocol (specifically, the To learn about the transport-specific types for this element, see the appropriate transport schema, which is available in a JAR file at the following location in your AquaLogic Service Bus installation:
where |
This element is read-only in the |
Specifies transport-specific metadata about the response (including transport headers). The value for this element is defined by the transport protocol (specifically, the To learn about the transport-specific types for this element, see the appropriate transport schema, which is available in a JAR file at the following location in your AquaLogic Service Bus installation:
where The URI element is initialized as follows:
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: |
Specifies whether the communication style is Initialized on the |
|
This element is read only for You can modify it for the |
Specifies the quality of service expected when sending or receiving a message. Valid values include
The qualityOfService element is initialized on the inbound and outbound variables as follows:
|
Specifies the number of retries to attempt when sending a message from AquaLogic Service Bus. If retryCount is set, the setting overrides any retry count value configured in the target service configuration. |
|
Specifies the interval, in seconds, to wait before attempting to resend a message from AquaLogic Service Bus. If retryInterval is set, the setting overrides any retry interval value configured in the target service configuration. |
The sub-elements of the security
element are described in the following table.
Table A-5 Sub-Elements of the security Element
Sub-Elements1 | |
---|---|
Specifies authenticated transport-level user information. Includes the Initialized by AquaLogic Service Bus. The inbound transportClient element is read-only. |
|
( |
Specifies authenticated message-level user information. Includes the Initialized by AquaLogic Service Bus. The inbound messageLevelClient element is read-only. |
A flag that you set to specify if Web Services Security (WSS) should be applied to an outbound message. This property is used to support WSS pass-through cases in which an unsecured proxy service is used to route messages to a secured service. Because the proxy service is unsecured, an incoming secured message remains signed/encrypted in the AquaLogic Service Bus message flow and must therefore not be re-signed or re-encrypted on outbound dispatch. Initialized by AquaLogic Service Bus. You can modify the value of the doOutboundWss element in a routing or publish outbound request action. |
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 http://download.oracle.com/docs/cd/E13222_01/wls/docs90/jms/fund.html#jms_features
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.
AquaLogic Service Bus 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.
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 the following table.
Table A-6 Sub-Elements of the Fault Variable
Description1 . . . |
|
---|---|
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: |
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 AquaLogic Service Bus correspond to system error codes and are prefixed with the BEA
string.
AquaLogic Service Bus 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:
This yields three generic codes as follows:
Additionally, AquaLogic Service Bus defines the following specific proxy error:
BEA-382030—Indicates a message parse error (for example, a SOAP proxy service received a non-SOAP message).
In future releases of AquaLogic Service Bus, additional specific errors may be introduced for each of the three generic categories.
The message context and its variables are initialized in the binding layer when a message is received and before message processing begins. The following table summarizes how context variables are initialized.
Table A-7 Initializing Context Variables
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 For information about the initialization of sub-elements of |
|
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 |
|
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: The |
|
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
:
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.
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 messagebody
—initialized with the <soap:Body>
element from the SOAP messageThe 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 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. <soap:Body>
element. <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.
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 following examples show the use of XQuery to examine and manipulate context variables.
Listing A-1 Extract the WS-Addressing Header—From
$header/wsa:From
Listing A-2 Extract the Payload From a Non-SOAP Message
$body/*
Listing A-3 Extract the user-header From an Outbound Response Message
$outbound/ctx:transport/ctx:response/tp:user-header[@name='myheader']/@value
For more information about handling context variables using the XQuery and XPath editors in the AquaLogic Service Bus Console, see the following topics:
When AquaLogic Service Bus 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:
An outgoing SOAP message is constructed by wrapping the contents of the header
and body
variables inside a <soap:Envelope>
element. 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 AquaLogic Service Bus is constructed from the contents of the body
variable:
body
variable is empty, then a zero-size message is sent. 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. body
variable is text and not XML, an error is thrown. 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. 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.
The messages to messaging services from AquaLogic Service Bus are constructed from the contents of the body
variable.
body
variable is empty, then a zero-size message is sent, regardless of the outgoing message type. body
variable are interpreted as text and sent. In this way, it is possible for AquaLogic 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.body
variable must contain a piece of reference XML—the reference URI references the binary data stored in the AquaLogic 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 proxy service specifies the reference URI, the referenced data is not stored in the AquaLogic 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 binary messages, AquaLogic Service Bus 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:
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:
content-type
(the default is binary for MFL message type) as text/plain
in $outbound
To learn more about how binary content is handled, see Binary Content in the body and attachments Variables.
For the purposes of instruction, the following questions are asked and answered considering an example scenario in which AquaLogic Service Bus receives a SOAP message with attachments (3 parts: SOAP, text, binary).
The nature of the message written to the file system depends on the type of your outbound service:
<soap:Envelope>
) as the root part. (For more information, see SOAP Services.)$body
as the root part. (For more information, see XML Services (Non SOAP) and Messaging Services.)For complete information about configuring actions in the AquaLogic Service Bus Console, see Adding an Action.
You need not set any transport headers. The Content-Type
is set automatically according to the service type. For more information, see Initializing the attachments Context Variable.
No. Any changes you make to an outbound message in a publish action only affect the published message. In other words, the changes you make in the publish action are rolled back before the message flow proceeds to any nodes that follow the route node in your message flow. For more information about configuring route nodes, see Adding an Action.
Listing A-4 shows the message context schema (MessageContext.xsd
), which specifies the types for the message context variables.
When working with the message context variables, you need to reference MessageContext.xsd
and the transport-specific schemas, which are available in a JAR file at the following location in your AquaLogic Service Bus installation:
BEA_HOME
\weblogic90\servicebus\lib\sb-schemas.jar
where BEA_HOME
represents the directory in which you installed AquaLogic Service Bus. sb-schemas.jar
includes the following context-related schemas:
EmailTransport.xsd
)FileTransport.xsd
)FTPTransport.xsd
)HttpTransport.xsd
)HttpsTransport.xsd
)MessageContext.xsd
)JmsTransport.xsd
)ServiceBusReference.xsd
)TransportCommon.xsd
)Listing A-4 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">
<all>
<!-- User name associated with this tranport- or message-level subject -->
<element name="username" type="string"/>
</all>
</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>
</schema>
Inbound and Outbound Variables
Performing Operations on Context Variables
![]() |
![]() |
![]() |