|
|
|
|
|
|
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:
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:
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:
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:
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:
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.
The following table describes how each Quality of Service setting affects message tracking and delivery acknowledgments.
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 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.
// 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);
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. In these settings:
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
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 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:
When sending an XOCP business message with either synchronous or deferred synchronous delivery, you need to set the following values:
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:
To send a business message synchronously, an XOCP application invokes the following methods on the XOCPMessage instance:
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:
To send a business message asynchronously, an XOCP application invokes the following methods on the XOCPMessage instance:
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.
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:
Both methods return a DeliveryStatus object, an instance of the com.bea.b2b.protocol.messaging.DeliveryStatus class that provides the following information:
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.
|
|
|
|
|
|
Copyright © 2002 BEA Systems, Inc. All rights reserved.
|