Developing XOCP Applications to Exchange Business Messages

e-docs > WebLogic Platform > WebLogic Integration > B2B Topics > Programming Messaging Applications > Developing XOCP Applications to Exchange Business Messages

Programming Messaging Applications

Developing XOCP Applications to Exchange Business Messages

Note: The Messaging API and XOCP business protocol are deprecated as of this release of WebLogic Integration. For information about the features that are replacing the Messaging API and XOCP business protocol, see the BEA WebLogic Integration Release Notes.

The eXtensible Open Collaboration Protocol (XOCP) is the default business protocol used by WebLogic Integration for exchanging business messages. This section includes the following topics:

Introduction

WebLogic Integration provides two means to implement trading partner conversations that are based on the XOCP protocol:

Via business process management (BPM) collaborative workflows that you create using the WebLogic Integration Studio. These workflows define each role in a conversation, and they specify how business messages are handled and exchanged by trading partners. For information about creating collaborative workflows, see Creating Workflows for B2B Integration.
Via XOCP applications that you create using the WebLogic Integration Messaging API. An XOCP application implements a trading partner role and interacts directly with the B2B engine to manage the conversation and handle business messages as appropriate.

This document explains how to use the Messaging API to create XOCP applications to conduct and manage conversations among trading partners.

Many of the code examples in this documentation derive from the Messaging API example. For more information, see the Messaging API Sample in Running the B2B Integration Samples.

Note: The C-Enabler API, which was formerly used for creating XOCP applications (in WebLogic Integration Release 2.0 and the WebLogic Collaborate product) is deprecated but still supported. Information about creating applications that use this deprecated API is available at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wlintegration/v2_0/collaborate/devxocp/index.htm

XOCP applications, including those originally written with the WebLogic Collaborate C-Enabler API for WebLogic Integration Release 2.0, must be run in a separate Java Virtual Machine (JVM) in nonpersistent mode.

Key Concepts

This section describes the following key concepts associated with XOCP applications:

XOCP Applications

An XOCP application is a user-written Java application that runs on a WebLogic Integration node that is deployed in a hub-and-spoke configuration and that uses the XOCP application class to execute a specific role in a conversation definition. In a hub-and-spoke configuration, a trading partner XOCP application is associated with a spoke delivery channel, or B2B spoke. This XOCP application allows a trading partner to communicate with other trading partners at B2B spokes via an intermediary, or routing proxy, which is configured with a hub delivery channel.

A user-written XOCP application executes the following tasks:

Create and shut down XOCP application sessions
Initiate or participate in conversations
Exchange XOCP business messages with other trading partners
Terminate or leave conversations

Note: For complete details on the XOCP application class, see the com.bea.b2b.protocol.xocp.application class in the BEA WebLogic Integration Javadoc.

The following figure shows three possible hub-and-spoke configurations for the delivery channels, the XOCP applications, and the instances of WebLogic Integration that host the XOCP applications.

Figure 1-1 Possible Hub-and-Spoke Configurations

A WebLogic Integration node can host many XOCP applications. For more information about configuring hub and spoke delivery channels used with XOCP applications, see Configuration Requirements in Administering B2B Integration.

XOCP Application Sessions

An XOCP application session is the means by which an XOCP application is associated with a collaboration agreement and a delivery channel. An XOCP application session is created by an application to communicate with a trading partner; and its scope is bounded by a delivery channel. XOCP applications create an XOCP application session by invoking the getXOCPApplicationSession method on the XOCP application class.

An XOCP application can be associated with multiple XOCP application sessions, enabling the application to participate in multiple conversations simultaneously.

Messaging API Class Library

The Messaging API class library includes the XOCP application class and provides APIs for exchanging XOCP business messages. It consists of the packages listed in the following table.

Table 1-1 Messaging API Class Library Packages

Package Name	Description
com.bea.b2b.protocol.xocp.application	Used for working with XOCP applications and XOCP application sessions. This package is designed for applications used by trading partners configured with a spoke delivery channel.
com.bea.b2b.protocol.xocp.conversation.local	Used for working with conversations based on XOCP.
com.bea.b2b.protocol.messaging	Used for working with messages in a conversation.
com.bea.b2b.protocol.xocp.messaging	Used for working with business messages in conversations based on XOCP.

For detailed information about these packages, see BEA WebLogic Integration Javadoc on the WebLogic Integration documentation CD or, on Windows systems, choose the BEA WebLogic e-Business Platform—>WebLogic Integration 2.1—>Javadocs from the Windows Start menu.

XOCP Business Messages and Message Envelopes

An XOCP business message is the basic unit of communication exchanged between trading partners in an XOCP conversation. An XOCP business message is represented in the Messaging API class library by the com.bea.b2b.protocol.xocp.messaging.XOCPMessage class.

A message envelope is a container for a business message. A message envelope contains information about the sender (such as the sender URL) and recipient (such as the destination URL). A message envelope is represented in the Messaging API class library by the com.bea.b2b.protocol.messaging.MessageEnvelope class. However, only logic plug-ins (not XOCP applications) have programmatic access to message envelopes. For more information, see Information Flow for Message Envelopes and Routing and Filtering Business Messages in Programming Logic Plug-Ins for B2B Integration.

Diagram of an XOCP Business Message

The following figure shows a message envelope and the components of an XOCP business message.

Figure 1-2 Components of an XOCP Business Message

Components of an XOCP Business Message

An XOCP business message is a multipart MIME (Multipurpose Internet Mail Extensions) message. It consists of the following components.

Table 1-2 Components of an XOCP Business Message

Component	Description
Message header	Message attributes, including information about the sender and recipient, the conversation, Qualities of Service, and so on.
Payload	Container for one or more business documents, one or more attachments, or a combination of both. The payload component is represented in the Messaging API class library by the com.bea.b2b.protocol.messaging.PayloadPart interface.
Business document(s)	XML files in the XML-based part of the payload. Represented in the Messaging API class library by the com.bea.b2b.protocol.messaging.BusinessDocument class.
Attachment(s)	NonXML files in the nonXML-based part of the payload. Binary content. Represented in the Messaging API class library by the com.bea.b2b.protocol.messaging.Attachment class.

Information Flow for Message Envelopes

The following figure shows an example of how message envelopes are processed in WebLogic Integration.

Figure 1-3 Message Envelope Processing in WebLogic Integration

Message envelope processing occurs in the following sequence:

A trading partner creates and sends a business message from its spoke delivery channel to the hub delivery channel at the intermediary. (This hub delivery channel can be configured on a B2B engine collocated with the sending trading partner, on a standalone machine, or on a B2B engine collocated with a recipient trading partner, as shown in Figure 1-1.)
The business message is received at the hub delivery channel. The B2B engine wraps the business message with a message envelope, extracting certain sender and recipient information from the business message.
The XOCP router processes the business message, and then validates and finalizes the list of recipients.
The router creates a separate message envelope for each recipient in the list of recipients, inserts a logical copy of the business message in each message envelope, and then forwards all message envelopes to the XOCP filter.

As shown in the example in Figure 1-3, the router creates message envelopes for three recipients.
Within the XOCP filter, the applicable filter for each recipient trading partner evaluates each business message to determine whether it will be sent to the recipient. The filter forwards accepted messages to the next processing step in the B2B engine.

In Figure 1-3, the three business messages are evaluated in the filter. Two are accepted and one is rejected.
The B2B engine validates the recipient, and then sends the business message (in its message envelope) to the recipient trading partner.
The recipient trading partner receives the business message.

Conversation Initiators and Participants

In any XOCP conversation, there are two types of trading partner roles:

Conversation initiator is the trading partner that creates the conversation and sends the first business message (such as a request) to one or more recipient trading partners. The conversation initiator usually awaits a reply from each trading partner and might exchange subsequent business messages. When finished, the conversation initiator terminates the conversation (unless the conversation has timed out).
Conversation participant is a trading partner that is enlisted in the conversation when it receives the first business message from the conversation initiator. The conversation participant usually sends a reply to the conversation initiator and, optionally, might exchange subsequent business messages. When finished, the conversation participant either leaves the conversation or waits until the conversation terminates.

Each conversation definition in the repository includes at least both of these types of roles. A trading partner must be subscribed to the appropriate role in the conversation to initiate or participate in conversations associated with the associated conversation definition.

The initiator of a conversation is usually determined by the role in which a trading partner is registered. For example, in a GetQuote conversation, the trading partner in the role of the buyer normally initiates a GetQuote conversation. Any trading partner in the role of the seller normally acts as a conversation participant in the GetQuote conversation.

The following figure shows some of the tasks that conversation initiators and conversation participants perform.

Figure 1-4 Conversation Initiators and Participants

Conversation Coordinators

WebLogic Integration supports two types of conversation coordinators that manage conversations at run time: a global conversation coordinator manages active conversations on the B2B intermediary, and local conversation coordinators associated with B2B spokes help the global coordinator manage active conversations locally.

The following figure shows where global and local conversation coordinators work in the WebLogic Integration architecture.

Figure 1-5 Global and Local Conversation Coordinators

Global Conversation Coordinator

A global conversation coordinator is a service associated with the intermediary, which is configured with a hub delivery channel. The global conversation coordinator manages conversation lifecycles according to the rules of XOCP and supports long-living, durable conversations that span multiple organizational boundaries. The global conversation coordinator maintains a list of active conversations.

The global conversation coordinator performs the following services:

Enlists and delists trading partners in a conversation
Enforces the XOCP conversation termination protocol
Maintains status information about conversations
Provides the conversational context for the execution of the business protocol

Local Conversation Coordinators

A local conversation coordinator is a service associated with a B2B spoke. The local conversation coordinator manages conversations in which the local trading partner (configured with a spoke delivery channel) is participating and maintains a list of active conversations. Each XOCP application session has a separate local conversation coordinator.

The local conversation coordinator performs the following tasks:

Locally enlists in a conversation when the initial business message in a conversation is received from the intermediary
Locally delists from a conversation when the system message that terminates the conversation is received from the intermediary

Trading Partner States

The following table describes the states assigned to trading partners as they perform tasks related to XOCP application sessions and conversation participation.

Table 1-3 Trading Partner States

State	Description
REGISTERED	Connected trading partner has registered for roles in conversations and is ready to initiate or participate in conversations.
ACTIVE	Registered trading partner has participated (that is, has sent or received a business message) in at least one conversation.
DROPPEDOUT	Trading partner has left a conversation.

Some of these trading partner states are visible in the WebLogic Integration B2B Console.

Secure Messaging

Communication among trading partners is secured via the Secure Sockets Layer (SSL). Before allowing trading partners to exchange business messages, the WebLogic Integration node must authenticate the identity of each trading partner using the trading partner's certificate. Once these identities are authenticated, business messages are exchanged securely among trading partners. For more information about WebLogic Integration security, see Implementing Security with B2B Integration.

Key Tasks for XOCP Applications

This section introduces the key tasks that XOCP applications perform:

Creating an XOCP Application Session

Before exchanging business messages, an XOCP application must create an XOCP application session for the trading partner and its associated delivery channel.

Before a trading partner XOCP application can create an XOCP application session:

Configuration information about the delivery channel and trading partner must be defined in the WebLogic Integration repositories for both the hub and spoke delivery channels associated with the collaboration agreement. For more information, see Configuration Requirements in Administering B2B Integration.
The trading partner must be authorized to access the delivery channel.

Note: If the machine hosting the XOCP application associated with the spoke delivery channel crashes after connecting to a hub delivery channel, the XOCP application can reconnect to the hub delivery channel upon normal startup. The previous XOCP application session is discarded and new resources are assigned to the new XOCP application session. However, the intermediary cannot deliver business messages while the machine associated with the spoke delivery channel is down. Undelivered business messages are discarded if the number of retry attempts is exceeded or if the business message or conversation times out.

When a trading partner no longer wants to exchange business messages with other trading partners, the XOCP application shuts down the XOCP application session, as described in Shutting Down an XOCP Application Session.

Registering for a Role in a Conversation

After the XOCP application session has been created, a trading partner needs to register a message listener for the conversation type to which it is bound by the collaboration agreement. The message listener must be registered for a conversation type that defines how the trading partner participates in the conversation.

Role registration requires the following information in the repository associated with the hub delivery channel:

The conversation type—is a subset of a conversation definition that defines a conversation for one trading partner based on the trading partner's role in the conversation definition to which it is subscribed.
A message definition—consists of ordered message parts. A message part contains a content type (XML or binary) and can contain a document definition. If the content type for a part is XML, then a document definition is required for that part. For the binary type, no other information is required.

For an introduction to these concepts, see Overview in Introducing B2B Integration

Before registering a message listener for a conversation type in a collaboration agreement, the trading partner must first be authorized to register. Authorization is configured by the administrator of the intermediary and is based on the trading partner's subscription to a role in a conversation definition.

When an XOCP application session attempts to register a message listener for a specific conversation type in a collaboration agreement, the spoke delivery channel sends an XOCP system message, register for conversation, to the intermediary. The intermediary validates the role of the trading partner for the requested conversation type in the associated delivery channel. If the registration is valid, the trading partner is then allowed to initiate and participate in conversations associated with the registered conversation type. At this point, the trading partner is in a REGISTERED state and is ready to initiate or participate in conversations.

Engaging in Conversations with Trading Partners

Once registered for a role in a conversation, a trading partner can engage in conversations in accordance with that role. Conversation initiation and participation occurs on the intermediary itself. However, the XOCP application session maintains some state information about the conversations in which it is involved.

Conversation initiator XOCP applications and conversation participant XOCP applications are very similar. However, conversation initiator XOCP applications can terminate conversations while conversation participant XOCP applications cannot. Conversation participant XOCP applications can only leave a conversation.

Initiating a Conversation and Sending a Business Message

To initiate a conversation, a conversation initiator XOCP application first creates it. Optionally, the conversation initiator XOCP application can specify a timeout value, after which the conversation automatically terminates; this value overrides the timeout value that is specified in the associated conversation definition in the repository.

The local conversation coordinator on the B2B spoke sends an XOCP system message, create conversation of the specific collaboration agreement, to the intermediary. The global conversation coordinator in the intermediary creates a conversation using the appropriate delivery channel and enlists the trading partner as the conversation initiator. After the conversation is created, the conversation initiator XOCP application creates and sends a business message, as described in Sending XOCP Business Messages.

Participating in a Conversation

The global conversation coordinator in the intermediary handles all business messages that the intermediary receives for a given conversation. After the intermediary delivers an initial business message to recipient trading partners, the global conversation coordinator enlists those trading partners in that conversation. Once a trading partner is enlisted in a conversation, the trading partner is in an ACTIVE state and can send and receive business messages in that conversation.

When the XOCP application session on a target spoke delivery channel receives the initial business message in a conversation, it performs the necessary housekeeping (such as registering the conversation in the local list) before invoking the onMessage callback on the message listener. For more information, see Receiving XOCP Business Messages.

Once a registered trading partner is enlisted in a conversation, the trading partner is in an ACTIVE state and can send and receive business messages in that conversation.

Leaving a Conversation

When it has finished participating in a conversation, a conversation participant trading partner can leave it. When a trading partner leaves a conversation, it is removed, by the conversation coordinator, from the list of participating trading partners. Subsequent business messages in that conversation are not sent to that trading partner. After a trading partner leaves, it is kept in a DROPPEDOUT state for the remainder of that conversation.

Terminating Conversations

A conversation terminates when the initiating trading partner explicitly terminates the conversation, or when the conversation times out; whichever occurs first. A trading partner who initiates a conversation must terminate that conversation at the appropriate time in a business process.

Note: Only the conversation initiator can terminate a conversation.

When a conversation is terminated, the conversation coordinator sends all of the participating trading partners an XOCP system message: terminate message. This message is propagated as the callback onTerminate on registered message listeners in XOCP application sessions on B2B spokes.

Shutting Down an XOCP Application Session

When a trading partner finishes all the activities in a conversation, the XOCP application shuts down the XOCP application session. When an XOCP application shuts down an XOCP application session, the B2B engine associated with the spoke unregisters with the intermediary all the collaboration agreements associated with this session. This causes the intermediary to unregister the associated conversation type. In response, the conversation coordinator automatically terminates all of the conversations that the trading partner has initiated in the XOCP application session and delists the trading partner from all other conversations in which it was participating.

When a trading partner shuts down an XOCP application session, the consequences are as follows:

The intermediary is stopped from sending any further messages to the trading partner at the specified delivery channel.
All conversations initiated by the trading partner are terminated.
The trading partner leaves any conversations in which it is participating.
The trading partner reclaims resources allocated in the intermediary for the shut down XOCP application session.

Run-Time Information Flow

At run time, all XOCP applications perform certain tasks identically: they connect to a delivery channel, register message listeners, and shut down the application session in the same way. During individual conversations, however, conversation initiators and conversation participants perform a series of distinct, interweaving tasks.

Information Flow Diagram

The following figure shows the run-time information flow between a conversation initiator and a participant.

Figure 1-6 Information Flow Between Conversation Initiator and Participant

This is a simplified example that involves a single conversation and a minimal exchange of business messages (request and reply). In practice, a trading partner may participate in multiple conversations after registering a message listener and before shutting down an XOCP application session. In addition, within a single conversation, trading partners might exchange many business messages, not just a single request and a single reply.

Steps in the Information Flow

At run time, the flow of information between trading partners (via XOCP applications communicating through the intermediary) proceeds in the following sequence:

Each trading partner with a specific delivery channel creates an XOCP application session.
Each trading partner XOCP application registers a message listener with the XOCP application session, which, in turn (with the help of the local conversation coordinator), registers that trading partner for a given role in a conversation in a given collaboration agreement maintained by the intermediary.
Each trading partner XOCP application gets the collaboration agreement ID, if it is not known.
The conversation starts when it is created by the conversation initiator XOCP application.
The global conversation coordinator adds the conversation instance to its global conversation list and marks the trading partner as the initiator.
The local conversation coordinator in the conversation initiator adds the conversation instance to its local conversation list.
The conversation initiator's XOCP application creates and sends a business message (such as a request).
The conversation initiator's XOCP application session delivers the business message to the hub delivery channel in the intermediary.
The intermediary delivers the business message to the conversation participant's spoke delivery channel.
The global conversation coordinator in the intermediary enlists the participating trading partner in the conversation, adding it to the conversation instance entry in the global conversation list.
The local conversation coordinator receives the business message and enlists the trading partner in the conversation locally, adding the conversation instance to the local conversation list.
The onMessage implementation in the conversation participant XOCP application is invoked and processes the business message.
The conversation participant XOCP application creates and sends a business message (such as a reply) back to the conversation initiator.
The XOCP application session associated with the conversation participant delivers the business message to the intermediary.
The intermediary receives the business message and delivers it to the conversation initiator.
The conversation initiator receives the business message.
The onMessage implementation in the conversation initiator XOCP application is invoked and processes the business message.
To end the conversation, the conversation initiator XOCP application terminates it.

Note: A conversation might terminate automatically if the conversation timeout is exceeded.
The local conversation coordinator in the conversation initiator delivers notification of termination to the global conversation coordinator in the intermediary.
The global conversation coordinator in the intermediary delists the conversation participant from the global conversation list and delivers notification of termination to the local conversation coordinator associated with the conversation participant.
The local conversation coordinator associated with the conversation participant receives the termination notification and delists the conversation from the local conversation list.
The onTerminate implementation in the conversation participation XOCP application is invoked.
The global conversation coordinator in the intermediary marks the conversation terminated and informs the conversation initiator by sending a conversation termination confirmation.
The conversation initiator receives the conversation termination confirmation.
The local conversation coordinator on the conversation initiator receives the termination notification and delists the conversation from the local conversation list.
The onTerminate implementation in the conversation initiator XOCP application is invoked.
Each trading partner XOCP application shuts down its respective XOCP application session.

For more information about these steps, see Key Tasks for XOCP Applications.