Creating and Adding Logic Plug-Ins (Deprecated)

The following sections describe how to develop logic plug-ins with WebLogic Integration:

• About Logic Plug-Ins

• Logic Plug-In API

• Rules and Guidelines for Logic Plug-Ins

• Developing and Administering 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 Processing Tasks

• Chains

• System and Custom Logic Plug-Ins

What Are Logic Plug-Ins?

Note: Custom Logic Plug-Ins are deprecated as of this release of WebLogic Integration. For information about the features that are replacing them, see the BEA WebLogic Integration Release Notes.

Logic plug-ins are Java classes that perform specialized processing of business messages as those messages pass through a B2B engine. They can be developed, as custom services, by WebLogic Integration providers or trading partners.

Logic plug-ins insert rules and business logic at strategic locations along the path traveled by business messages as they make their way through a WebLogic Integration B2B system. Logic plug-ins are instances of Java classes that are created when business protocols are created in WebLogic Integration. They are activated when a trading partner's delivery channel is started and invoked when a message passes through the B2B engine.

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

Logic Plug-In Processing Tasks

WebLogic Integration provides a router logic plug-in and a filter logic plug-in for supported business protocols. In addition to routing and filtering, custom logic plug-ins can perform a wide range of services. For example, for billing purposes, a custom logic plug-in can track the number of messages sent from each trading partner.

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

Table 3-1 Tasks Performed by Logic Plug-Ins

Task	Purpose	Examples
Route Modification	To change the list of intended recipients for a business message. Subject to conversation and collaboration agreement validation of the recipient. (This functionality is provided by WebLogic Integration B2B system 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	To examine the contents of a business message and take certain actions based on the results of the examination. (This functionality is provided by custom plug-ins.) Note: Most business messages that are examined do not include 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

Routers and filters consist of one or more logic plug-ins that are executed when a business message passes through the routers and filters. Multiple logic plug-ins that share the same business protocol are sequenced as a logic plug-in chain.

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

Note: The position of a logic plug-in in a chain is configured in the repository, through the WebLogic Integration B2B Console, as described in Online Help for the WebLogic Integration B2B Console.

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

Figure 3-1 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	System logic plug-in. WebLogic Integration provides this logic plug-in, which can modify the list of recipients for an XOCP business message based on XPath router expressions configured in the repository. This logic plug-in must be the first one in the XOCP router chain.
XOCP-MessageTracker	Custom logic plug-in. A WebLogic Integration owner or trading partner can provide such a custom logic plug-in to track the number of business messages sent from each trading partner for billing purposes.
XOCP-MessageInspector	Custom logic plug-in. A WebLogic Integration owner or trading partner can provide such a custom logic plug-in to examine and maintain statistics for the types of business documents being exchanged through the B2B engine (for example, purchase orders, invoices, and so on).
XOCP router enqueue	System logic plug-in. WebLogic Integration provides this logic plug-in, which enqueues the XOCP business message in an internal WebLogic Integration B2B router message queue. This logic plug-in must be the last one in the XOCP router chain.

 

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

System and Custom Logic Plug-Ins

To provide standard services for processing business messages, WebLogic Integration B2B offers the following logic plug-ins.

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. 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 Integration B2B router message queue. This system logic plug-in must be last in the XOCP router logic plug-in chain.
XOCP filter	Determines whether an XOCP business message is sent to a specific trading partner based on XPATH filter expressions configured in the repository. This system logic plug-in must be last in the XOCP filter logic plug-in chain.
RosettaNet router enqueue	Enqueues the RosettaNet business message in the WebLogic Integration B2B router message queue. This system logic plug-in must be last in the RosettaNet router logic plug-in chain.
RosettaNet filter	Determines whether a RosettaNet business message is sent to a specific trading partner. This system logic plug-in must be last in the RosettaNet filter logic plug-in chain.

 

In addition to using the system logic plug-ins, trading partners built on WebLogic Integration can develop their own custom logic plug-ins to provide specialized services. 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 Integration provides a logic plug-in API that allows WebLogic Integration B2B applications to:

• Add or remove target trading partners from the message recipient list when using XOCP multicast.

• 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 Integration Javadoc.

Table 3-4 Logic Plug-In API  

Class/Interface	Description
com.bea.b2b.protocol.PlugIn	Tagging interface that represents a generic logic plug-in, that is, code that can be inserted, for execution, into a router or a filter.
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. 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	The Message interface contains all of the information required for processing a business message in the WebLogic Integration B2B engine. It provides 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 nonXML 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.CAInstance	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 a party in a collaboration agreement. The available methods allow you to verify or retrieve information about the collaboration agreement party, such as the delivery channel used by it.
com.bea.b2b.tpa. TradingPartnerInstance	Represents a trading partner instance at run time. 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, 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, 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 logic plug-ins that are installed on WebLogic Integration are properly debugged and designed from a security perspective.

• A logic plug-in is always associated with at least one business protocol in the repository. The logic plug-in is triggered only when a business message that uses that protocol passes through the B2B engine. For example, a RosettaNet business message does not trigger an XOCP 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 Integration B2B 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 the B2B engine 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 B2B engine are shut down as well. The B2B engine and the delivery channel must be restarted.

  • If logic plug-in definitions change in the WebLogic Integration 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.

 

---

Developing and Administering Logic Plug-Ins

Implementing a custom logic plug-in requires a combination of development and administrative tasks. The following steps describe the required 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 the 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 the WebLogic Integration B2B engine

• 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 Integration 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 Integration 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 if a PlugInException is thrown, processing should not stop; it should continue to the next logic plug-in in the chain. Use this option to allow a business message to continue being processed even if an error occurs while the logic plug-in is being executed.
EXCEPTION_STOP	Indicates that if a PlugInException is thrown, processing should stop at this logic plug-in. 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 being processed further. For example, a logic plug-in that is validating business documents can reject any documents 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 B2B engine; 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 B2B application that sent the message 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 the 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 obtains the required information from the business message, it processes this information as necessary. 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 Integration B2B 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 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 B2B Integration and Online Help for the WebLogic Integration B2B Console.