Plug-In Development Fundamentals

This section describes the fundamental tasks required for plug-in development. It includes the following topics:

• Importing Packages and Interfaces

• Connecting to the Plug-In Manager

• Getting the Plug-In Framework Version

• Using Plug-In Value Objects

• Disconnecting from the Plug-In Manager

You may also want to review the following chapters in Programming BPM Client Applications:

• Accessing Process Engine Information - explains how to obtain information about the WebLogic Integration process engine

• Establishing JMS Connections - explains how to establish a connection to WebLogic Java Messaging Service (JMS)

• Understanding the BPM Transaction Model - explains how transactions are handled in BPM applications

 

---

Importing Packages and Interfaces

Import the BPM packages and interfaces, and general Java packages, as desired.

Review Importing Packages and Interfaces in Programming BPM Client Applications for a description of the packages and interfaces that you may import, including the following which are used for plug-in management:

• com.bea.wlpi.server.plugin.PluginManager interface

• com.bea.wlpi.server.plugin.PluginManagerCfg interface

• com.bea.wlpi.common.plugin package

 

---

Connecting to the Plug-In Manager

To connect to the BPM Plug-in Manager, use the PluginManager and/or PluginManagerCfg session EJBs.

As with any EJB, to access the PluginManager and/or PluginManagerCfg EJBs, you must use the home and remote interfaces. To do so, perform the following steps:

1. Look up a session EJB home interface in JNDI.

2. Create a remote session object (EJBObject) using the home interface.

Review Connecting to the Process Engine in Programming BPM Client Applications for a description of how to access API session EJBs (in this case the PluginManager and PluginManagerCfg EJBs).

The following code listing is an excerpt from the plug-in sample that shows how to connect to the Plug-in Manager through the following two-step procedure:

1. Create an initial context and use the JNDI context lookup() method to access the session EJB home interface.

2. Create a remote session object using the home interface.

This excerpt is taken from the SamplePluginBean.java file in the SAMPLES_HOME/integration/samples/bpm_api/plugin/src/com/bea/wlpi/tour/po/plugin directory. Notable lines of code are shown in bold.

Note: For more information about the initial context, see the javax.naming.InitialContext() Javadoc.

Listing 2-1 Connecting to the Plug-In Manager

    private final static String PLUGIN_MANAGER_CFG_HOME =
        "java:comp/env/ejb/PluginManagerCfg";    
     .
     .
     .
    private PluginManagerCfg getPluginManagerCfg() throws PluginException {

        PluginManagerCfg pm = null;
        InitialContext ic = null;

        try {
            ic = new InitialContext();

            PluginManagerCfgHome pmHome =
                (PluginManagerCfgHome)ic.lookup(PLUGIN_MANAGER_CFG_HOME);

            pm = pmHome.create();
        } catch (Exception e) {
            e.printStackTrace();

            throw new PluginException(SamplePluginConstants.PLUGIN_NAME,
                                      "Unable to get PluginManagerCfg");
        } finally {
            try {
                ic.close();
            } catch (Exception e) {
            }
        }

        return pm;
    }

For more information about the plug-in sample, see BPM Plug-In Sample.

 

---

Getting the Plug-In Framework Version

To get the plug-in framework version, use one of the following methods:

public com.bea.wlpi.common.VersionInfo com.bea.wlpi.server.plugin.PluginManager.getFrameworkVersion(
) throws java.rmi.RemoteException

public com.bea.wlpi.common.VersionInfo com.bea.wlpi.common.plugin.PluginInfo.getPluginFrameworkVersion(
) throws java.rmi.RemoteException

These methods return the Plug-in Manager version as a com.bea.wlpi.common.VersionInfo object. To obtain information about the version, use the VersionInfo object methods described in "VersionInfo Object" in Value Object Summary in Programming BPM Client Applications.

For example, the following code gets the Plug-in Manager version using the PluginManager object method and saves it to the version object. In the examples, pm represents the EJBObject reference to the PluginManager EJB:

VersionInfo version = pm.getFrameworkVersion();

For more information about the getFrameworkVersion() method, see the com.bea.wlpi.server.plugin.PluginManager Javadoc. For more information about the getPluginFrameworkVersion() method, see the com.bea.wlpi.common.plugin.PluginInfo Javadoc.

 

---

Using Plug-In Value Objects

The com.bea.wlpi.common.plugin package provides Info classes, or value objects, for obtaining plug-in object data at both definition time and run time. Using plug-in value objects, the process engine and BPM client applications request plug-in object data for a specified locale, enabling the plug-in to localize display strings and other resources appropriately.

Value objects play an important role in remote class loading on the design client. Specifically, the BPM design client uses value objects:

1. To retrieve, based on the plug-in component name and ID, the names of the Java classes included in the plug-in.

2. To initiate remote class loading on the design client, based on the returned values, to obtain an instance of the defined classes.

For more information about remote class loading, see Accessing the Plug-In Implementation.

The following table lists the value objects that can be used to create and use plug-in object data.

Table 2-1 Plug-In Value Objects  

Use this value object . . .	To access plug-in . . .
com.bea.wlpi.common.plugin.ActionCategoryInfo	Action or action category information.
com.bea.wlpi.common.plugin.ActionInfo	Action information.
com.bea.wlpi.common.plugin.CategoryInfo	Action category information.
com.bea.wlpi.common.plugin.ConfigurationData	Configuration data.
com.bea.wlpi.common.plugin.ConfigurationInfo	Configuration information.
com.bea.wlpi.common.plugin.DoneInfo	Done node information.
com.bea.wlpi.common.plugin.EventHandlerInfo	Event handler information.
com.bea.wlpi.common.plugin.EventInfo	Event node information.
com.bea.wlpi.common.plugin.FieldInfo	Message type information.
com.bea.wlpi.common.plugin.FunctionInfo	Evaluator function information.
com.bea.wlpi.common.plugin.HelpSetInfo	Online help information.
com.bea.wlpi.common.plugin.InfoObject	Abstract base class for all plug-in value objects.
com.bea.wlpi.common.plugin.PluginCapabilitiesInfo	Capabilities information.
com.bea.wlpi.common.plugin.PluginDependency	Dependency information.
com.bea.wlpi.common.plugin.PluginInfo	Basic plug-in information.
com.bea.wlpi.common.plugin.StartInfo	Start node information.
com.bea.wlpi.common.plugin.TemplateDefinitionPropertiesInfo	Template definition properties information.
com.bea.wlpi.common.plugin.TemplateNodeInfo	Template node (Done and Start) information.
com.bea.wlpi.common.plugin.TemplatePropertiesInfo	Template properties information.
com.bea.wlpi.common.plugin.VariableTypeInfo	Variable type information.

 

The following sections explain how to create and use value objects.

For more information about the value object constructors and the associated get and set methods, see Plug-In Value Object Summary. For a list of common characteristics shared by value objects, and an explanation of how to sort them, see Using Value Objects in Programming BPM Client Applications.

Defining Plug-In Value Objects

To define the plug-in value object, use the associated constructor. For each of the plug-in value objects described in the table Plug-In Value Objects, one or more constructors for creating object data are provided. The constructors for creating value objects are described in Plug-In Value Object Summary.

You must pass the plug-in value objects for each of the plug-in components when defining the com.bea.wlpi.common.plugin.PluginCapabilitiesInfo object. For details, see the description of the getPluginCapabilitiesInfo() method, in the table Remote Interface Plug-In Information Methods.

When creating a value object, you must specify:

• Plug-in ID, which must be unique for the plug-in and object type.

• Description of the plug-in features.

• Globally unique internal identifier, formed by appending one or more dot-separated strings to the vendor reverse-DNS name (for example, com.somedomain.someproduct.myplugin).

• Array containing the Java class names associated with the plug-in. The design client can retrieve this information using the plug-in name and ID, as described in Getting and Setting Object Data. Subsequently, the design client can initiate remote class loading to access the implementation classes. For more information about remote class loading, see Accessing the Plug-In Implementation.

• The icon used by the WebLogic Integration Studio to represent the plug-in when the interface view is enabled. Custom icons can be defined when you implement the home interface ejbCreate() method, as described in Plug-In Home Interface.

For example, the following code creates a StartInfo object and assigns the resulting object to si:

si = new StartInfo(SamplePluginConstants.PLUGIN_NAME, 5,
          bundle.getString("startOrderName"),
          bundle.getString("startOrderDesc"), ICON_BYTE_ARRAY,
          SamplePluginConstants.START_CLASSES, orderFieldInfo);

The START_CLASSES array defines the plug-in data, plug-in panel, and run-time component class names for the plug-in Start node. The START_CLASSES array is defined within the SamplePluginConstants.java class file as follows:

final static String[] START_CLASSES = { 
	START_DATA, 
	START_PANEL,
	START_NODE };

In this example, the array variable values are defined in the SamplePluginConstants.java file, as follows:

final static String START_NODE = 
	"com.bea.wlpi.tour.po.plugin.StartNode";
final static String START_DATA =
	"com.bea.wlpi.tour.po.plugin.StartNodeData";
final static String START_PANEL =
	"com.bea.wlpi.tour.po.plugin.StartNodePanel";

The ICON_BYTE_ARRAY variable specifies a byte array representation of the graphical image (icon) that is used by the Studio to represent the plug-in when the Studio interface view is enabled.

For more information about value object constructors and associated get and set methods, see Plug-In Value Object Summary.

Getting and Setting Object Data

Each plug-in value object described in the table Plug-In Value Objects provides various methods for getting and setting object data. These methods are described in Plug-In Value Object Summary.

For example, the following code gets the PluginTriggerPanel implementation class for a plug-in Start node and saves it to the startpanel string:

java.lang.String startpanel = si.getClassName(KEY_PANEL);

In this example, si represents a reference to the com.bea.wlpi.common.plugin.StartInfo value object for the plug-in Start node.

For more information about plug-in value object methods, see Plug-In Value Object Summary.

 

---

Disconnecting from the Plug-In Manager

To disconnect from the BPM Plug-in Manager, perform the following steps:

1. Remove session EJB references to make the system space available for use by other EJBs.

   For example, the following excerpt from the plug-in sample shows how to remove the PluginManagerCfg EJB reference. In this example, pm represents the EJBObject reference to the PluginMangerCfg EJB:

   try {
      if (pm != null)
      pm.remove();
   } catch (Exception e) {}

   For more information, see "Removing Session EJB References" in Disconnecting from the Process Engine in Programming BPM Client Applications.

2. Remove additional resources, including JMS connections (if applicable), and closing the context.

   For example, the following code closes the JNDI context resources:

   try {
       ic.close();
   { catch(Exception exp) {}

   For more information, see "Releasing Other Resources" in Disconnecting from the Process Engine in Programming BPM Client Applications