Programming Steps for XOCP Applications

The following sections describe each step in the procedure that a developer usually provides in an XOCP application:

• Step 1: Import Packages

• Step 2: Implement the MessageListener Interface

• Step 3: Create an XOCP Application Session

• Step 4: Create and Register a Message Listener

• Step 5: Initiate or Participate in a Conversation

• Step 6: Exchange Business Messages

• Step 7: End the Conversation

• Step 8: Shut Down the XOCP Application Session

Each section includes example code from the Messaging API sample, which is fully described in Running the B2B Integration Samples.

Note: Before you can run an XOCP application, the administrator must specify a collaboration agreement for the trading partners who participate in the conversation associated with that XOCP application. For more information, see Configuration Requirements in Administering B2B Integration. For information about backward compatibility with XOCP applications created with earlier versions of WebLogic Integration, see Migrating to BEA WebLogic Integration Release 2.1.

Step 1: Import Packages

XOCP applications import the required packages from the Messaging API class library. For a description of these packages, see Messaging API Class Library.

The following example listing shows the type of packages that must be imported.

Listing 2-1 Importing Packages

import java.util.Properties; 
import com.bea.b2b.protocol.xocp.application.*; 
import com.bea.b2b.protocol.xocp.messaging.*; 
import com.bea.b2b.protocol.conversation.ConversationType; 
import com.bea.b2b.protocol.messaging.PayloadPart; 
import com.bea.b2b.protocol.xocp.conversation.local.Conversation; 
import com.bea.eci.logging.*;

Step 2: Implement the MessageListener Interface

To receive messages, an XOCP application must implement the following interface:

com.bea.b2b.protocol.xocp.messaging.XOCPMessageListener

This interface provides the onMessage and onTerminate methods that are used to handle incoming business messages and conversation termination notifications, respectively. The onMessage method is invoked when a B2B spoke receives a business message. The onTerminate method is invoked when a B2B spoke receives notification of a conversation termination.

The message listener is required in order for the trading partner to receive business messages in a conversation. An XOCP application session supports one message listener per collaboration agreement.

Listing 2-2 Implementation of the MessageListener Interface

public class Partner1MessageListener
    implements XOCPMessageListener{

    public void onMessage(XOCPMessage rmsg){
        
      counter ++;
    
      QualityOfService qos = rmsg.getQoS();
      
      // Received reply, time to wake up waiter
      
      synchronized(waiter){

        debug("onMessage in waiter counter = " + counter);

        PayloadPart[] payload = rmsg.getPayloadParts();
        // we are using a single part document
        if (payload != null && payload.length > 0){
          BusinessDocument bd = (BusinessDocument)payload[0];
          waiter.reply = bd.getDocument();
        }
        waiter.done = true;
        waiter.notify();
      }
    }  

    public void onTerminate(Conversation conv, int result)
    }
  } 

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

Step 3: Create an XOCP Application Session

To initiate or participate in conversations, a trading partner creates an XOCP application session associated with a local B2B spoke delivery channel. Each XOCP application session enables the associated trading partner to exchange messages with other trading partners in a conversation.

To create a new XOCP application session or to get an existing one, use the com.bea.b2b.protocol.xocp.application.XOCPApplication class. The following listing is an example of getting the MdmApp1 XOCP application session, based on the trading partner name (Partner 1) and the delivery channel (Partner1-Channel0).

Listing 2-3 Obtaining an XOCP Application Session

XOCPApplication app = XOCPApplication.getXOCPApplication("MdmApp1");
XOCPApplicationSession es = app.getXOCPApplicationSession("Partner1", "Partner1-Channel0"); 

Step 4: Create and Register a Message Listener

To participate in a conversation, an XOCP application must register a message listener. A message listener is implemented by the application; the developer is responsible for using it as needed.

To register a message listener, an XOCP application calls the registerMessageListener method on the XOCPApplicationSession instance, passing the collaboration agreement ID, the conversation role of the trading partner, and the message listener object as parameters.

The following example listing shows how to register a message listener for a requestor role (generally a conversation initiator) in the verifierConversation conversation. Note that the required collaboration agreement ID and role must be specified in the repositories of the trading partner and the intermediary respectively.

Listing 2-4 Registering a Message Listener

Partner1MessageListener ml =  new Partner1MessageListener();

      Properties prop = new Properties();
      prop.setProperty("BusinessProcessName", "verifierConversation");
      prop.setProperty("BusinessProcessVersion", "1.0");
      prop.setProperty("otherTradingPartner", "Hub");
      prop.setProperty("toRole", "replier");
      String caId = es.getCAId(prop);

      String myRole = "requestor";

      es.registerMessageListener(caId, myRole, ml);

Step 5: Initiate or Participate in a Conversation

A conversation initiator application explicitly starts a conversation. To initiate a conversation, the initiating trading partner calls the createConversation method on the com.bea.b2b.protocol.xocp.application.XOCPApplicationSession instance, passing the collaboration agreement ID, the trading partner role, and, optionally, the conversation timeout value, which is specified in seconds. (The default value is zero, or no timeout, if the configured timeout is also zero in the conversation definition in both the trading partner's and intermediary's respective repositories.) The trading partner must be registered in the initiator role in the conversation definition.

The following example listing shows how a conversation is initiated.

Listing 2-5 Initiating a Conversation

      long timeout = 0;
      Conversation c = es.createConversation(caId, myRole, timeout);

Step 6: Exchange Business Messages

After the conversation initiator application has created the conversation, it can begin exchanging business messages with other trading partners in the conversation.

Initially, the conversation initiator application creates and sends a business message (such as a request) to one or more trading partners in the conversation. When a trading partner receives the business message, its conversation participant application processes the business message and (usually) creates and sends a reply business message. Trading partners may send and receive several business messages in the course of a conversation. For more information about exchanging business messages, see Sending XOCP Business Messages and Receiving XOCP Business Messages.

Step 7: End the Conversation

A conversation can end after trading partners finish exchanging business messages in that conversation. The way in which a trading partner ends its involvement in a conversation depends on its role in the conversation.

Participant Leaves a Conversation

Participant trading partners can leave a conversation. To leave a conversation, a participant XOCP application calls the leave method on the Conversation instance, passing false. No messages are retained in the intermediary while the participant is not participating.

Note: In this release, only the false argument is supported.

The following example listing shows how a participant leaves a conversation.

Listing 2-6 Leaving a Conversation

c.leave(false);

Initiator Terminates a Conversation

Conversation initiators can explicitly terminate a conversation or wait until the conversation times out. (The conversation initiator can specify a timeout value when it creates the conversation, or it can specify zero to use the timeout value defined for the conversation in the trading partner's and intermediary's repositories.) When a conversation terminates, the conversation initiator and all participating trading partners are delisted from the conversation, any undelivered business messages are discarded, and associated system resources are released.

To terminate a conversation explicitly, the initiating XOCP application calls the terminate method in its implementation of the Conversation interface, as shown in the following listing.

Listing 2-7 Terminating a Conversation

c.terminate(Conversation.SUCCESS);

Step 8: Shut Down the XOCP Application Session

To shut down an XOCP application session and leave the conversation, an application uses the shutDown method in its implementation of the XOCPApplicationSession interface. The following example listing shows how an XOCP application session is shut down.

Listing 2-8 Shutting Down an XOCP Application Session

es.shutDown();

If an XOCP application shuts down an XOCP application session, the trading partner leaves the conversation automatically and permanently.