BEA Logo BEA WebLogic Collaborate Release 1.0.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

   WebLogic Collaborate Doc Home   |   C-Hub Administration   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Routing and Filtering XOCP Business Messages

 

The following sections describe how to use routing, filtering, and XPath expressions to control the flow of XOCP business messages exchanged among trading partners in a c-space:

 


Run-Time Message Processing

BEA WebLogic Collaborate uses the XOCP router and XOCP filter to direct the flow of XOCP business messages through the c-hub to trading partners in a c-space as follows:

The following figure provides an overview of how a c-hub processes a message.

Figure 7-1 Overview of Message Processing

The following figure provides a detailed look at the router. The router consists of a protocol-specific router for each business protocol that WebLogic Collaborate supports.

Note: For completeness, RosettaNet is included in the diagram even though RosettaNet is not part of XOCP message processing.

Figure 7-2 Router

The following figure provides a detailed look at the filter. The filter consists of a protocol-specific filter for each business protocol that WebLogic Collaborate supports.

Note: For completeness, RosettaNet is included in the diagram even though RosettaNet is not part of XOCP message processing.

Figure 7-3 Filter

The following figure provides a detailed look at how a c-hub processes an XOCP business message.

Figure 7-4 XOCP Message Processing

The following sections explain how the "send" and "receive" sides of the c-hub process an XOCP business message:

The Send Side

The following sections describe the components in the "send" side of the c-hub and explain how they process an XOCP business message:

C-Enabler XPath Expression

When sending an XOCP business message, the c-enabler for the sending trading partner can specify a c-enabler XPath expression that defines the intended recipients for the business message. The c-enabler XPath expression is defined in a WebLogic Process Integrator workflow or in a c-enabler application. For more information about c-enabler XPath expressions, see Creating C-Enabler XPath Expressions.

Transport Service

The transport service reads the incoming XOCP business message and does the following:

  1. Wraps the message in a message envelope to expedite processing as it travels through the c-hub.

  2. Forwards the message to the appropriate decoder based on the business protocol, such as XOCP or RosettaNet. The URL on which the transport service receives the message identifies the protocol and the c-space. Each c-space/business protocol combination has a unique URL. A trading partner uses this URL to access a particular c-space using a particular business protocol.

    Warning: A URL for a c-space/business protocol combination can be used only by the c-hub and c-enablers. If customer-supplied software uses one of these URLs, messages will not be processed correctly.

    For information about business protocols, see Configuring Business Protocols.

Decoder

The decoder does the following:

  1. Processes the protocol-specific headers.

  2. Identifies the sending trading partner.

  3. Enlists the sending trading partner in a conversation.

  4. Prepares a reply to return to the sender.

  5. Forwards the message to the scheduling service.

Scheduling Service

The scheduling service enqueues the message to store it for subsequent retrieval and forwards the message to the XOCP router.

XOCP Router

The XOCP router is a chain of logic plug-ins that specifies the recipients for the XOCP business message. Each logic plug-in can add trading partners to or remove trading partners from the set of recipient trading partners.

The order of the logic plug-ins in the XOCP router is:

  1. XOCP router logic plug-in—provided by WebLogic Collaborate

  2. Customer-supplied logic plug-ins—optional logic plug-ins that you can create

  3. XOCP router enqueue logic plug-in—provided by WebLogic Collaborate

The following sections describe these logic plug-ins.

XOCP Router Logic Plug-In

The XOCP router logic plug-in does the following:

  1. Creates a message-context document.

    A message-context document is an XML document that the XOCP router logic plug-in generates from the XOCP business message and associated information in the repository. The message-context document describes header and payload information about the XOCP business message, such as the c-hub, large message information, c-space, business protocol, conversation, sending trading partner, receiving trading partners, message definition, and document definition. The XOCP router logic plug-in uses XPath expressions to evaluate the message-context document. For more information about message-context documents, see Working with Message-Context Documents.

  2. Evaluates the message-context document against the XPath routing expressions, which can refer to values in the message-context document. This evaluation results in a set of trading partners that are targeted to receive the XOCP business message.

    The XOCP router logic plug-in uses the XPath routing expressions in the following order:

    1. C-enabler XPath expression.

      For information about c-enabler XPath expressions, see C-Enabler XPath Expression and Creating C-Enabler XPath Expressions.

    2. Sequence of trading partner XPath routing expressions.

      These XPath routing expressions are defined in the repository and are defined for the sending trading partner. Each trading partner XPath routing expression applies to all XOCP business messages that the c-hub receives from a particular sending trading partner. Each sending trading partner can have multiple trading partner XPath routing expressions.

      Each trading partner XPath routing expression can examine different parts of the message-context document and select a different set of recipient trading partners. The trading partners produced by each expression can either replace the previously generated set of recipient trading partners or add to the current set.

    3. Sequence of c-hub XPath routing expressions.

      These XPath routing expressions are defined in the repository and are defined for the c-hub. Each c-hub XPath routing expression applies to all XOCP business messages that the c-hub receives from all sending trading partners. The c-hub can have multiple c-hub XPath routing expressions.

      As with trading partner XPath routing expressions, each c-hub XPath routing expression can examine different parts of the message-context document and select a different set of recipient trading partners. The trading partners produced by each expression can either replace the previously generated set of recipient trading partners or add to the current set.

      You can add XPath expressions to the repository for use by the XOCP router logic plug-in. For information about XPath expressions, see Working with XPath Expressions.

  3. Discards the message-context document.

  4. If the set of recipient trading partners is empty, then the XOCP router logic plug-in does not forward the message to the next component in the c-hub. Otherwise, the c-hub continues to process the message.

Customer-Supplied Logic Plug-Ins

You can create logic plug-ins and add them to the XOCP router. If you create a new logic plug-in, you must add it to the chain after the XOCP router logic plug-in and before the XOCP router enqueue logic plug-in. The order of the logic plug-ins in the XOCP router chain is specified in the XOCP business protocol definition.

A customer-supplied logic plug-in does not have to provide router functionality to be part of the XOCP router. For example, a customer-supplied logic plug-in can provide billing functionality by keeping track of the number of message sent by a particular sending trading partner and then billing the trading partner for those messages. Even when a customer-supplied logic plug-in does not provide routing or filtering functionality, it can be added only to the XOCP router or the XOCP filter. For more information about logic plug-ins, see Developing Logic Plug-Ins in the BEA WebLogic Collaborate Developer Guide.

If the set of recipient trading partners is empty after the processing performed by a customer-supplied router logic plug-in, then the customer-supplied router logic plug-in does not forward the message to the next component in the c-hub. Otherwise, the c-hub continues to process the message.

XOCP Router Enqueue Logic Plug-In

The XOCP router enqueue logic plug-in does the following:

  1. Enqueues the XOCP business message along with the intended recipients.

  2. Forwards the message to the routing service.

Routing Service

The routing service does the following:

  1. Performs the final validation of the message recipients.

  2. Creates a separate message envelope, along with a copy of the message content, for each validated recipient trading partner.

  3. Stores each copy of the message for delivery.

  4. Forwards each copy of the message to the XOCP filter.

The Receive Side

The following sections describe the components in the "receive" side of the c-hub and explain how they process an XOCP business message:

XOCP Filter

The XOCP filter is a chain of logic plug-ins that determines whether or not to send an XOCP business message to an intended recipient. These logic plug-ins are evaluated after the XOCP router logic plug-ins and can modify or override the XOCP router results. Each logic plug-in can determine not to send the message.

The order of the logic plug-ins in the XOCP filter is:

  1. Customer-supplied logic plug-ins—optional logic plug-ins that you can create

  2. XOCP filter logic plug-in—provided by WebLogic Collaborate

The following sections describe these logic plug-ins.

XOCP Filter Logic Plug-In

The XOCP filter logic plug-in does the following:

  1. Creates a message-context document.

    A message-context document is an XML document that the XOCP filter logic plug-in generates from the XOCP business message and associated information in the repository. The message-context document describes header and payload information about the XOCP business message, such as the c-hub, large message information, c-space, business protocol, conversation, sending trading partner, receiving trading partners, message definition, and document definition. The XOCP filter logic plug-in uses XPath expressions to evaluate the message-context document. For more information about message-context documents, see Working with Message-Context Documents.

  2. Evaluates the message-context document against the XPath filtering expressions, which can refer to values in the message-context document. This evaluation determines whether or not to send the message to the intended recipient.

    The XOCP filter logic plug-in uses the XPath filtering expressions in the following order:

    1. Sequence of trading partner XPath filtering expressions.

      These XPath filtering expressions are defined in the repository and are defined for the recipient trading partner. Each trading partner XPath filtering expression applies to all XOCP business messages that the c-hub receives for a particular recipient trading partner. Each recipient trading partner can have multiple trading partner XPath filtering expressions.

      Each trading partner XPath filtering expression can examine different parts of the message-context document and return a Boolean result that indicates acceptance or rejection of the message.

    2. Sequence of c-hub XPath filtering expressions.

      These XPath filtering expressions are defined in the repository and are defined for the c-hub. Each c-hub XPath filtering expression applies to all XOCP business messages that the c-hub receives for all recipient trading partners. The c-hub can have multiple c-hub XPath filtering expressions.

      As with trading partner XPath filtering expressions, each c-hub XPath filtering expression can examine different parts of the message-context document and return a Boolean result that indicates acceptance or rejection of the message.

      You can add XPath expressions to the repository for use by the XOCP filter logic plug-in. For information about XPath expressions, see Working with XPath Expressions.

  3. Discards the message-context document.

  4. If the XOCP filter logic plug-in cancels delivery of the XOCP business message to the intended recipient, then the XOCP filter logic plug-in does not forward the message to the next component in the c-hub. Otherwise, the c-hub continues to process the message.

Customer-Supplied Logic Plug-Ins

You can create logic plug-ins and add them to the XOCP filter. If you create a new logic plug-in, you must add it to the chain before the XOCP filter logic plug-in. The order of the logic plug-ins in the XOCP filter chain is specified in the XOCP business protocol definition.

A customer-supplied logic plug-in does not have to provide filter functionality to be part of the XOCP filter. For example, a customer-supplied logic plug-in can provide sampling functionality by keeping track of the types of messages sent to a particular recipient trading partner. Even when a customer-supplied logic plug-in does not provide routing or filtering functionality, it can be added only to the XOCP router or the XOCP filter. For more information about logic plug-ins, see Developing Logic Plug-Ins in the BEA WebLogic Collaborate Developer Guide.

If the customer-supplied logic plug-ins cancels delivery of the XOCP business message to the intended recipient, then the customer-supplied filter logic plug-in does not forward the message to the next component in the c-hub. Otherwise, the c-hub continues to process the message.

Scheduling Service

The scheduling service does the following:

  1. Performs additional internal operations related to quality of service issues and conversation management. For information about quality of service, see the BEA WebLogic Collaborate Developer Guide.

  2. Forwards the message to the encoder.

Encoder

The encoder transforms the message as necessary to support the business protocol and forwards the message to the transport service.

Transport Service

The transport service sends the message to the recipient.

 


Working with Message-Context Documents

For information about how message-context documents are created and used, see XOCP Router Logic Plug-In and XOCP Filter Logic Plug-In.

This section describes message-context documents:

DTD for the Message-Context Document

The following listing is the Document Type Definition (DTD) for the message-context document.

Listing 7-1 Document Type Definition for Message-Context Document

<!--	Copyright (c) 2000 BEA Systems, Inc. -->
<!-- All rights reserved -->

<!-- This DTD describes the message context document for
XPath routing expressions and XPath filtering expressions -->

<!ELEMENT c-hub (c-space, conversation, sender, trading-partner+,
message)>
<!ATTLIST c-hub context (message-router | trading-partner-router | hub-router | trading-partner-filter | hub-filter) #REQUIRED>
<!ATTLIST c-hub name CDATA #IMPLIED>
<!ATTLIST c-hub large-msg-support-on CDATA #IMPLIED>
<!ATTLIST c-hub large-msg-min-size CDATA #IMPLIED>
<!ATTLIST c-hub large-msg-location CDATA #IMPLIED>

<!ELEMENT c-space (business-protocol)>
<!ATTLIST c-space name CDATA #REQUIRED>

<!ELEMENT business-protocol EMPTY>
<!ATTLIST business-protocol name CDATA #REQUIRED>
<!ATTLIST business-protocol url CDATA #REQUIRED>

<!ELEMENT conversation EMPTY>
<!ATTLIST conversation name CDATA #REQUIRED>
<!ATTLIST conversation version CDATA #REQUIRED>
<!ATTLIST conversation default-durability CDATA #IMPLIED>
<!ATTLIST conversation default-conversation-timeout
CDATA #IMPLIED>
<!ATTLIST conversation sender-role CDATA #REQUIRED>
<!ATTLIST conversation receiver-role CDATA #REQUIRED>

<!-- A sender is a trading-partner that has sent a message from a role in a conversation. -->
<!ELEMENT sender (trading-partner)>

<!-- A Trading Partner represents an entity such as a company that sends or receives messages. -->
<!ELEMENT trading-partner (address, extended-property-set*)>
<!ATTLIST trading-partner email CDATA #IMPLIED>
<!ATTLIST trading-partner fax CDATA #IMPLIED>
<!ATTLIST trading-partner name ID #REQUIRED>
<!ATTLIST trading-partner phone CDATA #IMPLIED>
<!ATTLIST trading-partner certificate-field CDATA #IMPLIED>
<!ATTLIST trading-partner certificate-field-value CDATA #IMPLIED>
<!ATTLIST trading-partner user-name CDATA #IMPLIED>

<!ELEMENT address ANY>

<!ELEMENT extended-property-set ANY>
<!ATTLIST extended-property-set name CDATA #REQUIRED>

<!-- A message is a multipart payload sent between trading partners -->
<!ELEMENT message (message-part+)>
<!ATTLIST message message-def-name CDATA #REQUIRED>

<!ELEMENT message-part ANY>
<!ATTLIST message-part document-def-name CDATA #IMPLIED>
<!ATTLIST message-part content-type CDATA #REQUIRED>
<!-- A message part may include or exclude the subelements based on admin settings or mime-type -->
<!ATTLIST message-part include (yes | no) #REQUIRED>

Sample Message-Context Document and XPath Expressions

The following listing shows a sample message-context document generated by the XOCP router logic plug-in for a business message.

Listing 7-2 Sample Message-Context Document

<c-hub name="CHub1">
<c-space name="Cspace1">
<business-protocol name="XOCP1" url="http://myserver/Cspace1/XOCP1"/>
</c-space>
<conversation name="aConv" version="1.0">
<sender role="buyer"/>
<receiver role="seller"/>
</conversation>
<sender>
<trading-partner name="Partner1"
email="messages@partner1.com"
phone="123-456-7890"
fax="123-456-7899">
<address>123 Main Street, My Town, CA 95131</address>
<extended-property-set name="Partner1 contact">
<business-contact>John Doe</business-contact>
<phone type="work">123-456-7898</phone>
<phone type="cell">123-456-7897</phone>
<city>San Jose</city>
<state>California</state>
</extended-property-set>
</trading-partner>
</sender>

<!-- List of target trading partners extracted from the repository -->
<trading-partner name="Partner2"
email="messages@partner2.com"
phone="123-456-7896">
<address>456 Another Street, Any Town, CA 95136</address>
<extended-property-set name="Partner2 contact">
<business-contact>Jane Smith</business-contact>
<phone type="work">123-456-7895</phone>
<phone type="cell">123-456-7894</phone>
<city>San Jose</city>
<state>California</state>
</extended-property-set>
</trading-partner>

<message message-def-name="Product Query">
<message-part document-def-name="ProductQueryDefinition"
content-type="text/xml" include="yes">
<ProductPriceAndAvailabilityQuery>
</message-part>
</message>
</c-hub>

For this XOCP business message, XPath routing expressions in the XOCP router logic plug-in could refer to any of the elements in this XML document, including extended properties and message parts. The following XPath routing expression routes messages to trading partners that have extended properties specifying that they are located in San Jose, California:

/c-hub/trading-partner[extended-property-set[city='San Jose' AND state='California']]

 


Working with XPath Expressions

This section describes XPath expressions and how to create them:

About XPath Expressions

XPath is the XML path language that is defined by the World Wide Web Consortium. The XOCP router logic plug-in and the XOCP filter logic plug-in use XPath expressions to evaluate message-context documents. You can add XPath expressions to the repository for use by the XOCP router logic plug-in and the XOCP filter logic plug-in.

XPath expressions in the XOCP router logic plug-in and XOCP filter logic plug-in perform the following functions:

The following table provides an overview of the various types of XPath expressions.

In the XOCP router logic plug-in, each XPath routing expression can examine different parts of the message-context document and select a different set of recipient trading partners. The trading partners produced by each expression can either replace the previously generated set of recipient trading partners or add to the current set.

The following table steps through an example that shows how XPath routing expressions can be used.

In the XOCP filter logic plug-in, each XPath filtering expression can examine different parts of the message-context document to determine whether or not to forward the message to the recipient trading partner. Each XPath filtering expression can return true or false using different selection criteria. After an XPath filtering expression returns false, the message is blocked from further evaluation and is not sent to the intended recipient.

An XPath expression can refer to the following kinds of information:

Creating C-Enabler XPath Expressions

When sending an XOCP business message, the c-enabler for the sending trading partner can specify a c-enabler XPath expression that defines the intended recipients for the business message. The c-enabler XPath expression is defined in a WebLogic Process Integrator workflow or in a c-enabler application. This XPath expression selects a subset of <trading-partner> nodes from the message-context XML document that the XOCP router logic plug-in will generate.

The sending c-enabler defines this XPath expression and sends it to the c-hub along with the message. The c-enabler defines an XPath expression as follows:

Creating Trading Partner XPath Expressions

A trading partner XPath expression is an XPath expression that is defined for a trading partner. For routing, a trading partner XPath expression is used by the XOCP router logic plug-in and is defined for the sending trading partner. For filtering, a trading partner XPath expression is used by the XOCP filter logic plug-in and is defined for the receiving trading partner.

Trading partner XPath expressions are defined in the repository. You can use the following tools to create trading partner XPath expressions for the XOCP router logic plug-in and the XOCP filter logic plug-in:

For example, a trading partner might want to route requests to trading partners that are located in California. To do this, the trading partner can use the detail screen on the Trading Partners tab in the C-Hub Administration Console to create the following XPath expression for the XOCP router logic plug-in:

/c-hub/trading-partner[extended-property-set/state='California']

For another example, a trading partner might want to ignore bid requests for quantities less than 100. To do this, the trading partner can use the detail screen on the Trading Partners tab in the C-Hub Administration Console to create the following XPath expression for the XOCP filter logic plug-in:

(/c-hub/message/@message-def-name='Product Bid' AND /c-hub/message/message-part[1]/quantity >= 100])

Creating C-Hub XPath Expressions

A c-hub XPath expression is an XPath expression that is defined for a business protocol. For routing, a c-hub XPath expression is used by the XOCP router logic plug-in and is defined for all the XOCP business messages that pass through the c-hub. For filtering, a c-hub XPath expression is used by the XOCP filter logic plug-in and is defined for all the XOCP business messages that pass through the c-hub.

C-hub XPath expressions are defined in the repository. You can use the following tools to create c-hub XPath expressions for the XOCP router logic plug-in and the XOCP filter logic plug-in:

For example, a c-hub administrator might want to filter messages for trading partners that are shippers so that they receive only shipping requests, while all other types of trading partners receive all messages. To do this, the c-hub administrator can use the Business Protocol Definitions tab in the C-Hub Administration Console to create the following XPath expression for the XOCP filter logic plug-in:

(/c-hub/message/@message-def-name='Shipping Request' AND /c-hub/trading-partner/extended-property-set/business='shipper') OR (/c-hub/trading-partner/extended-property-set/business!='shipper')