|
|
|
|
|
|
Sending XOCP Business Messages
The following sections describe how a c-enabler application sends XOCP business messages to one or more trading partners in a c-space:
To send an XOCP business message, a c-enabler application constructs a business document, creates the business message, specifies the message routing criteria and Quality of Service delivery options, and sends the business message to the c-hub for processing. The c-enabler 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, a c-enabler application first creates the message payload, which consists of any business documents and attachments that the business message will contain. 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, a c-enabler application imports the necessary packages, as shown in the following listing.
Listing 3-1 Importing Packages for Business Message Creation
import org.w3c.dom.*;
import org.apache.html.dom.*;
import org.apache.xml.serialize.*;
import org.apache.xerces.dom.*;
import com.bea.b2b.protocol.conversation.ConversationType;
Creating Payload Parts
A c-enabler application next creates the message payload, which can include business documents and 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). A c-enabler 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 the package used by the Verifier application to create and process XML documents.
Note: The specified document type parameters must map to a part content type of message definition associated with the conversation definition in the repository.
The following listing from the Partner1Servlet of the Verifier 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 rq = new DocumentImpl(dType);
Element root = rq.createElement("request");
// the actual string data to be processed by the other partner
String sendStr = "ABCDEFGHI";
root.appendChild(rq.createTextNode(sendStr));
rq.appendChild(root);
After creating the XML document, a c-enabler application creates a BusinessDocument object, passing the XML document (request) as a parameter to the constructor, as shown in the following listing.
Listing 3-3 Creating a BusinessDocument
BusinessDocument bdoc = new BusinessDocument(rq);
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 WebLogic Collaborate 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 the message payload, a c-enabler application creates the 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 WebLogic Collaborate Javadoc
.To construct the business message, a c-enabler application:
In the following listing an XOCP business message is created and payload parts are added to it.
Listing 3-5 Creating a Business Message and Adding Payload Parts
XOCPMessage smsg = new XOCPMessage("");
smsg.addPayloadPart(bdoc);
smsg.addPayloadPart(att);Note: The c-enabler application clones XOCPMessage content (except its payload parts) before sending it to the c-hub. Therefore, a payload part must not be changed after the application invokes the send or sendAndWait methods on the XOCPMessage.
Step 2: Specify the Recipients of the Business Message
After creating a business message, a c-enabler application optionally specifies the trading partner to which the message will be sent. A c-enabler 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, a c-enabler application might send a business message to a set of trading partners (via multicasting) when certain business criteria (represented by c-enabler XPath expressions) are met. For example, an application might sentd 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 constrained by those who are subscribed to the appropriate role in the conversation definition. In addition, router and filter expressions defined in the c-hub repository may also affect message delivery to particular trading partners. For more information, see Administering BEA WebLogic Collaborate.
Specifying a Particular Trading Partner
If an XOCP business message is being sent to a single, known trading partner, a c-enabler 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 c-hub repository.
The following example listing shows how a trading partner named ChipMaker is specified as the recipient of the 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 c-hub does not perform the usual router processing, such as the evaluation of trading partner or c-hub XPath expressions. However, the business message is still subject to applicable filtering in the c-hub. For more information, see Administering BEA WebLogic Collaborate.
Using C-Enabler XPath Expressions to Specify Message Recipient Criteria
A c-enabler application can use XPath expressions to specify the criteria for a set of trading partners that are to receive a business message. C-enabler XPath expressions are used to address parts of an XML document. For more information, see Administering BEA WebLogic Collaborate.
The XPath expression should be specific to the document format of the c-hub 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 c-hub repository:
The XPath expression is passed as part of the message header in the business message from the c-enabler to the c-hub. The c-hub uses this XPath expression, along with other XPath expressions defined in the c-hub repository, to determine the set of message recipients for the business message.
If applicable trading partner and c-hub XPath expressions are defined in the c-hub repository, the c-hub evaluates these expressions after it receives the business message. Depending on how they are configured, these XPath expressions might override or append the c-enabler XPath expression that the c-enabler application specifies. For more information, see Administering BEA WebLogic Collaborate.
To specify a c-enabler XPath expression for an XOCP business message, the c-enabler application calls the setExpression method on the XOCPMessage object, passing the XPath expression as the parameter.
Notes: Apache Xalan v 1.0.1 supports single quotes, but not double quotes, to delimit string literals.
Before the business message is delivered, it is still subject to applicable router and filter processing in the c-hub.
Specifying Standard Trading Partner Attributes
The following listing shows a c-enabler XPath expression that selects the trading partner with the specified name.
Listing 3-7 C-Enabler XPath Expression Specifying a Trading Partner Name
msg.setExpression("//trading-partner[@name=\'"+ tradingPartnerName+"\']")The following listing shows a c-enabler XPath expression that selects the trading partner whose address contains the string San.
Listing 3-8 C-Enabler XPath Expression Specifying a Trading Partner Name
msg.setExpression("//trading-partner[contains(address,\'San\')]");Specifying a C-Enabler XPath Expression Using Extended Properties
Extended properties are user-defined elements, attributes, and text that can be associated with trading partners in the c-hub repository. These properties provide application extensions to the standard predefined attributes in the repository. The extended property sets are modeled in the repository so that they can be retrieved as subtrees within an XML document. Extended properties are configured on the Trading Partners tab in the WebLogic Collaborate Administration Console. For more information, see Administering BEA WebLogic Collaborate.
C-enabler XPath expressions can refer to these extended properties to assist with business message routing. For example, suppose a c-hub administrator adds an extended property called Maximum Order Quantity so that sellers can indicate, in the c-hub repository, the largest quantity that they can accommodate. With this property defined, a buyer with a large order can specify a c-enabler XPath expression that sends the business message only to the sellers that can 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
<c-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>
</c-hub>
The following listing shows a c-enabler XPath expression that selects trading partners that can accommodate orders larger than 500 units.
Listing 3-10 C-Enabler 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, the seller is selected as a recipient of this business message.
Step 3: Specify the Quality of Service for Message Delivery
The WebLogic Collaborate messaging system allows c-enabler applications to define the Quality of Service (QoS), or level of reliability, to use when delivering a business message to recipient trading partners. The Quality of Service settings are stored in the message header of the business message. The messaging system supports the reliable delivery of messages in the event of network-link or node failures. The messaging system 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 WebLogic Collaborate messaging system provides certain automatic Quality of Service features that do not require input from c-enabler 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 quality of service required from the WebLogic Collaborate messaging system to deliver a specific message. It also identifies, to the WebLogic Collaborate messaging system, the c-enabler application's expectation for delivering the business message. A c-enabler application creates an instance of this class, calls methods on this instance to specify various Quality of Service settings, and then calls the setQoS method on the message instance, passing the QualityOfService object, to associate the settings with the message. If a c-enabler application does not specify Quality of Service settings, the WebLogic Collaborate messaging system uses the 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 the Quality of Service setting affects message tracking and delivery acknowledgments.
If the Confirmed Delivery to Destination(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.messaging.MessageToken;
import com.bea.b2b.protocol.messaging.DeliveryStatus;
import com.bea.b2b.protocol.messaging.BusinessDocument;
import com.bea.b2b.protocol.xocp.conversation.local.*;
import com.bea.b2b.protocol.xocp.messaging.*;
import com.bea.b2b.enabler.*;
import com.bea.b2b.enabler.xocp.*;
XOCPMessage msg =
// Create QoS object
QualityOfService qos = new QualityOfService();
// Specify message to be persisted
qos.setPersistent(true);
// 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, a c-enabler application calls one of the following methods on the QualityOfService instance, passing the Boolean true parameter to enable the desired option.
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 Message Durability
In the WebLogic Collaborate messaging system, message durability is a Quality of Service option that determines whether a durable message store is used in order to guarantee delivery of messages in case of node failures.
Message Durability Options
A c-enabler application has two message durability options: non-persistent (the default) and persistent, as described in the following table.
Message and Conversation Durability
A c-enabler application can specify message durability on a per-message basis. In addition, message durability can be defined on a per-conversation basis in the c-hub repository.
How business messages are persisted on a per-message or a per-conversation basis depends on a combination of whether persistence is enabled or disabled in the c-hub, the conversation, and the message, as shown in the following table.
A business message is considered persistent if persistence (recovery) is enabled in the c-hub, if the conversation in which the message is propagated is persistent, and if the message QoS indicates persistence. Even if persistence is enabled for conversations or messages, if persistence is not enabled in the c-hub, then no conversations or messages are stored to a reliable data store.
Specifying Message Persistence
To enable message persistence, a c-enabler application calls the setPersistent method on the QualityOfService instance, passing the Boolean true parameter, as shown in the following listing.
Listing 3-13 Specifying Message Persistence
qos.setPersistent(true);
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 receiver of the business message does not process it, and all other processing of the business message, including acknowledgment processing and delivery retries, is abandoned.
Timeout Algorithm
WebLogic Collaborate does not synchronize the clocks used by its different components, which can reside in different machines at different locations. Instead, WebLogic Collaborate uses a relative time algorithm.
Based on this algorithm, the time left before the timeout of a business message (relative to the absolute time of the component processing the business message) is included in the business message when the business message is sent to the other component.
In the receiving component, the timeout calculations are based on an absolute time (at the arrival of the business message) and a relative time (embedded in the incoming message) left to process the message. 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 C-Hub = Message timeout specified by the c-enabler application when sending a message
Message Timeout on the Sending C-Enabler = Message Timeout on the C-Hub + N x Delta
In these settings:
Setting the Number of Delivery Retry Attempts
If an attempt to deliver a business message fails due to intermittent network failures, the WebLogic Collaborate messaging system 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 c-hub repository and are retrieved by a c-enabler when the c-enabler session is created. The WebLogic Collaborate messaging system waits for the configured interval before attempting to resend a business message.
To override the default retry attempt limit, a c-enabler application calls 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-14 Specifying the Message Timeout
qos.setTimeout(10000);
Setting the Correlation ID for a Business Message
A c-enabler application can specify a unique correlation ID for a business message so that it can correlate received business messages (such as replies to a request) from trading partners to a previously sent message (such as a request). The correlation ID accompanies the business message to its destination. The c-enabler application of 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, a c-enabler application calls 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-15 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, a c-enabler application sends the business message in one of the following ways:
Synchronous Message Delivery
With synchronous message delivery, the application waits until the sent message is delivered to the destination(s). The WebLogic Collaborate messaging system returns control to the application once the outcome of the activity of sending the message is known. The application waits until any of the following events occurs:
To send a business message synchronously, a c-enabler application calls the sendAndWait method on the XOCPMessage instance, passing the amount of time to wait (in milliseconds) as a parameter. If zero (0) is specified, the c-enabler application waits until the business message reaches its destination(s), as shown in the following listing.
Listing 3-16 Sending a Message Using Synchronous Message Delivery
MessageToken token = msg.sendAndWait(0);
Deferred Synchronous Message Delivery
With deferred synchronous message delivery, the WebLogic Collaborate messaging system returns control to the c-enabler application immediately after a message is sent, and returns a message token that the c-enabler 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 with deferred synchronous message delivery, a c-enabler application calls the send method on the XOCPMessage instance, 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-17 Sending a Message Using Deferred Synchronous Message Delivery
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 on the XOCPMessage instance return a message token that a c-enabler 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 was sent using the synchronous send delivery option, then the message token cannot be used to wait for acknowledgments. If used, the method returns immediately.
Delivery Status Tracking
In the WebLogic Collaborate messaging system, when a business message reaches its destination (the receive queue of the destination c-enabler node), a system message is returned to the sender to acknowledge the message delivery if the Quality of Service setting requires it.
A c-enabler 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 WebLogic Collaborate messaging system provides message tracking features that allow c-hub and c-enabler administrators to check the progress of a business message as it moves through various predefined message tracking locations along the message path en route to its destination. The WebLogic Collaborate Administration Console can display status information if a business message passes through these tracking points. Administrators can use message tracking information for debugging and to identify bottlenecks in applications.
Note: The availability of message tracking locations depends on the configuration of the WebLogic Collaborate system and the specified Quality of Service for a given business message (such as CONFIRMED_DELIVERY_TO_DESTINATION(S), which is described in Table 3-1). For example, if the c-enabler and c-hub are collocated on the same node, some locations are not available. Similarly, some locations may not be available for synchronous message delivery.
Diagram of Message Tracking Locations
The following figure shows the message tracking locations in the WebLogic Collaborate messaging system.
Figure 3-1 Message Tracking Locations
Description of Message Tracking Locations The following message tracking locations are potentially visible in the WebLogic Collaborate Administration Console.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|