bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming Messaging Applications

Sending XOCP Business Messages

The following sections describe how an XOCP application sends XOCP business messages to one or more trading partners in a conversation:

- Step 1: Create the Business Message

- Step 2: Specify the Recipients of the Business Message (Optional)

- Step 3: Specify the Quality of Service for Message Delivery

- Step 4: Send the XOCP Business Message

- Step 5: Check the Delivery Status of the Business Message

To send an XOCP business message, an XOCP application constructs a business document, creates a business message, specifies message routing criteria and Quality of Service delivery options, and sends the business message to the intermediary for processing. The XOCP application can also check the delivery status of the business message, including whether it was successfully delivered. For an introduction to XOCP business messages, see XOCP Business Messages and Message Envelopes.

Step 1: Create the Business Message

To create a business message, an XOCP application first creates a message payload, which consists of any business documents and attachments to be sent.

The creation of a payload involves three steps:

1. Importing the Required Packages

2. Creating Payload Parts

3. Creating the XOCP Business Message and Adding Payload Parts

This section describes these three steps. For an introduction to the components of a business message, see XOCP Business Messages and Message Envelopes.

Importing the Required Packages

To create a business message, an XOCP application imports the necessary packages, as shown in the following listing.

Listing 3-1 Importing Packages for Business Message Creation

>     class java.io.FileInputStream;
>     import org.apache.xerces.dom.*;
>     import com.bea.b2b.protocol.xocp.application.*;
>     import com.bea.b2b.protocol.xocp.messaging.*;
>     import com.bea.b2b.protocol.messaging.Attachment;
>     import com.bea.eci.logging.*;

Creating Payload Parts

An XOCP application next creates a message payload, which includes business documents and/or attachments.

Creating XML Documents

A business message can contain one or more business documents. A business document is the XML-based payload part of a business message. A business document is an instance of the com.bea.b2b.protocol.messaging.BusinessDocument class.

A BusinessDocument object contains an XML document, which is an instance of the org.w3c.dom.Document class in the org.w3c.dom package published by the World Wide Web Consortium (www.w3.org). An XOCP application can also use a third-party implementation of that package, such as the org.apache.xerces.dom package provided by The Apache XML Project (www.apache.org), which is used by the Messaging API sample to create and process XML documents.

Note: The document type parameters specified in each XML document must map to a part content type of message definition associated with the conversation definition in the repository.

The following code from the MdmTp1Servlet of the Messaging API application creates a request in the form of an XML document.

Listing 3-2 Creating an XML Document

>     // Create a request document
>     DOMImplementationImpl domi = new DOMImplementationImpl();
>     DocumentType dType =
>             domi.createDocumentType("request", null, "request.dtd");
>     org.w3c.dom.Document rq1 = new DocumentImpl(dType);
>     Element root1 = rq1.createElement("request");
>     String sendStr1 = "FIRST MESSAGE"; // the actual string data to be
>                                        // processed by the other partner
>     root1.appendChild(rq1.createTextNode(sendStr1));
>     rq1.appendChild(root1);

After creating an XML document, an XOCP application creates a BusinessDocument object, passing the XML document (payload[0]) as a parameter to the constructor, as shown in the following listing.

Listing 3-3 Creating a BusinessDocument

>     BusinessDocument bd = (BusinessDocument)payload[0];

Creating Attachments

A business message can contain one or more attachments. An attachment is a nonXML-based payload part of a business message that contains binary content. An attachment is an instance of the com.bea.b2b.protocol.messaging.Attachment class. For more information, see the BEA WebLogic Integration Javadoc.

The following example listing shows how to create an attachment.

Listing 3-4 Creating an Attachment

>     FileInputStream fis = new FileInputStream("somefile");
>     Attachment att = new Attachment (fis);

Creating the XOCP Business Message and Adding Payload Parts

After creating a message payload, an XOCP application creates an XOCP business message and adds the payload parts to it. The com.bea.b2b.protocol.xocp.messaging.XOCPMessage class represents an XOCP business message. For more information, see the BEA WebLogic Integration Javadoc.

To construct the business message, an XOCP application:

1. Creates an instance of the XOCPMessage class.

2. Adds the payload parts to the business message by calling either of the following methods on the XOCPMessage message object:

   - addPayLoadPart, which adds a single business document or attachment to the business message

   - addPayLoadParts, which adds multiple business documents or attachments to the business message

In the following listing an XOCP business message is created and a payload part is added to it.

Listing 3-5 Creating a Business Message and Adding Payload Parts

>     XOCPMessage smsg1 = new XOCPMessage("");
>     smsg1.addPayloadPart(new BusinessDocument(rq1));

Note: The XOCP application clones the XOCPMessage content (except its payload parts) before sending it to the intermediary. Therefore, a payload part must not be changed after the application invokes the send or sendAndWait method on the XOCPMessage.

Step 2: Specify the Recipients of the Business Message (Optional)

After creating a business message, an XOCP application may specify the trading partner to which the message will be sent. An XOCP application might send the business message to a specific trading partner (a point-to-point exchange), such as when it replies to a request received from a conversation initiator. Alternatively, an XOCP application might send a business message to a set of trading partners (via multicasting) when certain business criteria (represented by XOCP XPath expressions) are met. For example, an application might send a message via multicasting when a buyer sends a bid request to multiple sellers of a particular product.

Either way, the set of eligible trading partners is limited to those who are subscribed to the appropriate role in the conversation definition. In addition, router and filter expressions defined in the intermediary repository may also affect message delivery to particular trading partners. For more information, see Advanced Configuration Tasks in Administering B2B Integration.

Specifying a Particular Trading Partner

If an XOCP business message is sent to a single, known trading partner, an XOCP application can call the setRecipient method on the XOCPMessage object, passing the trading partner name as the parameter. The specified trading partner must be defined in the intermediary repository.

The following example listing shows how a trading partner named ChipMaker is specified as the recipient of a business message.

Listing 3-6 Specifying a Single Trading Partner

>     String tradingPartnerName = "ChipMaker";
>     XOCPMessage msg = new XOCPMessage();
>     msg.setRecipient(tradingPartnerName);

Using setRecipient for a business message expedites message delivery because the intermediary does not perform the usual router processing, such as the evaluation of trading partner or intermediary XPath expressions. However, the business message is still subject to applicable filtering in the intermediary. For more information, see Advanced Configuration Tasks in Administering B2B Integration.

Using XPath Expressions to Specify Message Recipient Criteria

An XOCP application can use XPath expressions to specify the criteria for a set of trading partners that are to receive a business message. XPath expressions are used to address parts of an XML document. For more information, see Advanced Configuration Tasks in Administering B2B Integration.

An XPath expression should be specific to the document format of the intermediary repository and should define a node-specific set of trading-partner elements. The XPath expression selects recipient trading partners based on the following attributes, which are defined in the intermediary repository:

- Standard attributes, such as the trading partner name or a postal code

- Extended properties: custom attributes, elements, and text defined by the administrator of the intermediary

The XPath expression is passed, as part of the message header in the business message, from the XOCP application to the intermediary. The intermediary uses this XPath expression, along with other XPath expressions defined in the intermediary repository, to determine the set of message recipients for the business message.

If applicable trading partner and intermediary XPath expressions are defined in the intermediary repository, the B2B engine hosting the intermediary evaluates these expressions after it receives the business message. Depending on how they are configured, these XPath expressions might override or append the XOCP XPath expression that the XOCP application specifies. For more information, see Advanced Configuration Tasks in Administering B2B Integration.

To specify an XOCP XPath expression for an XOCP business message, the XOCP application calls the setExpression method on the XOCPMessage object, passing the XPath expression as the parameter.

Note: Apache Xalan v 1.0.1 supports single quotes, but not double quotes, to delimit string literals.

Before the business message is delivered, it undergoes applicable router and filter processing in the intermediary.

Specifying Standard Trading Partner Attributes

The following listing shows an XOCP XPath expression that selects the trading partner with the specified name.

Listing 3-7 XOCP XPath Expression Specifying a Trading Partner Name

>     smsg1.setExpression("//trading-partner[@name=\'Partner2\']");

The following listing shows an XOCP XPath expression that selects the trading partner with an address that contains the string San.

Listing 3-8 XOCP XPath Expression Specifying a Trading Partner Address

>     msg.setExpression("//trading-partner[contains(address,\'San\')]");

Specifying an XOCP XPath Expression Using Extended Properties

Extended properties are user-defined elements, attributes, and text that can be associated with trading partners in the repository in the intermediary. These properties provide application extensions to the standard predefined attributes in the repository. The extended property sets are modeled in the repository such that they can be retrieved as subtrees within an XML document. Extended properties are configured on the Trading Partners tab in the WebLogic Integration B2B Console. For more information, see "Using Advanced Trading Partner Configuration Options" in Configuring B2B Integration in Online Help for the WebLogic Integration B2B Console.

XOCP XPath expressions can refer to these extended properties to assist with business message routing. For example, suppose the administrator for the intermediary adds an extended property called Maximum Order Quantity so that sellers can indicate, in the intermediary repository, the largest quantity that they can accommodate. With this property defined, a buyer with a large order can specify an XOCP XPath expression that sends the business message only to sellers that are qualified to process the order.

The following code listing shows an XML document generated from the repository with an extended property set for a given seller.

Listing 3-9 Extended Property Set in XML Document Generated from the Repository

>     <hub context="message-router">
>     . . .
>     <trading-partner name="ABC Seller"
>     email="orderprocessing@somedomain.com"
>     phone="999-999-9999">
>     <address>123 Main St., San Jose, CA 95131</address>
>     <extended-property-set name="Capacity">
>     	<max-order-quantity>1000</max-order-quantity>
>     </extended-property-set>
>     </trading-partner>
>     . . .
>     </hub>

The following listing shows an XOCP XPath expression that selects trading partners that can accommodate orders larger than 500 units.

Listing 3-10 XOCP XPath Expression Specifying an Order Size

>     msg.setExpression("//trading-partner[extended-property-set/(@max-order-qty > \'500\')]")

Because the seller can accommodate orders of up to 1000 units, it is selected as a recipient of this business message.

Step 3: Specify the Quality of Service for Message Delivery

The B2B engine messaging service allows XOCP applications to define the Quality of Service (QoS), or level of reliability, to enforce when delivering a business message to recipient trading partners. Quality of Service settings are stored in the message header of the business message. The messaging service supports the reliable delivery of messages in the event of network-link or node failures. The messaging service provides other capabilities to support reliable messaging, such as message logging and tracking, correlation of messages, delivery retry attempts, message timeouts, and choice of message-delivery methods.

Automatic Quality of Service Features

The B2B engine messaging service provides certain automatic Quality of Service features that do not require input from XOCP applications:

- The B2B engine prevents duplicate message delivery.

- The B2B engine affixes a timestamp to every business message when it arrives at an intermediary or an XOCP application node. Timestamps can be helpful for taking performance measurements and with debugging applications.

QualityOfService Class

The com.bea.b2b.protocol.xocp.messaging.QualityOfService class represents Quality of Service settings for business messages. The QualityOfService class defines the level of reliability required from the B2B engine messaging service when it delivers a specific message. It also identifies, to the B2B engine messaging service, the XOCP application's expectation of how the business message will be delivered.

An XOCP application creates an instance of this class and calls methods on this instance to specify various Quality of Service settings. It then calls the setQoS method on the message instance, passing the QualityOfService object as a parameter, to associate the settings with the message. If an XOCP application does not specify Quality of Service settings, the B2B engine messaging service uses default values where applicable.

Quality of Service Settings, Options, and Default Values

The following table describes the available Quality of Service settings, options, and default values.

Table 3-1 Quality of Service Settings, Options, and Default Values

QoS Setting / Description | Options | Default Value(s)
--- | --- | ---
CONFIRMED_DELIVERY_TO_APPLICATION Provides confirmation of application delivery up to the receiving application. Provides complete status of delivery to each destination, including receipt timestamp, list of router-selected trading partners, final list of recipient trading partners, and so on. Provides complete message tracking information (of all potential locations) for the intermediary administrator and the administrator of the trading partner sending the message. | Not Applicable | Not Applicable
CONFIRMED_DELIVERY_TO_DESTINATION(S) Provides complete status of delivery to each destination, including receipt timestamp, list of router-selected trading partners, final list of recipient trading partners, and so on. Provides complete message tracking information (of all potential locations) for the intermediary administrator and the administrator of the trading partner sending the message. | Not applicable | Not applicable
CONFIRMED_ROUTING Provides information from the XOCP router on the intermediary about the trading partners selected to receive the business message. Provides message tracking for the administrator of the trading partner sending the messages (until the business message reaches the intermediary's XOCP router). | Not applicable | Not applicable
CONFIRMED_DELIVERY_TO_HUB (Default) Verifies that the message reached the intermediary. No message tracking for the administrator of the trading partner sending the message. | Not applicable | Not applicable
TIMEOUT | Timeout, in milliseconds, after send | Ignored
RETRY_ATTEMPTS | 0-n | As configured for the intermediary
CORRELATION_ID | Application-defined field | Ignored

The following table describes how each Quality of Service setting affects message tracking and delivery acknowledgments.

Table 3-2 How QoS Settings Affect Message Tracking and Acknowledgment

Quality of Service Setting | Message Tracking (Y/N)? | Acknowledgment (Y/N)?
--- | --- | ---
CONFIRMED_DELIVERY_TO_APPLICATIONS | Y | Y
CONFIRMED_DELIVERY_TO_DESINATION(S) | Y | Y
CONFIRMED_DELIVERY_TO_ROUTER | Y | N
CONFIRMED_DELIVERY_TO_HUB | N | N

If the CONFIRMED_DELIVERY_TO_DESINATION(S)setting is used, then complete message tracking is available and acknowledgments are used to make sure that the message is delivered reliably to its destination(s).

If the CONFIRMED_DELIVERY_TO_HUB setting is used, then no message tracking is available and no acknowledgments are sent from recipient trading partners.

Code Example

The following example listing shows how to set the Quality of Service for a business message.

Listing 3-11 Setting the Quality of Service for a Business Message

>     // Relevant imports
>     import com.bea.b2b.protocol.xocp.messaging.XOCPMessage;
>     import com.bea.b2b.protocol.xocp.messaging.QualityOfService;

>     XOCPMessage msg = . . .
>     // Create QoS object
>     QualityOfService qos = new QualityOfService();
>     // Specify confirmed delivery to destination(s)
>     qos.setConfirmedDeliveryToDestination(true);
>     msg.setQoS(qos);

Setting the Message Delivery Confirmation Level

To specify the level of message delivery confirmation, an XOCP application calls one of the following methods on the QualityOfService instance, passing the Boolean true parameter to enable the desired option.

Table 3-3 Message Delivery Confirmation Levels

Durability Level | Description
--- | ---
setConfirmedDeliveryToDestination | Specifies whether to confirm message delivery up to its destination (true) or only up to the intermediary (false).
setConfirmedDeliveryToHub | Specifies whether to confirm message delivery up to the intermediary (true) or not (false).
setConfirmedDeliveryToRouter | Specifies whether to confirm message delivery up to the XOCP router in the intermediary (true) or only up to the intermediary (false).
setConfirmedDeliveryToApplication | Sets the Quality of Service for this business message, specifying whether to confirm message delivery up to the target application (true) or only up to the intermediary (false).

The following example listing shows how to set the message confirmation level up to its destination.

Listing 3-12 Setting the Message Delivery Confirmation Level

qos.setConfirmedDeliveryToDestination(true);

For more information about confirming message delivery, see Step 5: Check the Delivery Status of the Business Message.

Setting the Message Timeout

If specified, the message timeout determines how long a sender waits for acknowledgments. If a business message expires (times out), the recipient does not process it, and all other processing of it, including acknowledgment processing and delivery retries, is abandoned.

Timeout Algorithm

The B2B engine does not synchronize the different clocks used by its components, which can reside in different machines at different locations. Instead, the B2B engine uses a relative time algorithm.

Based on this algorithm, the amount of time remaining before the timeout of a business message (relative to the absolute time at which the component finished processing the business message) is specified in the business message when that message is sent to another component.

In the receiving component, the timeout calculations are based on the amount of time remaining to process the message, expressed through both an absolute time (indicating the arrival of the message) and a relative time (embedded in the message itself). This algorithm at least ensures that the actual message timeout in the system always occurs after the original timeout specified by the application.

>     Message Timeout on the Hub = Message timeout specified by the XOCP application when sending a message

>     Message Timeout on the Sending XOCP Application = Message Timeout on the Hub + N x Delta

In these settings:

- N = A predefined number in the system, such as 10

- Delta = Estimated amount of time required for a message to travel, round-trip, between the sending trading partner and the intermediary

Setting the Number of Delivery Retry Attempts

If an attempt to deliver a business message fails due to intermittent network failures, the B2B engine messaging service attempts to retry sending the business message repeatedly until one of the following occurs:

- The business message is delivered (that is, delivery succeeds).

- The number of retry attempts is exceeded.

- The message times out.

- The conversation in which the business message is sent either terminates or times out.

The default values for message timeouts and retry intervals are defined in the repository in the intermediary and are retrieved by an XOCP application when the XOCP application session is created. The B2B engine messaging service waits for the configured interval before attempting to resend a business message.

To override the default retry attempt limit, an XOCP application invokes the setTimeout method on the QualityOfService instance, passing the timeout value (number of milliseconds) as a parameter, as shown in the following listing.

Listing 3-13 Specifying the Message Timeout

qos.setTimeout(10000);

Setting the Correlation ID for a Business Message

An XOCP application can specify a unique correlation ID for a business message so that it can correlate business messages (such as replies to a request) received from trading partners in response to a previously sent message (such as a request). The correlation ID accompanies the business message to its destination. The recipient trading partner can use this value to unambiguously identify the reply message sent back to the originating trading partner.

To specify the correlation ID, an XOCP application invokes the setCorrelationId method on the QualityOfService instance, passing a string representing the correlation ID as a parameter, as shown in the following listing.

Listing 3-14 Specifying the Correlation ID for a Business Message

qos.setCorrelationId("ABC123");

Step 4: Send the XOCP Business Message

After specifying the recipients of a business message and the Quality of Service, an XOCP application sends the business message in one of the following ways:

- Synchronous message delivery

- Deferred synchronous message delivery

When sending an XOCP business message with either synchronous or deferred synchronous delivery, you need to set the following values:

- The collaboration agreement ID associated with that message

- The conversation

Synchronous Message Delivery

With synchronous message delivery, the application waits until the message is delivered to the destinations. The B2B engine messaging service returns control to the application once the outcome of the activity of sending the message is known. The application waits until one of the following events occurs:

- Acknowledgments are received from all potential destinations.

- The message times out.

- The conversation in which the message was sent terminates.

To send a business message synchronously, an XOCP application invokes the following methods on the XOCPMessage instance:

- The setCAId method, which sets the collaboration agreement ID

- The setConversation method, which sets the conversation in which to send the business message

- The sendAndWait method, which specifies the amount of time to wait (in milliseconds) before timing out. If you specify zero (0), the XOCP application waits until the business message reaches its respective destinations.

The following example shows how to send an XOCP business message using synchronous message delivery.

Listing 3-15 Sending a Message Using Synchronous Message Delivery

>     smsg1.setCAId(caId);
>     smsg1.setConversation(c);
>     MessageToken token = msg.sendAndWait(0);

Deferred Synchronous Message Delivery

With deferred synchronous message delivery, the B2B engine messaging service returns control to the XOCP application immediately after a message is sent, and returns a message token that the XOCP application can use to check the status of message delivery. Once a message token is accessed, the application waits for a specified time or until any of the following events occurs:

- Acknowledgments are received from all potential destinations.

- The message times out.

- The conversation in which the message was sent either terminates or times out.

To send a business message asynchronously, an XOCP application invokes the following methods on the XOCPMessage instance:

- The setCAId method, which sets the collaboration agreement ID

- The setConversation method, which specifies the conversation in which to send the business message

- The send method, which sends the message

The XOCP application continues executing business logic, and then checks the status by calling the waitForACK method on the MessageToken instance, as shown in the following listing.

Listing 3-16 Sending a Message Using Deferred Synchronous Message Delivery

>     smsg1.setCAId(caId);
>     smsg1.setConversation(c);
>     token = msg.send();
>     ...
>     token.waitForACK();

The waitForAck method blocks until the status of the business message is available (if no timeout is specified) or until the specified timeout (in milliseconds) is exceeded.

Step 5: Check the Delivery Status of the Business Message

Both the send and sendAndWait methods invoked on the XOCPMessage instance return a message token that an XOCP application can query to check the delivery status of the associated business message.

Message Tokens

A message token is an instance of the com.bea.b2b.protocol.xocp.messaging.XOCPMessageToken class. A message token has the following attributes.

Table 3-4 Message Token Information

Attribute | Description
--- | ---
Message ID | Unique ID of the business message.
Exception | If applicable, any exception that occurred before the business message left the sending XOCP application. An exception is usually returned when the message is sent; but for deferred synchronous message delivery, the business message might be kept in an internal send queue temporarily before being delivered to the intermediary.
Elapsed Time | Amount of time taken to deliver the business message to all destinations. This information is available only after acknowledgments have been received from all message destinations. Availability is subject to the specified Quality of Service delivery option.
Delivery Status | Delivery status from recipient destinations. This information depends on the availability of such information. Availability is subject to the specified Quality of Service delivery option.
Number of Recipients (Router) | Number of recipient trading partners after the business message has been processed by the XOCP router in the intermediary. Availability is subject to the specified Quality of Service delivery option.
Number of Recipients (Filter) | Number of recipient trading partners after the business message has been processed by the XOCP filter in the intermediary. Availability is subject to the specified Quality of Service delivery option.

If the business message is sent using the synchronous send delivery option, then the message token cannot be used to wait for acknowledgments. Instead, the send method returns immediately.

Delivery Status Tracking

When a business message reaches its destination (the receive queue of the destination trading partner node), a system message is returned to the sender (by the B2B engine messaging service) to acknowledge the message delivery if an acknowledgment is required by the Quality of Service setting.

An XOCP application can use either of the following methods to obtain the delivery status:

- getAllDeliveryStatus if the business message was sent to multiple recipients

- getDeliveryStatus if the business message was sent to a single recipient

Both methods return a DeliveryStatus object, an instance of the com.bea.b2b.protocol.messaging.DeliveryStatus class that provides the following information:

- Recipient (name of the recipient trading partner or message tracking location)

- Timestamp for the receipt of the business message

- Status code, valid values for which are shown in the following table

Table 3-5 Message Delivery Status Codes

Status Code | Description
--- | ---
SUCCESS | Business message was successfully delivered to the destination. No errors or exceptions occurred.
FAILURE | An error occurred during delivery of the business message to the destination.
RETRIES_EXHAUSTED | All delivery retry attempts were exhausted and the business message was discarded.
TIMEDOUT | Timeout occurred before message delivery and the business message was discarded.

Message Tracking Locations

The B2B engine messaging service provides tracking features that allow administrators to check the progress of a business message as it moves through various predefined locations en route to its destination. The B2B Console can display status information as a business message passes through these tracking points. Administrators can use message tracking information for debugging and identifying bottlenecks in applications.

Note: The availability of message tracking locations depends on the configuration of the WebLogic Integration system and the specified Quality of Service for a given business message, such as CONFIRMED_DELIVERY_TO_DESTINATION(S). (For a description of Quality of Service settings, see Table 3-1). For example, if the XOCP application and the intermediary are collocated on the same node, some locations are not available. Similarly, some tracking locations may not be available for synchronous message delivery.

Diagram of Message Tracking Locations

The following figure shows the message tracking locations in the B2B engine messaging service.

Figure 3-1 Message Tracking Locations

Description of Message Tracking Locations

The following message tracking locations are potentially visible in the B2B Console.

Table 3-6 Message Tracking Locations

Location | Description of Location | Activity Performed
--- | --- | ---
ENABLER_SEND_QUEUE | Send queue in the XOCP application session of the sending trading partner | Message is enqueued for sending.
HUB_RECEIVE_QUEUE | Receive queue for the sending trading partner in the intermediary | Message is enqueued in the receive queue of the sending trading partner in the intermediary.
HUB_ROUTER | XOCP router in the intermediary | Message has reached the XOCP router.
HUB_SEND_QUEUE | Send queue of the receiving trading partner in the intermediary | Message is enqueued for delivery in the target trading partner's queue in the intermediary.
ENABLER_RECEIVE_QUEUE | Receive queue in the XOCP application session of the receiving trading partner | Message is enqueued in the queue of the listener thread of the target trading partner's XOCP application session.