Creating and Adding 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

 

---

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

What Are Logic Plug-Ins?

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

Logic plug-ins insert rules and business logic at strategic locations along the path that business messages travel as they make their way through WebLogic Collaborate. Logic plug-ins are instances of Java classes that are created when business protocols are created in WebLogic Collaborate, and are activated when a delivery channel is started. They are invoked when a message passes through.

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

Logic Plug-In Architecture

Logic plug-ins can be installed at two processing locations in the WebLogic Collaborate instance: the router and the filter, as shown in the following figure.

Figure 3-1 Logic Plug-In Locations in WebLogic Collaborate: Router and Filter

 

Logic Plug-In Processing Tasks

WebLogic Collaborate-provided router and filter plug-ins for all supported business protocols, including XOCP and RosettaNet, are directly involved in the processing of message recipient information in messages 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 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 3-1 Tasks Performed by Logic Plug-Ins

Process	Description	Examples
Route Modification	Changes the list of target recipients for a business message. Subject to conversation and collaboration agreement 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: The business messages that are usually examined are those without encrypted contents.	"Log all senders of messages for billing purposes." "For messages of type X, how many are conversation version 1 versus conversation version 2?"

 

Chains

Both the router and filter modules can have multiple plug-ins that are executed when a business message passes through those modules in WebLogic Collaborate. Multiple logic plug-ins that share the same protocol are sequenced as a logic plug-in chain.

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

Note: The position of a logic plug-in in a chain is configured in the repository using the WebLogic Collaborate Administration Console, as described in Administering BEA WebLogic Collaborate.

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

Figure 3-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 a router or filter logic plug-in chain. In this example, the chain contains four logic plug-ins that are processed in the order described in the following table.

Table 3-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 WebLogic Collaborate 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 WebLogic Collaborate 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 through WebLogic Collaborate (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 WebLogic Collaborate router message queue. This should be the last logic plug-in in the XOCP router chain.

 

In this example, only XOCP business messages trigger the logic plug-ins in the XOCP router chain. Non-XOCP business messages (such as RosettaNet or cXML messages) are processed separately by the router chain associated with those business protocols.

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 WebLogic Collaborate 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 WebLogic Collaborate instance, WebLogic Collaborate creates a message envelope that acts as a container for the business message as it travels through WebLogic Collaborate. 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 3-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 BEA WebLogic Collaborate Javadoc.

For XOCP business messages, after the system XOCP router processes an XOCP business message and finalizes the list of intended message recipients, WebLogic Collaborate validates the recipients and creates a separate message envelope (and a logical copy of the XOCP business message) for each recipient in the list. These message envelopes are then forwarded to the XOCP filter for processing.

System and Custom Logic Plug-Ins

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

Table 3-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 logic plug-in 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 WebLogic Collaborate router message queue. In general, this system logic plug-in should be last in the XOCP router logic plug-in 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 logic plug-in chain so that custom logic plug-ins can subsequently process a business message after rejected business messages have been filtered out.
RosettaNet router enqueue	Enqueues the RosettaNet business message in the WebLogic Collaborate router message queue. In general, this system logic plug-in should be last in the RosettaNet router logic plug-in 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 logic plug-in chain.

 

In addition to using the system logic plug-ins, delivery channel owners and trading partners can develop their own custom logic plug-ins to provide specialized services through WebLogic Collaborate. 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 when using XOCP multicast. WebLogic Collaborate 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 are not 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 BEA WebLogic Collaborate Javadoc.

Table 3-4 Logic Plug-In API

Class/Interface	Description
com.bea.b2b.protocol.PlugIn	Tagging interface that describes a generic logic plug-in, that is, code that can be inserted, for execution, at various places in WebLogic Collaborate.
com.bea.b2b.protocol.PlugInException	Exception class that is thrown if an error occurs while a logic plug-in is being executed.
com.bea.b2b.protocol.messaging. MessageEnvelope	Represents the container (envelope) for a business message passing through WebLogic Collaborate. 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 (because message content modification is not allowed, however, no OutputStream is provided).
com.bea.b2b.protocol.messaging. Message	Represents a business message passing through WebLogic Collaborate. 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 usually includes subclasses to provide additional protocol-specific information about the message.
com.bea.b2b.protocol.messaging. PayloadPart	Represents a component of the message payload. Specific classes that implement 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.
com.bea.b2b.tpa.CPAInstance	Represents a collaboration agreement instance. The available methods allow you to retrieve a variety of information about the collaboration agreement. Because no modification of the collaboration agreement is allowed from this API, only retrieval and verification methods are provided.
com.bea.b2b.tpa.PartyInstance	Represents the holder of a party to a collaboration agreement. The available methods allow you to verify or retrieve assorted information about the collaboration agreement party.
com.bea.b2b.tpa. TradingPartnerInstance	Represents a trading partner instance. This is used in conjunction with PartyInstance or in a stand-alone mode with a router or filter.

 

 

---

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 (such as 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 exchange variables; 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. The business messages that are examined are usually those that do not have encrypted contents. To examine the encrypted contents of a business message, the logic plug-in must decrypt the message, inspect its contents, and then encrypt it again. Users must 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 WebLogic Collaborate 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 WebLogic Collaborate. 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 can be associated with the XOCP and RosettaNet protocols. In the WebLogic Collaborate Administration Console, you can define separate logic plug-ins for each business protocol (such as XOCP-SentMessages, RN-SentMessages, and cXML-SentMessages), although each points to the same SentMessages class. Alternatively, the same logic plug-in can be used in two different protocol chains; such chains share initialization parameters, but they are separate instances.

• An efficient logic plug-in quickly determines 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 delivery channel is activated.

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

  • If WebLogic Collaborate is shut down (that is, if the shutdown method is called on the associated com.bea.b2b.management.runtime.WLCMBean), then all logic plug-ins running on that WebLogic Collaborate instance are shut down as well. WebLogic Collaborate and the delivery channel must be restarted.

  • If logic plug-in definitions change in the WebLogic Collaborate repository, such as when the chain is resequenced or when logic plug-in definitions are added, changed, or removed, then the delivery channel 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 logic plug-in source code is installed on WebLogic Collaborate.

 

---

Creating and Adding Logic Plug-Ins

Implementing a custom logic plug-in requires a combination of development and administrative tasks. The following steps describe the requires 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 excerpts from a logic plug-in that:

• Intercepts a business message en route through WebLogic Collaborate

• 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

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 how to import the necessary packages.

Listing 3-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 3-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 3-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 WebLogic Collaborate 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 a message from progressing further through WebLogic Collaborate. For example, a logic plug-in that is validating business documents can 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 WebLogic Collaborate; 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 the method does nothing.

 

If a business message is rejected, what happens next depends on the business protocol as well as on the specified Quality of Service associated with the message. For example, the sending WebLogic Collaborate 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 3-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 later uses to store message properties.

Listing 3-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 3-5 Retrieving the Business Message from the Message Envelope

if((bMsg = mEnv.getMessage())== null)
{
        throw new PlugInException("message is NULL");
}

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.

Listing 3-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 3-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 WebLogic Collaborate 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 Administering BEA WebLogic Collaborate.