|
|
|
|
|
|
Developing XOCP C-Enabler Applications to Exchange Business Messages
XOCP is the default protocol used by WLC for exchanging business messages. This section includes the following topics:
Introduction
The WebLogic Collaborate C-Enabler API is no longer recommended for developing XOCP applications to exchange business messages. This documentation is provided to support preexisting WebLogic Collaborate installations in which the XOCP protocol is used to manage business message processes.
Instead of using the API the recommended method is to use the WebLogic Process Integrator Studio with the WebLogic Collaborate plug-in. To create applications that exchange business messages, see the WebLogic Process Integrator Studio.
Terminology in this documentation differs in several significant ways from current WebLogic Collaborate terminology. For information about migrating from previous releases of WebLogic Collaborate to WebLogic Collaborate Release 2.0, including a table that maps the terminology differences, see Migrating Applications that Exchange Business Messages Using the XOCP Protocol in Migrating BEA WebLogic Collaborate to Release 2.0.
Note: If you migrated a Java messaging application that was written using the WebLogic Collaborate C-Enabler API to WebLogic Collaborate Release 2.0, the migrated application must be run in a separate Java Virtual Machine (JVM) in nonpersistent mode.
Many of the code examples in this documentation derive from the installation verification example. For more information, see Installing BEA WebLogic Collaborate and the "Hello Partner Sample" in Using BEA WebLogic Collaborate Samples.
Developers can also design and implement workflows by using the WebLogic Process Integrator Studio. For more information, see Using the BEA WebLogic Process Integrator Studio, Chapter 2, "Using Workflows to Exchange Business Messages."
The following sections describe XOCP c-enabler applications and related concepts:
Key Concepts
This section describes the following key concepts associated with c-enabler applications:
XOCP C-Enabler Applications
XOCP c-enabler applications are Java applications that run on c-enabler nodes and use the C-Enabler Class Library to execute the following tasks: join and leave c-spaces; initiate or participate in conversations; terminate or leave conversations; and exchange XOCP business messages with other trading partners in the c-space. A c-enabler node can host many XOCP c-enabler applications.
C-Enabler Class Library
The C-Enabler Class Library provides APIs for exchanging XOCP business messages and consists of the packages listed in the following table.
For detailed information about these packages, see the Javadoc on the WebLogic Collaborate documentation CD or in the classdocs subdirectory of your WebLogic Collaborate installation.
Conversations and Conversation Definitions
In WebLogic Collaborate, a conversation is a series of message exchanges between trading partners that takes place in a collaboration space and that is predefined according to a conversation definition. Each message in the conversation may cause any number of back-end transactions.
A conversation definition consists of a unique conversation name, conversation version, message definitions, trading partner IDs, and trading partner roles for one conversation. At design time, you use the WebLogic Process Integrator Studio to link a workflow template definition to a particular role (such as buyer or seller) in a WebLogic Collaborate conversation definition.
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 c-enabler 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 C-Enabler Class Library by the com.bea.b2b.protocol.messaging.MessageEnvelope class. However, only logic plug-ins (not c-enabler applications) have programmatic access to message envelopes. For more information, see Information Flow for Message Envelopes and Routing and Filtering Business Messages in Programming BEA WebLogic Collaborate Logic Plug-Ins.
Diagram of an XOCP Business Message
The following figure shows a message envelope and the components of an XOCP business message.
Figure 1-1 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. Information Flow for Message Envelopes The following figure shows an example of how message envelopes are processed in the c-hub. Figure 1-2 Message Envelope Processing in the C-Hub
Message envelope processing occurs in the following sequence:
As shown in Figure 1-2, the router creates message envelopes for three recipients.
In Figure 1-2, the three business messages are evaluated in the filter. Two are accepted and one is rejected.
Conversation Initiators and Participants
In any XOCP conversation, there are two types of trading partner roles:
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 in order to initiate or participate in conversations associated with that 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 who is in the role of the buyer normally initiates a GetQuote conversation. Any trading partner who is in the role of the seller would normally act 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-3 Conversation Initiators and Participants
Conversation Coordinators WebLogic Collaborate supports two types of conversation coordinators that manage conversations at run time: a global conversation coordinator manages active conversations on the c-hub, and local conversation coordinators in c-enablers help the global coordinator manage active conversations locally. The following figure shows global and local conversation coordinators in the WebLogic Collaborate architecture. Figure 1-4 Global and Local Conversation Coordinators
Global Conversation Coordinator A global conversation coordinator is a c-hub-based service that coordinates conversation life cycles 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 in the c-hub. The global conversation coordinator performs the following services:
Local Conversation Coordinators
A local conversation coordinator is a c-enabler-based service that coordinates conversations in which the c-enabler node is participating. The local conversation coordinator maintains a list of active conversations in which the c-enabler node is participating. Each c-enabler session has a separate local conversation coordinator.
The local conversation coordinator performs the following tasks:
Trading Partner States
The following table describes the states assigned to trading partners as they perform tasks related to c-space and conversation participation.
Some of these trading partner states are visible in the WebLogic Collaborate Administration Console. For more information, see "Getting Started Using WebLogic Collaborate" in Introducing BEA WebLogic Collaborate.
Secure Messaging
Communication between the c-hub and c-enablers is secured via the Secure Sockets Layer (SSL). Before allowing the trading partner to exchange business messages, the c-hub must authenticate the identity of the trading partner using the trading partner's certificate. Once authenticated, business messages are exchanged securely among trading partners via the c-hub. For more information about WebLogic Collaborate security, see Using BEA WebLogic Collaborate Security.
Key Tasks for C-Enabler Applications
This section introduces the key tasks that c-enabler applications perform:
Joining a C-Space
Before exchanging business messages, a c-enabler application must join a c-space. To join a c-space, the c-enabler application must create a c-enabler session, which is a logical session between a c-enabler node and one c-hub for one particular c-space.
Before a trading partner (c-enabler application) can create a c-enabler session to join a c-space:
When a c-enabler session is created, the c-enabler sends a system message to the c-hub with a request to join the c-space using the configuration settings specified in the c-enabler XML configuration file. This message acts as an authentication request to join the WebLogic Collaborate system. The c-hub validates the registration of the trading partner in the requested c-space and, if the registration is valid, allows that trading partner to join that particular c-space. At this point, the trading partner is in a CONNECTED state but it cannot yet participate in conversations.
Note: If the c-enabler node crashes after joining a c-space, the c-enabler application can rejoin the c-space upon normal startup. The previous c-enabler session is discarded and new resources are assigned to the new c-enabler session. However, the c-hub cannot deliver business messages while the c-enabler node 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 wants to leave a c-space, the c-enabler application shuts down the associated c-enabler session, as described in Shutting Down a C-Enabler Session to Leave a C-Space.
Registering for a Role in a Conversation
Once connected, a trading partner needs to register a conversation handler for a particular role in a specific conversation definition in a given c-space. The conversation handler must be registered for the conversation type that defines how the trading partner participates in the conversation.
Role registration requires the following information in the c-hub repository:
For an introduction to these concepts, see "Getting Started Using WebLogic Collaborate" in Introducing BEA WebLogic Collaborate.
Before registering for a conversation type, the trading partner must first be authorized to register. Authorization is configured by the c-hub administrator and is based on the trading partner's subscription to a role in a conversation definition.
When a c-enabler session attempts to register a conversation handler for a specific conversation type, the c-enabler sends an XOCP system message, register for conversation, to the c-hub. The c-hub validates the role of the trading partner for the requested conversation type in the associated c-space. 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 c-hub itself. However, the c-enabler session maintains some state information about the conversations in which it is involved.
The overall tasks for conversation initiator c-enabler applications and conversation participant c-enabler applications are very similar. However, conversation initiator c-enabler applications can terminate conversations while conversation participant c-enabler applications cannot. Conversation participant c-enabler applications can only leave a conversation.
Initiating a Conversation and Sending a Business Message
To initiate a conversation, a conversation initiator c-enabler application creates the conversation. Optionally, the conversation initiator c-enabler 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 c-enabler node sends an XOCP system message, create conversation, to the c-hub. The global conversation coordinator in the c-hub creates a conversation in the appropriate c-space and enlists the trading partner as the conversation initiator. After the conversation is created, the conversation initiator c-enabler application creates and sends a business message, as described in Sending XOCP Business Messages.
Participating in a Conversation
The global conversation coordinator in the c-hub handles all business messages that the c-hub receives for a given conversation. After the c-hub delivers the 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 c-enabler session on a target c-enabler node 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 conversation handler. 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 the conversation. 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 has initiated 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, which is propagated as the callback onTerminate on registered conversation handlers in c-enabler sessions at respective c-enabler nodes.
Shutting Down a C-Enabler Session to Leave a C-Space
When a trading partner has finished its activities in a c-space, the c-enabler application should leave the c-space by shutting down the c-enabler session. When a c-enabler application shuts down a c-enabler session, the c-enabler sends an XOCP system message, leave c-space, to the c-hub. When the c-hub receives this system message, the conversation coordinator automatically terminates all of the conversations that the trading partner has initiated in the c-space and delists the trading partner from all other conversations in which it was participating in the c-space.
When a trading partner leaves a c-space, the consequences are as follows:
At this point, the trading partner is in a DISCONNECTED state in that c-space.
Run-Time Information Flow
At run time, all c-enabler applications perform certain tasks identically: they join a c-space, register conversation handlers, and leave the c-space 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-5 Information Flow Between Conversation Initiator and Participant
This is a simplified example that uses 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 conversation handler and before leaving the c-space. 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 c-enabler applications communicating through the c-hub) proceeds in the following sequence:
Note: A conversation might terminate automatically if the conversation timeout is exceeded.
For more information about these steps, see Key Tasks for C-Enabler Applications.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|