Programming Steps for C-Enabler Applications

 

The following sections describe each step in the procedure that a developer usually provides in a c-enabler application:

• Step 1: Import Packages

• Step 2: Implement the ConversationHandler Interface

• Step 3: Create a C-Enabler Session

• Step 4: Register a Conversation Handler

• Step 5: Initiate or Participate in a Conversation

• Step 6: Exchange Business Messages

• Step 7: End the Conversation

• Step 8: Shut Down the C-Enabler Session

Each section includes example code.

Note: You must provide a c-enabler XML configuration file that contains the information required by the c-enabler application at run time. Only one c-enabler XML configuration file exists per c-enabler node. However, the c-enabler XML configuration file can specify configuration information for multiple c-enabler sessions; specifically, it can provide configuration information for each c-space that the associated trading partner joins.

For more information, see "Configuration Requirements" in Administering BEA WebLogic Collaborate. In addition, for help in defining the c-enabler XML configuration file, see the comments in the EnablerConfig.dtd file in the dtd subdirectory of your WebLogic Collaborate installation.

Step 1: Import Packages

C-enabler applications import the required packages from the C-Enabler Class Library. For a description of these packages, see C-Enabler Class Library.

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

Listing 2-1 Importing Packages

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;
import com.bea.b2b.enabler.*;
import com.bea.b2b.enabler.xocp.*;
import com.bea.b2b.protocol.messaging.*;
import com.bea.b2b.protocol.xocp.conversation.local.*;
import com.bea.b2b.protocol.xocp.messaging.*;

import com.bea.eci.logging.*;

Step 2: Implement the ConversationHandler Interface

To receive messages, a c-enabler application must implement the following interface:

com.bea.b2b.protocol.xocp.conversation.local.ConversationHandler

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 the c-enabler receives a business message. The onTerminate method is invoked when the c-enabler receives a conversation termination.

The conversation handler is required in order for the trading partner to receive business messages in a conversation. A conversation handler must support at least one conversation type (com.bea.b2b.protocol.conversation.ConversationType), which represents a role in a conversation. A c-enabler session supports one conversation handler per conversation type.

Listing 2-2 Implementation of the ConversationHandler Interface

public class MyConversationHandler 
    implements ConversationHandler{

   private String collaboratorId;

    MyConversationHandler(String collaboratorId){
      this.collaboratorId = collaboratorId;
    }

    public void onMessage(XOCPMessage msg){
System.out.println("onMessage: received for collaborator:" + collaboratorId );
	Conversation conv = msg.getConversation();
     QualityOfService qos = msg.getQoS();
     
    }

    public void onTerminate(Conversation conv, int result) {
      System.out.println("onTerminate: received for collaborator:" + collaboratorId);
    }
}

For detailed information about the ConversationHandler interface, see the Javadoc on the WebLogic Collaborate documentation CD or in the classdocs subdirectory of your WebLogic Collaborate installation.

Step 3: Create a C-Enabler Session

To initiate or participate in conversations, a trading partner creates a c-enabler session on a c-enabler node. Each c-enabler session enables the trading partner to exchange messages with other trading partners in one c-space.

To create a new c-enabler session or to get an existing one, use the com.bea.b2b.enabler.Enabler class. The following listing is an example of getting the session1 c-enabler session, based on the information defined in the c-enabler XML configuration file. Alternatively, an application can get all the c-enabler session definitions from the c-enabler XML configuration file and then create c-enabler sessions as needed.

Listing 2-3 Obtaining a C-Enabler Session

Enabler enabler = Enabler.getEnabler("enabler.xml");
EnablerSession es = enabler.getEnablerSession("session1");
// Create all enabler session(s) defined in "enabler.xml"
// EnablerSession[] ess = enabler.getEnablerSessions();
// Optionally, get names of Enabler Sessions
// and use name to create enabler session individually
// String[] sessionNames = enabler.getSessionNames();
// EnablerSession es = null;

Step 4: Register a Conversation Handler

To participate in a conversation, a c-enabler application must register a conversation handler. A conversation handler can be associated with multiple conversation types (each type has a conversation name, version and role). A conversation handler can also be shared among multiple conversations. A conversation handler is implemented by the application; the developer is responsible for using it as needed.

To register a conversation handler, a c-enabler application calls the registerConversationHandler method on the XOCPEnablerSession instance, passing the conversation type and the conversation handler object as parameters.

The following example listing shows how to register a conversation handler for a buyer role (generally a conversation initiator) in the BuyProcessor conversation. Note that the specified conversation definition and role must be defined in the spoke and hub repository.

Listing 2-4 Registering a Conversation Handler

XOCPEnablerSession session = null;
if(es instanceof XOCPEnablerSession)
      session = (XOCPEnablerSession)es;
MyConversationHandler ch = new    MyConversationHandler(session.getTradingPartner());

ConversationType ctype = new ConversationType("BuyProcessor", "1.0", "buyer");
ConversationType[] types = { ctype };
session.registerConversationHandler(types, ch);

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.enabler.xocp.XOCPEnablerSession instance, passing the conversation type and, optionally, the conversation timeout value, in seconds. (The default value is zero, or no timeout, if the configured timeout is also zero in the conversation definition in the spoke and hub repository.) 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

ConversationType ctype = new ConversationType("BuyProcessor", "1.0", "buyer");
Conversation conv = session.createConversation(ctype, 0);

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 c-space.

Initially, the conversation initiator application creates and sends a business message (such as a request) to one or more trading partners in the c-space. 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. The trading partners may send and receive several business messages in the 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 have finished exchanging business messages in that conversation. The way in whiuch 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 c-enabler application calls the leave method on the Conversation instance, passing false. No messages are retained on the c-hub 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 spoke and hub repository.) 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 c-enabler 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 C-Enabler Session

To shut down a c-enabler session and leave the c-space, an application uses the shutDown method in its implementation of the EnablerSession interface, always passing false. The following example listing shows how a c-enabler session is shut down.

Listing 2-8 Shutting Down a C-Enabler Session

es.shutDown(false);

If a c-enabler application shuts down a c-enabler session, the trading partner leaves the c-space automatically and permanently.