bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming BPM Plug-Ins

Managing Plug-Ins

This section explains how to manage plug-ins. It includes the following topics:

- Viewing Plug-Ins

- Loading Plug-Ins

- Configuring Plug-Ins

- Refreshing the List of Plug-Ins

- Using the Studio to Manage Plug-ins

Viewing Plug-Ins

To view installed plug-ins, use the com.bea.wlpi.server.plugin.PluginManager interface methods defined in the following table.

Table 7-1 PluginManager Interface Methods for Viewing Installed Plug-Ins

Method | Description
--- | ---
public com.bea.wlpi.common.plugin.PluginInfo getPlugin(java.lang.String pluginName, java.util.Locale lc) throws java.rmi.RemoteException, com.bea.wlpi.common.WorkflowException | Gets the localized, basic information for the specified plug-in. The method parameters are defined as follows. pluginName: java.lang.String object that specifies the plug-in name. lc: java.util.Locale object that specifies a locale in which to localize display strings. This method returns a com.bea.wlpi.common.plugin.PluginInfo object that specifies the basic plug-in information. For more information, see PlugInfo Object.
public com.bea.wlpi.common.plugin.PluginInfo[] getPlugins(java.util.Locale lc) throws java.rmi.RemoteException, com.bea.wlpi.common.WorkflowException | Gets a list of installed plug-ins for the specified locale. The method parameter is defined as follows. lc: java.util.Locale object that specifies a locale in which to localize display strings. This method returns an array of com.bea.wlpi.common.plugin.PluginInfo objects that specify the installed plug-ins. For more information, see PlugInfo Object.

For example, the following code gets a list of installed plug-ins for the specified locale, lc, and saves the list to the plugins[] array. In this example, pm represents the EJBObject reference to the PluginManager EJB.

>     plugins[]=pm.getPlugins(lc);

For more information about the getPlugin() and getPlugins() methods, see the com.bea.wlpi.server.plugin.PluginManager Javadoc.

Loading Plug-Ins

To load an installed plug-in, use the com.bea.wlpi.server.plugin.PluginManagerCfg interface method defined in the following table.

Table 7-2 PluginManager Interface Method for Loading an Installed Plug-In

Method | Description
--- | ---
public void loadPlugin(java.lang.String pluginName, com.bea.wlpi.commonVersionInfo version) throws java.rmi.RemoteException, com.bea.wlpi.common.WorkflowException | Loads and initializes the specified plug-in. The Plug-in Manager merges the capabilities of the plug-in with those of the currently loaded plug-ins. The method parameters are defined as follows. pluginName: java.lang.String object that specifies the plug-in name. version: com.bea.wlpi.common.VersionInfo object that specifies the Plug-in Manager version. For information about accessing the Plug-in Manager version, see Getting the Plug-In Framework Version.

For example, the following code loads the plug-in, MyPlugin, for the specified Plug-in Manager version, version. In this example, pmCfg represents the EJBObject reference to the PluginManager EJB.

>     pmCfg.getPlugins(MyPlugin, version);

For more information about the loadPlugin() method, see the com.bea.wlpi.server.plugin.PluginManagerCfg Javadoc.

Configuring Plug-Ins

By default, when configuring the plug-in you can specify the plug-in start mode.

For example, the following figure shows the default plug-in configuration dialog in the WebLogic Intergration Studio.

Figure 7-1 Default Plug-In Configuration Dialog in the Studio

The start mode can be set to one of the following values:

- Automatic: started automatically at system startup. This is the default.

- Manual: must be started manually by a user.

- Disabled: disabled and cannot be started.

For information about accessing the plug-in configuration dialog, see "Configuring Plug-Ins" in Configuring Workflow Resources in Using the WebLogic Integration Studio.

If required, you can customize the plug-in configuration requirements. The customized plug-in configuration requirements appear in place of the text Plugin defined data are not available shown in the previous figure.

The following sections explain how to customize plug-in configuration requirements and edit configuration values using the plug-in API, including the following topics:

- Customize the Plug-In Configuration Requirements

- Setting the Plug-In Configuration Values

- Getting the Plug-In Configuration Values

- Deleting the Plug-In Configuration Values

Customize the Plug-In Configuration Requirements

The following sections describe the steps required to customize the plug-in configuration requirements, including the following topics:

- Implementing the PluginData Interface

- Defining the PluginPanel Class

- Defining the ConfigurationInfo Value Object

Implementing the PluginData Interface

To read (parse) and save plug-in data in XML format, implement the plug-in data interface, as described in Implementing the PluginData Interface.

The following code listing shows how to define a class that implements the PluginData interface for the plug-in configuration. Notable lines of code are shown in bold.

Note: This class is not available as part of the plug-in sample.

Listing 7-1 Implementing the PluginData Interface—Plug-In Configuration

>     package com.bea.wlpi.test.plugin;

>     import java.io.IOException;
>     import com.bea.wlpi.common.plugin.PluginData;
>     import com.bea.wlpi.common.XMLWriter;
>     import java.util.List;
>     import java.util.Map;
>     import org.xml.sax.*;

>     public class ConfigData implements PluginData {
>         private static final String YESORNO_TAG = "yesorno";

>         private String yesOrNo;
>         private transient String lastValue;

>         public ConfigData() {
>             this.yesOrNo = TestPluginConstants.CONFIG_NO;
>         }

>         public ConfigData(String yesOrNo) {
>             this.yesOrNo = yesOrNo;
>         }

>         public void load(XMLReader parser) {
>         }

>         void setYesOrNo(String decision) {
>             yesOrNo = decision;
>         }

>         String getYesOrNo() {
>             return yesOrNo;
>         }

>         public void setDocumentLocator(Locator locator) {
>         }

>         public void startDocument()
>             throws SAXException {
>         }

>         public void endDocument()
>             throws SAXException {
>         }

>         public void startPrefixMapping(String prefix, String uri)
>             throws SAXException {
>         }

>         public void endPrefixMapping(String prefix)
>             throws SAXException {
>         }

>         public void startElement(String namespaceURI, String localName, String qName, Attributes atts)
>             throws SAXException {
>             lastValue = null;
>         }

>         public void endElement(String namespaceURI, String localName, String name)
>             throws SAXException {
>             if (name.equals(YESORNO_TAG))
>                 yesOrNo = lastValue;
>         }

>         public void characters(char[] ch, int start, int length)
>             throws SAXException {
>             String value = new String(ch, start, length);

>             if (lastValue == null)
>                 lastValue = value;
>             else
>                 lastValue = lastValue + value;
>         }

>         public void ignorableWhitespace(char[] ch, int start, int length)
>             throws SAXException {
>         }

>         public void processingInstruction(String target, String data)
>             throws SAXException {
>         }

>         public void skippedEntity(String name)
>             throws SAXException {
>         }

>         public void save(XMLWriter writer, int indent) throws IOException {
>             writer.saveElement(indent, YESORNO_TAG, yesOrNo);
>         }

>         // TODO:
>         public List getReferencedPublishables(Map publishables) {
>             return null;
>         }

>         public String getPrintableData() {
>             return toString();
>         }

>         public String toString() {
>             return "ConfigData[yesOrNo=" + yesOrNo + ']';
>         }

>         public Object clone() {
>             return new ConfigData(yesOrNo);
>         }
>     }

Defining the PluginPanel Class

To display the plug-in GUI component within the design client, define a class that extends the plug-in panel class, as described in Defining the PluginPanel Class.

The following code listing shows how to define a class for the plug-in configuration that extends the PluginPanel class. Notable lines of code are shown in bold.

Note: This class is not available as part of the plug-in sample.

Listing 7-2 Defining the PluginPanel Class—Plug-In Configuration

>     package com.bea.wlpi.test.plugin;

>     import java.awt.*;
>     import javax.swing.*;
>     import javax.swing.border.TitledBorder;
>     import javax.swing.border.EtchedBorder;
>     import java.util.List;
>     import java.util.Locale;
>     import com.bea.wlpi.common.plugin.PluginPanel;
>     import com.bea.wlpi.common.plugin.PluginPanelContext;
>     import com.bea.wlpi.client.studio.Studio;
>     import com.bea.wlpi.common.VariableInfo;

>     public class ConfigPanel extends PluginPanel {

>         JPanel ButtonPanel = new JPanel();
>         ButtonGroup YesNoButtonGroup = new ButtonGroup();
>         JRadioButton YesButton = new JRadioButton();
>         JRadioButton NoButton = new JRadioButton();
>         TitledBorder titledBorder = new TitledBorder(new EtchedBorder());

>         public ConfigPanel() {
>             super(Locale.getDefault(), "halloween");
>     //        super(Locale.getDefault(), "pgconfig");
>             //TODO: Create resource bundle for strings
>             setLayout(null);
>             setBounds(12,12,420,300);
>             ButtonPanel.setBorder(titledBorder);
>             ButtonPanel.setLayout(null);
>             add(ButtonPanel);
>             ButtonPanel.setBounds(72,60,300,144);
>             YesButton.setText("JavaHelp");
>             YesButton.setSelected(true);
>             YesNoButtonGroup.add(YesButton);
>             ButtonPanel.add(YesButton);
>             YesButton.setBounds(60,36,100,23);
>             NoButton.setText("HTML Help");
>             YesNoButtonGroup.add(NoButton);
>             ButtonPanel.add(NoButton);
>             NoButton.setBounds(60,60,100,23);
>             titledBorder.setTitle("Online Help");
>         }

>         public void load() {
>             ConfigData myData = (ConfigData)getData();
>             if (myData != null) {
>                 if (myData.getYesOrNo().equals(TestPluginConstants.CONFIG_NO)) {
>                     NoButton.setSelected(true);
>                 } else {
>                     YesButton.setSelected(true);
>                 }
>             }
>         }

>         public boolean validateAndSave() {
>             ConfigData myData = (ConfigData)getData();
>             if (myData != null) {
>                 myData.setYesOrNo(YesButton.isSelected()
>                                   ? TestPluginConstants.CONFIG_YES
>                                   : TestPluginConstants.CONFIG_NO);
>             }
>             return true;
>         }
>     }

Defining the ConfigurationInfo Value Object

To further define the plug-in component data, define a com.bea.wlpi.common.plugin.ConfigurationInfo value object for the plug-in configuration. You can then pass the ConfigurationInfo object using the config parameter to the com.bea.wlpi.common.plugin.PluginInfo value object, when defining the basic plug-in information.

If you set the config parameter to null when defining the PluginInfo value object, no plug-in specific configuration is defined. In this case, the plug-in configuration dialog in the Studio will appear as in the figure Default Plug-In Configuration Dialog in the Studio. For more information about defining the PluginInfo value object, see PlugInfo Object.

For example, the following code listing shows how to define a ConfigurationInfo value object.

>     ci = new ConfigurationInfo(TestPluginConstants.PLUGIN_NAME, 12,
>          "test plugin configuration",
>          TestPluginConstants.CONFIG_CLASSES);

The CONFIG_CLASSES field element value is listed within the TestPluginConstants.java class file, and defines the classes as follows:

>     final static String CONFIG_DATA =
>         "com.bea.wlpi.test.plugin.ConfigData";

>     final static String CONFIG_PANEL =
>         "com.bea.wlpi.test.plugin.ConfigPanel";
>     final static String[] CONFIG_CLASSES = {
>         CONFIG_DATA, CONFIG_PANEL
>     };

For more information about the ConfigurationInfo, see ConfigurationInfo Object.

Setting the Plug-In Configuration Values

To set the plug-in configuration values, use the com.bea.wlpi.server.plugin.PluginManagerCfg interface method defined in the following table.

Table 7-3 PluginManagerCfg Interface Method for Setting Configuration Values

Method | Description
--- | ---
public void setPluginConfiguration(java.lang.String pluginName, com.bea.wlpi.common.VersionInfo version, int startMode, java.lang.String config) throws java.rmi.RemoteException, com.bea.wlpi.common.WorkflowException | Sets the plug-in configuration information. The method parameters are defined as follows. pluginName: java.lang.String object that specifies the plug-in name. version: com.bea.wlpi.common.VersionInfo object that specifies the Plug-in Manager version. For information about accessing the Plug-in Manager version, see Getting the Plug-In Framework Version. startMode: Integer value that specifies when the Plug-in Manager starts the plug-in. This value can be set to one of the following com.bea.wlpi.common.plugin.PluginConstants values: MODE_AUTOMATIC: plug-in is started automatically at system startup. MODE_DISABLED: plug-in is disabled and cannot be started. MODE_MANUAL: plug-in must be started manually by a user. config: java.lang.String object that specifies the plug-in configuration information as an XML document.

For example, the following code sets the plug-in configuration information using the pconfig.xml file for MyPlugin plug-in, the specified Plug-in Manager version, version, and the MODE_AUTOMATIC start mode. In this example, pmCfg represents the EJBObject reference to the PluginManagerCfg EJB.

>     pmCfg.setPluginConfiguration(MyPlugin, version, MODE_AUTOMATIC,
>       pconfig.xml);

For more information about the setPluginConfiguration() method, see the com.bea.wlpi.server.plugin.PluginManagerCfg Javadoc.

Getting the Plug-In Configuration Values

To get the plug-in configuration values, use the com.bea.wlpi.server.plugin.PluginManager interface method defined in the following table.

Table 7-4 PluginManager Interface Method for Getting Configuration Values

Method | Description
--- | ---
public com.bea.wlpi.common.plugin.ConfigurationData getPluginConfiguration(java.lang.String pluginName, com.bea.wlpi.common.VersionInfo version) throws java.rmi.RemoteException, com.bea.wlpi.common.WorkflowException | Gets the plug-in configuration information. The method parameters are defined as follows. pluginName: java.lang.String object that specifies the plug-in name. version: com.bea.wlpi.common.VersionInfo object that specifies the Plug-in Manager version. For information about accessing the Plug-in Manager version, see Getting the Plug-In Framework Version. This method returns a com.bea.wlpi.common.plugin.ConfigurationData object that specifies the configuration information. For more information about the methods that you can use to access specific configuration information, see ConfigurationData Object.

For example, the following code gets the plug-in configuration information for MyPlugin and the specified Plug-in Manager version, version. In this example, pm represents the EJBObject reference to the PluginManager EJB.

>     configData=pm.setPluginConfiguration(MyPlugin, version);

For more information about the getPluginConfiguration() method, see the com.bea.wlpi.server.plugin.PluginManager Javadoc.

Deleting the Plug-In Configuration Values

You can delete a configuration for the plug-in if you no longer need the configuration. When you delete a configuration, you do not delete the plug-in itself, just its registered configuration.

To delete the plug-in configuration values, use the com.bea.wlpi.server.plugin.PluginManagerCfg interface method defined in the following table.

Table 7-5 PluginManagerCfg Interface Methods for Deleting Configuration Values

Method | Description
--- | ---
public void deletePluginConfiguration( java.lang.String pluginName, com.bea.wlpi.common.VersionInfo version) throws java.rmi.RemoteException, com.bea.wlpi.common.WorkflowException | Deletes the plug-in configuration information. The method parameters are defined as follows. pluginName: java.lang.String object that specifies the plug-in name. version: com.bea.wlpi.common.VersionInfo object that specifies the Plug-in Manager version. For information about accessing the Plug-in Manager version, see Getting the Plug-In Framework Version.

For example, the following code deletes the plug-in configuration values for MyPlugin and the specified Plug-in Manager version, version. In this example, pmCfg represents the EJBObject reference to the PluginManagerCfg EJB.

>     pmCfg.deletePluginConfiguration(MyPlugin, version);

For more information about the deletePluginConfiguration() method, see the com.bea.wlpi.server.plugin.PluginManagerCfg Javadoc.

Refreshing the List of Plug-Ins

To refresh the list of plug-ins, use the com.bea.wlpi.server.plugin.PluginManagerCfg interface method defined in the following table.

Table 7-6 PluginManagerCfg Interface Method for Refreshing the List of Plug-Ins

Method | Description
--- | ---
public void refresh() throws java.rmi.RemoteException, com.bea.wlpi.common.WorkflowException | Refreshes plug-in information in the cache. Note: Due to the amount of resources required to execute this method, its use should be limited. This method causes the Plug-in Manager to re-query all loaded plug-ins and rebuild its internal plug-in capabilities cache. Plug-ins can call this method if their capabilities are dynamically configured.

For example, the following code refreshes all loaded plug-ins. In this example, pmCfg represents the EJBObject reference to the PluginManager EJB.

>     pmCfg.refresh();

For more information about the refresh() method, see the com.bea.wlpi.server.plugin.PluginManagerCfg Javadoc.

Using the Studio to Manage Plug-ins

You can view, load, and configure plug-ins from within the Studio design client interface. For more information, see Configuring Workflow Resources in Using the WebLogic Integration Studio.