Developing Logic Plug-Ins

 

The following sections describe how to develop logic plug-ins in WebLogic Collaborate:

• About Logic Plug-Ins

• Logic Plug-In API

• Rules and Guidelines for Logic Plug-Ins

• Creating and Adding Logic Plug-Ins

For sample applications that demonstrate the use of logic plug-ins, see the MessageCounter and CheckAccount logic plug-in samples, which are described in Using Logic Plug-Ins for Billing in BEA WebLogic Collaborate Getting Started.

 

---

About Logic Plug-Ins

The following sections describe logic plug-ins and related concepts:

• What Are Logic Plug-Ins?

• Logic Plug-In Architecture

• Chains

• Business Messages and Message Envelopes

• System and Custom Logic Plug-Ins

• Creating and Adding Logic Plug-Ins

• Creating and Adding Logic Plug-Ins

What Are Logic Plug-Ins?

Logic plug-ins are individual components that perform specialized processing of business messages that pass through the c-hub. A logic plug-in is a custom service that a c-hub provider or trading partner can develop and install on a c-hub to provide additional value for c-hub management and for trading partners who use that c-hub.

Logic plug-ins insert rules and business logic at strategic locations along the path that business messages travel as they make their way through the c-hub. Logic plug-ins are Java classes that are invoked when a c-space is started. At run time, logic plug-ins can intercept, process, and output business messages. When a business message passes through the location where a logic plug-in is configured, the logic plug-in processes the business message. Logic plug-in execution occurs on the c-hub and is transparent to c-enabler users.

Each logic plug-in is associated with a business protocol. A logic plug-in processes only the messages that are exchanged using that protocol. For example, if a particular plug-in is associated with the XOCP protocol, then it will process only XOCP business messages.

Logic Plug-In Architecture

Logic plug-ins can be installed at two processing locations in the c-hub: in the router and in the filter, which are shown in the following figure.

Figure 4-1 Logic Plug-In Locations in the C-Hub: Router and Filter

 

Logic Plug-In Processing Tasks

WebLogic Collaborate-provided XOCP router and XOCP filter plug-ins, as well as RosettaNet plug-ins, are directly involved in the processing of message recipients based on Xpath expressions in the repository. However, custom logic plug-ins can perform a wide range of services that are entirely unrelated to routing or filtering, as well as performing routing and filtering operations. For example, a custom logic plug-in might track the number of messages sent from each trading partner for billing purposes.

Logic plug-ins perform the types of tasks described in the following table.

Table 4-1 Tasks That Logic Plug-Ins Perform

Process	Description	Examples
Route Modification	Changes the list of target recipients for a business message. Subject to conversation and c-space validation of the recipient. (WebLogic Collaborate plug-ins and custom plug-ins.)	"If a computer chip order over $1M is placed, make sure that NewChipCo is one of the recipients." "After January 1, 2000, no orders should be sent to OldChipCo."
Examination	Examines the contents of a business message and takes certain actions based on the results of the examination. (Custom plug-ins.) Note: Examination is usually performed on business messages without encrypted contents.	"Log all senders of messages for billing purposes." "Sample 1 out of every N messages of type X for standards compliance." "For messages of type X, how many are conversation version 1 versus conversation version 2?"
Content Modification	Changes the contents of a business message. Note: Content modification is not allowed in this release.	"If over N items are ordered, be sure to specify extra insurance."

 

Chains

Both the router and filter modules can have multiple plug-ins that will be executed when a business message passes through that part of the c-hub. Multiple logic plug-ins that share the same protocol are sequenced as a logic plug-in chain.

In a chain, the logic plug-ins are processed sequentially at run time. After one plug-in has finished executing, the next sequential plug-in in the chain will normally be activated. Each successive plug-in can access any changes made previously to the shared message information as the business message passes throughout the c-hub.

Note: The position of a logic plug-in in a chain is configured in the repository using the C-Hub Administration Console, as described in Working with Logic Plug-ins in the BEA WebLogic Collaborate C-Hub Administration Guide.

The following figure shows an example of a chain of XOCP logic plug-ins in the router location in the c-hub.

Figure 4-2 Sample XOCP Router Chain

 

Note that even when custom logic plug-ins do not provide routing or filtering capability, they must still be part of an XOCP or RosettaNet router or filter chain. In this example, the chain contains four logic plug-ins that are processed in the order described in the following table.

Table 4-2 Logic Plug-Ins in the Sample XOCP Router Chain

Logic Plug-In	Description
XOCP router	WebLogic Collaborate provides this logic plug-in, which might modify the list of recipients for an XOCP business message based on XPath router expressions configured in the repository. This should be the first logic plug-in in the XOCP router chain.
XOCP-MessageTracker	Hypothetical logic plug-in. A c-hub owner or trading partner might provide such a custom logic plug-in to track the number of business messages sent from each trading partner for billing purposes.
XOCP-MessageInspector	Hypothetical logic plug-in. A c-hub owner or trading partner might provide such a custom logic plug-in to examine and maintain statistics for the types of business documents being exchanged on the c-hub (for example, purchase orders, invoices, and so on).
XOCP router enqueue	WebLogic Collaborate provides this logic plug-in, which enqueues the XOCP business message in an internal c-hub router message queue. This should be the last logic plug-in in the XOCP router chain.

 

In this example, only XOCP business messages will trigger the logic plug-ins in the XOCP router chain. Non-XOCP business messages (such as RosettaNet messages) are processed separately by the router chain associated with the protocol/c-space defined by the URL that received the business message.

Business Messages and Message Envelopes

A business message is the basic unit of communication exchanged between trading partners in a conversation. The business message contains the list of message recipients. A business message is represented in the C-Hub API by the com.bea.b2b.protocol.messaging.Message interface. In addition, the following classes implement this interface and represent protocol-specific business messages:

• com.bea.b2b.protocol.xocp.messaging.XOCPMessage

• com.bea.b2b.protocol.rosettanet.messaging.RNMessage

When a business message enters the c-hub, the c-hub creates a message envelope that acts as a container for the business message as it travels through the c-hub. Message envelopes are instances of the com.bea.b2b.protocol.messaging.MessageEnvelope class.

The message envelope is used for routing purposes and is analogous to a paper envelope for a letter: the message envelope contains the business message plus addressing information, such as the identity of the sender (return address) and one recipient of the business message (destination address), as shown in the following figure.

Figure 4-3 Message Envelope Containing an XOCP Business Message

 

Message envelopes also contain other information about the business message. For detailed information about the MessageEnvelope class, see the Javadoc on the WebLogic Collaborate documentation CD or in the classdocs subdirectory of your WebLogic Collaborate installation.

For XOCP business messages, after the system XOCP router processes an XOCP business message and finalizes the list of intended message recipients, the c-hub validates the recipients and creates a separate message envelope (and a logical copy of the XOCP business message) for each recipient in the recipient list. These message envelopes are then forwarded to the XOCP filter for processing. For more information, see Information Flow for Message Envelopes.

System and Custom Logic Plug-Ins

WebLogic Collaborate provides the following logic plug-ins to provide standard services for processing business messages.

Table 4-3 System Logic Plug-Ins

Logic Plug-In	Description
XOCP router	Modifies the list of recipients for an XOCP business message based on XPATH router expressions configured in the repository. In general, this system logic plug-in should be first in the router chain so that custom logic plug-ins can subsequently process a business message after its list of intended recipients is known.
XOCP router enqueue	Enqueues the XOCP business message in the c-hub router message queue. In general, this system logic plug-in should be last in the XOCP router chain.
XOCP filter	Determines whether an XOCP business message is sent to a trading partner based on XPATH filter expressions configured in the repository. In general, this system logic plug-in should be first in the XOCP filter chain so that custom logic plug-ins can subsequently process a business message after rejected business messages have been filtered out.
RosettaNet router	Handles routing for RosettaNet business messages. In general, this system logic plug-in should be first in the RosettaNet router chain.
RosettaNet router enqueue	Enqueues the RosettaNet business message in the c-hub router message queue. In general, this system logic plug-in should be last in the RosettaNet router chain.
RosettaNet filter	Determines whether a RosettaNet business message is sent to a trading partner. In general, this system logic plug-in should be first in the RosettaNet filter chain.

 

In addition to using the system logic plug-ins, c-space owners and trading partners can develop their own custom logic plug-ins to provide specialized services on the c-hub. Each logic plug-in is a Java class that implements the Logic Plug-In API, as described in Programming Steps for Logic Plug-Ins.

 

---

Logic Plug-In API

WebLogic Collaborate provides a Logic Plug-In API that allows WebLogic Collaborate applications to:

• Add or remove target trading partners from the message recipient list. The c-hub validates the list of recipients before sending the business message.

• Retrieve, examine, and process parts of business messages. To ensure that the contents of business messages will not be altered or misrepresented programmatically, the logic plug-in API provides methods for examining business messages, but not for changing their contents.

The following table lists the components of the Logic Plug-in API. For more information, see the WebLogic Collaborate Javadoc.

Table 4-4 Logic Plug-In API

Class/Interface	Description
com.bea.b2b.protocol.PlugIn	Tagging interface that describes a generic logic plug-in, which represents pluggable code that can be inserted for execution at various places in the c-hub.
com.bea.b2b.protocol.PlugInException	Exception class that is thrown if an error occurs while executing a logic plug-in.
com.bea.b2b.protocol.messaging.MessageEnvelope	Represents the container ("envelope") for a business message passing through the c-hub. The MessageEnvelope contains the actual business message plus high level routing and processing information associated with the business message, such as the sender URL and the URL for one recipient (there is a single message envelope for each recipient). A Java InputStream is available in case access to the native message is needed (however, because message content modification is not allowed, no OutputStream is provided).
com.bea.b2b.protocol.messaging.Message	Represents a business message passing through the c-hub. It provides additional information to be used to properly route a message between trading partners. It also contains information specific to the particular business protocol being used for this business message. Depending on the protocol used, the Message class will usually be subclassed to provide additional protocol-specific information about the message.
com.bea.b2b.protocol.messaging.PayloadPart	Represents a component of the message payload. Specific implementing classes of this information are provided for some of the different types of parts of a business message, such as XML or non-XML parts, or to assist in accessing business protocol-specific information.
com.bea.b2b.protocol.conversation.ConversationType	Represents a single role in a specific conversation definition. It contains information such as the conversation name, conversation version, and trading partner role.

 

 

---

Rules and Guidelines for Logic Plug-Ins

Logic plug-ins should conform to the following rules and guidelines:

• Logic plug-ins must be thread-safe and, therefore, stateless. At run time, logic plug-in instances are cached and shared by multiple threads. Using instance variables is not recommended.

• If access to shared resources is required, then use the synchronized Java keyword to restrict access to the shared resource. Certain resources, such as instance variables within the class, shared objects, or external system resources (like files) might need shared access. Using the synchronized keyword can affect overall application performance, so use it only when necessary.

• Logic plug-ins can modify the message envelope and the list of recipients in the business message, but they cannot modify the message contents. Changing the business message invalidates the digital signature, if present. The Logic Plug-In API provides mutator methods for modifying the message envelope only.

• Logic plug-ins must be self-contained. They are not interdependent with other logic plug-ins; they cannot pass variables between them; and they do not return a variable. The message envelope is the only input and the only output. If the logic plug-in makes a change to the message envelope, it outputs the message envelope as modified.

• The main logic plug-in class must implement the com.bea.b2b.protocol.PlugIn interface.

• To ensure secure messaging, logic plug-ins are generally not able to inspect encrypted business messages. Examination is usually performed on business messages that do not have encrypted contents. To examine the encrypted contents of a business message, the logic plug-in would need to decrypt the message, inspect its contents, and then encrypt it again. Users would need to have their own public key infrastructure.

• It is the responsibility of the plug-in provider to ensure that any custom plug-ins that are installed on the c-hub are properly debugged and designed from a security perspective.

• A logic plug-in is always associated with at least one particular protocol in the repository. The logic plug-in is triggered only when a business message that uses that protocol passes through the c-hub. For example, a RosettaNet business message does not trigger an XOCP-defined logic plug-in, and vice versa.

• A single logic plug-in can be associated with multiple protocols in the repository. For example, the same logic plug-in class named SentMessages could be associated with the XOCP and RosettaNet protocols. In the C-Hub Administration Console, you can define two separate logic plug-ins (such as XOCP-SentMessages and RN-SentMessages), although each would point to the same SentMessages class. Alternatively, the same logic plug-in can be used in two different protocol chains; they would share initialization parameters, but they would be separate instances.

• An efficient logic plug-in determines quickly whether a business message qualifies for processing and, if not, exits immediately.

• Logic plug-ins can call other modules, including shared methods in a utility library (for example, a module that accesses a database).

• Logic plug-ins are initialized one time, when the c-space is activated.

  • If the c-space is shut down (the shutdown method is called on the associated com.bea.b2b.management.hub.runtime.CSpaceMBean), then all protocol-specific logic plug-ins associated with that c-space are shut down as well. The c-space must be restarted for the logic plug-ins to be active.

  • If the c-hub is shut down (the shutdown method is called on the associated com.bea.b2b.management.hub.runtime.CHubMBean), then all logic plug-ins running on that c-hub are shut down as well. The c-hub and c-space must be restarted.

  • If the logic plug-in definitions change in the c-hub repository, such as when the chain is resequenced or when logic plug-in definitions are added, changed, or removed, then the c-space must be shut down and restarted to reflect the repository changes.

• The WebLogic Server instance must be restarted (and the Java Virtual Machine, or JVM, reloaded) if an upgraded version of the logic plug-in source code is installed on the c-hub.

 

---

Creating and Adding Logic Plug-Ins

Implementing a custom logic plug-in requires a combination of development and administrative tasks. The following steps describe those procedures:

• Programming Steps for Logic Plug-Ins

• Administrative Tasks

Programming Steps for Logic Plug-Ins

This section describes the programming steps that you must perform in the logic plug-in code. Although each logic plug-in processes business messages in its own way, all logic plug-ins must perform certain tasks.

To implement a logic plug-in, complete the following steps:

• Step 1: Import the Necessary Packages

• Step 2: Implement the PlugIn Interface

• Step 3: Specify the Exception Processing Model

• Step 4: Implement the Process Method

• Step 5: Get the Business Message from the Message Envelope

• Step 6: Validate the Business Message

• Step 7: Get Business Message Properties

• Step 8: Process the Business Message as Needed

This section uses code fragments from the SentMsgCounter.java file in the MessageCounter sample application. The SentMsgCounter class is a logic plug-in that:

• Intercepts a business message en route through the c-hub

• Obtains the names of the message sender, its target recipient, and its associated conversation definition

• Inserts a row with this information in the billing database.

The CheckAccount.java file in the CheckAccount sample application is another example of a logic plug-in. For more information about the MessageCounter and CheckAccount sample applications, see Using Logic Plug-Ins for Billing in BEA WebLogic Collaborate Getting Started.

Step 1: Import the Necessary Packages

At a minimum, a logic plug-in needs to import the following packages:

• com.bea.b2b.protocol.*

• com.bea.b2b.protocol.messaging.*

The following listing from the SentMsgCounter.java file shows importing the necessary packages.

Listing 4-1 Importing the Necessary Packages

import java.util.Hashtable;
import com.bea.b2b.protocol.*;
import com.bea.b2b.protocol.messaging.*;
import com.bea.eci.logging.*;
import javax.naming.*;
import javax.sql.DataSource;

// This package is needed to access the DB pool
import java.sql.*;

Step 2: Implement the PlugIn Interface

A logic plug-in needs to implement the com.bea.b2b.protocol.PlugIn interface, as shown in the following listing.

Listing 4-2 Implementing the PlugIn Interface

public class SentMsgCounter implements PlugIn
{ ...
}

Step 3: Specify the Exception Processing Model

A PlugInException is thrown if:

• A run-time exception (such as a NullPointerException) is thrown by a logic plug-in and caught by WebLogic Collaborate processing code.

• The logic plug-in throws an exception to indicate problems encountered during logic plug-in processing. The logic plug-in might handle the exception directly or it might notify the WebLogic Collaborate processing code.

The exception processing model specified in a logic plug-in determines what happens if an exception is thrown. Logic plug-ins must implement the exceptionProcessingModel method and specify one of the return values described in the following table.

Table 4-5 Options for the Exception Processing Model

Class/Interface	Description
EXCEPTION_CONTINUE	Indicates that processing should continue to the next logic plug-in in the chain if a PlugInException is thrown. Use this option to allow a business message to continue through the c-hub even if an error occurs during the execution of this logic plug-in.
EXCEPTION_STOP	Indicates that processing should stop at this logic plug-in if a PlugInException is thrown. The business message does not continue to the next logic plug-in in the chain. Use this option to cancel message processing and prevent its further progress through the c-hub. For example, if a logic plug-in might validate business documents and reject any that contain insufficient or incorrect data.
EXCEPTION_UNWIND	Indicates that processing should unwind if a PlugInException is thrown. The business message does not continue to the next logic plug-in in the chain. Use this option to reject a message; to prevent its further progress through the c-hub; and to undo any changes made by this plug-in, along with any changes made by previous plug-ins in the chain. If an exception is thrown and this is the exception processing model, then the unwind methods in all previous plug-ins in the chain (but not the current logic plug-in), are invoked in reverse order. In effect, unwinding cancels all changes made by the chain. For example, if a logic plug-in inserts a row in a database table, its unwind method should delete that row. Note: To use this exception processing model, all logic plug-ins in the chain must implement the unwind method, even if it does nothing.

 

If a business message is rejected, what happens next depends on the business protocol as well as the specified Quality of Service associated with the message. For example, the sending c-enabler application might be notified that message delivery failed and it might then attempt to send the business message again.

The following listing shows how the SentMsgCounter plug-in implements the exceptionProcessingModel method.

Listing 4-3 Specifying the Exception Processing Model

public int exceptionProcessingModel()
{
  return EXCEPTION_CONTINUE;
}

Step 4: Implement the Process Method

To process a business message, a logic plug-in must implement the process method, which accepts the message envelope of the business message as its only parameter. In the following listing, the SentMsgCounter class begins its implementation of the process method by defining the variables that it will later use to store message properties.

Listing 4-4 Implementing the Process Method

  public void process(MessageEnvelope mEnv) throws PlugInException
{
    
    String sender, conversation ;
    String tRecipient;
    Connection conn = null;
    Statement stmt = null;
    Message bMsg = null;
    ...
}

Note: When processing a business message, a logic plug-in is allowed to modify only the message envelope, not the business message.

Step 5: Get the Business Message from the Message Envelope

If a logic plug-in needs to inspect the contents of a business message, it must call the getMessage method on the MessageEnvelope instance, which retrieves the business message as a Message object.

In the following listing, the SentMsgCounter class gets the business message from the message envelope by calling the getMessage method.

Listing 4-5 Retrieving the Business Message from the Message Envelope

    if((bMsg = mEnv.getMessage())== null)
    {
        new Throwable("bMsg is NULL").printStackTrace();
    }

Step 6: Validate the Business Message

Optionally, a logic plug-in can determine whether a message is a valid business message that should be processed, or a system message that should be ignored by the logic plug-in. To check a business message, the logic plug-in can call the isBusinessMessage method on the Message instance. In the following listing, the SentMsgCounter class uses the isBusinessMessage method to ensure that the message is a business message before processing it.

Listing 4-6 Validating the Business Message

    if (bMsg.isBusinessMessage())
    {
    ...
    }

Step 7: Get Business Message Properties

Optionally, a logic plug-in can retrieve certain properties of the business message by calling methods on the MessageEnvelope or Message instance. In the following listing, the SentMsgCounter class gets the name of the conversation definition associated with the conversation in which this message was sent, the name of the sender of the business message, and the name of the recipient trading partner.

Listing 4-7 Retrieving Business Message Properties

       conversation= bMsg.getConversationType().getName();
       sender = mEnv.getSender();
       tRecipient = mEnv.getRecipient();

Step 8: Process the Business Message as Needed

After a logic plug-in has obtained the necessary information from the business message, it processes this information as needed. For example, the SentMsgCounter plug-in updates the billing database with the message statistics it has collected.

Administrative Tasks

An administrator adds the logic plug-in definition to the repository by performing the following tasks from the Logic Plug-Ins tab of the C-Hub Administration Console:

1. Specify the following logic plug-in properties:

   • Name of the logic plug-in.

   • Java class that implements the PlugIn interface. This class can call auxiliary classes in the class library, but it must be the main point of entry for the logic plug-in. In addition, the Java class file must reside in a location specified by the WebLogic CLASSPATH.

   • Parameter name/value pairs to use when initializing the Java class.

2. Assign a logic plug-in to a business protocol.

3. Specify the position of the logic plug-in in the chain.

For more information about administrative tasks, see Working with Logic Plug-Ins and Using the C-Hub Administration Console in the BEA WebLogic Collaborate C-Hub Administration Guide.