Deploying the Plug-In

Download Docs

Site Map

Glossary

e-docs > WebLogic Platform > WebLogic Integration > BPM Topics > Programming BPM Plug-Ins > Deploying the Plug-In

Programming BPM Plug-Ins

Deploying the Plug-In

A plug-in is a stateless session EJB. It is deployed like any other EJB. This section explains how to deploy the plug-in. It includes the following topics:

Note: For your convenience, the plug-in sample has been deployed for you. The plug-in sample JAR, WAR, and deployment descriptor files are copied to the appropriate directories upon installation.

Defining the Plug-In Deployment Descriptor Files

To deploy the plug-in, you must define the plug-in deployment descriptor files that define the EJB and/or online help deployment properties, as described in the following sections.

Defining the Plug-In EJB Deployment Descriptor Files

The following table lists the deployment descriptor files that you may need to define to deploy the plug-in EJB.

Table 9-1 Plug-In EJB Deployment Descriptor Files

Define the following file . . .	To specify . . .
ejb-jar.xml	Basic EJB structure, internal dependencies, and application assembly information.
weblogic-ejb-jar.xml	WebLogic Server caching, clustering, and performance information, and WebLogic Server resource mappings, including security, JDBC pool, JMS connection factory, and other deployed EJB resources.
weblogic-cmp-rdbms-jar.xml	WebLogic Server container-managed persistence services.

For more information about the EJB deployment descriptor files, see "Deploying EJBs in the EJB Container" in Programming WebLogic Enterprise Java Beans at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ejb/deploy.html

The following code listings provide excerpts from the plug-in sample showing how to define the ejb-jar.xml and weblogic-ejb-jar.xml deployment descriptor files.

Note: Plug-ins must support container-managed transaction demarcation. Therefore, the trans-attr element of the plug-in notification listener method must have a value of Required, Supports, or Mandatory.

Listing 9-1 Plug-In Sample ejb-jar.xml EJB Deployment Descriptor

<?xml version="1.0"?>

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_2_0.dtd">

<ejb-jar>
  <enterprise-beans>
    <session>
      <ejb-name>SamplePlugin</ejb-name>
      <home>com.bea.wlpi.server.plugin.PluginHome</home>
      <remote>com.bea.wlpi.server.plugin.Plugin</remote>
      <ejb-class>com.bea.wlpi.tour.po.plugin.SamplePluginBean</ejb-class>
      <session-type>Stateless</session-type>
      <transaction-type>Container</transaction-type>
      <ejb-ref>
        <ejb-ref-name>ejb/PluginManagerCfg</ejb-ref-name>
        <ejb-ref-type>Session</ejb-ref-type>
        <home>com.bea.wlpi.server.plugin.PluginManagerCfgHome</home>
        <remote>com.bea.wlpi.server.plugin.PluginManagerCfg</remote>
        <ejb-link>PluginManagerCfg</ejb-link>
      </ejb-ref>
    </session>
  </enterprise-beans>
  <assembly-descriptor>
    <container-transaction>
      <method>
        <ejb-name>SamplePlugin</ejb-name>
        <method-intf>Remote</method-intf>
        <method-name>*</method-name>
      </method>
      <trans-attribute>Required</trans-attribute>
    </container-transaction>
  </assembly-descriptor>
</ejb-jar>

Listing 9-2 Plug-In Sample weblogic-ejb-jar.xml EJB Deployment Descriptor

<?xml version="1.0"?>

<!DOCTYPE weblogic-ejb-jar PUBLIC "-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN" "http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd">

<weblogic-ejb-jar>
  <weblogic-enterprise-bean>
    <ejb-name>SamplePlugin</ejb-name>
    <stateless-session-descriptor>
      <pool>
        <max-beans-in-free-pool>100</max-beans-in-free-pool>
        <initial-beans-in-free-pool>0</initial-beans-in-free-pool>
      </pool>
      <stateless-clustering>
        <stateless-bean-is-clusterable>True</stateless-bean-is-clusterable>
        <stateless-bean-methods-are-idempotent>True</stateless-bean-methods-are-idempotent>
      </stateless-clustering>
    </stateless-session-descriptor>
    <reference-descriptor>
      <ejb-reference-description>
        <ejb-ref-name>ejb/PluginManagerCfg</ejb-ref-name>
        <jndi-name>com.bea.wlpi.PluginManagerCfg</jndi-name>
      </ejb-reference-description>
    </reference-descriptor>
    <jndi-name>com.bea.wlpi.tour.po.plugin.SamplePlugin</jndi-name>
  </weblogic-enterprise-bean>
</weblogic-ejb-jar>

Defining the Plug-In Online Help Deployment Descriptor Files

The following table lists the deployment descriptor files that you may need to define to deploy the plug-in online help.

Table 9-2 Plug-In Online Help Deployment Descriptor Files

Define the following file . . .	To specify . . .
web.xml	Web application configuration information.
weblogic.xml	Resource mapping information for named resources in the web.xml file and resources residing elsewhere in WebLogic Server; and JSP and HTTP session attributes.

For more information about the online help (web application) deployment descriptor files, see "Writing WebApplication Deployment Descriptors" in Assembling and Configuring Web Applications at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/webapp/webappdeployment.html

The following code listings provide excerpts from the plug-in sample showing how to define the web.xml and weblogic.xml deployment descriptor files.

Listing 9-3 Plug-In Sample Online Help web.xml Deployment Descriptor

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
    <display-name>Sample Plugin Online Help</display-name>
    <description>
        This Web Application serves up HTML Help for the
        WebLogic Process Integrator Sample Plugin.
    </description>
    <welcome-file-list>
    <welcome-file>
        com/bea/wlpi/tour/po/plugin/htmlhelp/index.htm
    </welcome-file>
    </welcome-file-list>
</web-app>

Listing 9-4 Plug-In Sample Online Help weblogic.xml Deployment Descriptor

<!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 6.0//EN" "http://www.bea.com/servers/wls600/dtd/weblogic-web-jar.dtd">
<weblogic-web-app>
    <description>
        This Web Application serves up HTML Help for the
        WebLogic Process Integrator Sample Plugin.
    </description>
</weblogic-web-app>

Packaging the Plug-In

To package the plug-in in a JAR file that will be deployed to the WebLogic Server, perform the following steps:

Create the build directory and compile the source files into this directory using javac.

For the plug-in sample, the source files are located in the SAMPLES_HOME/integration/samples/bpm_api/plugin/src/com/bea/wlpi/tour/po/plugin directory and are compiled into the SAMPLES_HOME/integration/samples/bpm_api/plugin directory.
Copy the deployment descriptors (ejb-jar.xml, weblogic-ejb-jar.xml), created in the previous section, into a subdirectory called META-INF in the build directory.

For example, copy the deployment descriptor files to the SAMPLES_HOME/integration/samples/bpm_api/plugin/META-INF directory.
Create a JAR file of the build directory, including the compiled source files and deployment descriptors.

For the plug-in sample, the resulting JAR file is stored as SAMPLES_HOME/integration/samples/lib/sampleplugin-ejb.jar.
Run weblogic.ejbc on the JAR file to generate the WebLogic Server container classes.

For the plug-in sample, the output of this utility is stored in the SAMPLES_HOME/integration/samples/bpm_api/plugin/ejbcgen directory.
Optionally, create a WAR file containing the plug-in online help and deployment descriptor files.

For the plug-in sample, the plug-in online help files are stored in the SAMPLES_HOME/integration/samples/bpm_api/plugin/htmlhelp directory. The resulting WAR file is stored as SAMPLES_HOME/integration/samples/lib/sampleplugin.war.

The following code listing is an excerpt from the plug-in sample that shows how to define a build script, build.cmd, to package the plug-in. This file is located in the SAMPLES_HOME/integration/samples/bpm_api/plugin directory. Notable lines of code are shown in bold.

Note: Before running the build.cmd script, you must update and run the setEnv.cmd script to set the environment. This script is located in the SAMPLES_HOME/integration/samples/bpm_api/plugin directory.

Listing 9-5 Plug-In Sample Build Script

@rem Copyright (c) 2001 BEA Systems, Inc. All rights reserved.
@rem build.cmd - compile and create the sampleplugin deployable jar file.
@echo off


@rem Compile classes
setlocal
set JAVAC_ARGS=-d . -g -deprecation
echo Compiling Sample Plugin classes
"%JAVA_HOME%\bin\javac" %JAVAC_ARGS% source\*.java
endlocal

@rem Create jar
echo Building Sample Plugin EJB jar for bean classes
erase /f _sampleplugin-ejb.jar 2> nul 1> nul
@copy interfaces.jar _sampleplugin-ejb.jar 2> nul 1> nul
@copy source\Sample.gif com\bea\wlpi\tour\po\plugin\Sample.gif 2> nul 1> nul
@copy source\SamplePlugin.properties com\bea\wlpi\tour\po\plugin\SamplePlugin.properties 2> nul 1> nul
@rem Add the standard and vendor-specific XML deployment descriptors.
"%JAVA_HOME%\bin\jar" -uf _sampleplugin-ejb.jar META-INF\ejb-jar.xml META-INF\weblogic-ejb-jar.xml
rem Add the bean implementation classes, and helper classes.
"%JAVA_HOME%\bin\jar" -uf _sampleplugin-ejb.jar com
dir /b _sampleplugin-ejb.jar

echo Compiling EJB container classes

erase /f sampleplugin-ejb.jar 2> nul 1> nul
"%JAVA_HOME%\bin\java" -Dweblogic.ejb20.ejbc.debug=1 weblogic.ejbc -compiler "%JAVA_HOME%\bin\javac" _sampleplugin-ejb.jar sampleplugin-ejb.jar
dir /b sampleplugin-ejb.jar
if not exist sampleplugin-ejb.jar echo *** ERROR: ejbc failed to create the sampleplugin-ejb.jar file.


echo Building Sample Plugin WAR file for JavaHelp/HTML Help
"%JAVA_HOME%\bin\jar" -cf sampleplugin.war WEB-INF
"%JAVA_HOME%\bin\jar" -uf sampleplugin.war htmlhelp
dir /b sampleplugin.war
if not exist sampleplugin.war echo *** ERROR: failed to create the sampleplugin.war file.

del _sampleplugin-ejb.jar
echo Done.

Updating the Configuration File

To deploy the plug-in, you must update the configuration file, config.xml, to specify the associated deployment descriptor files as part of the WebLogic Integration application.

To specify the plug-in EJB descriptor files, use the <EJBComponent> element. You can control the order in which the EJB JAR files are deployed using the DeploymentOrder attribute. In general, if plug-in A is dependent upon plug-in B, then plug-in B must be deployed first. The BPM plug-in framework ultimately dictates the order in which plug-ins are loaded. For example, if the plug-in framework attempts to load plug-in A, and plug-in A is dependent upon plug-in B, which is not yet loaded, the plug-in framework will load plug-in B.

To specify the plug-in online help files, use the <WebAppComponent> element. You must set the Name attribute to the value of the pluginName parameter of the com.bea.wlpi.common.plugin.HelpSetInfo object, which is set when you are defining the plug-in online help. For more information about defining plug-in online help, see Defining Plug-In Online Help.

The following code listing is excerpted from the samples domain config.xml showing the information required to deploy the plug-in sample. This file is located in the SAMPLES_HOME/config/samples directory. Notable lines of code are shown in bold.

Listing 9-6 Deploying the Plug-In Sample EJB in the config.xml File

     .
     .
     .
<Application Deployed="true" Name="WLI" Path="E:\bea\weblogic600\samples\integration\samples\lib">
   <EJBComponent DeploymentOrder="0" Name="repository-ejb.jar"
      Targets="myserver" URI="repository-ejb.jar"/>
   <WebAppComponent Name="XTPlugin" Targets="myserver" URI="wlxtpi.war"/>
   <WebAppComponent Name="wlai" ServletReloadCheckSecs="1"
      Targets="myserver" URI="wlai.war"/>
   <EJBComponent DeploymentOrder="2" Name="wlpi-master-ejb.jar"
      Targets="myserver" URI="wlpi-master-ejb.jar"/>
   <EJBComponent DeploymentOrder="1" Name="wlpi-ejb.jar"
      Targets="myserver" URI="wlpi-ejb.jar"/>
   <EJBComponent DeploymentOrder="4" Name="wlc-wlpi-plugin.jar"
      Targets="myserver" URI="wlc-wlpi-plugin.jar"/>
   <EJBComponent DeploymentOrder="8" Name="wlai-admin-ejb"
      Targets="myserver" URI="wlai-admin-ejb.jar"/>
   <EJBComponent DeploymentOrder="5" Name="pobean.jar"
      Targets="myserver" URI="pobean.jar"/>
   <WebAppComponent Name="b2bconsole" ServletReloadCheckSecs="1"
      Targets="myserver" URI="b2bconsole.war"/>
   <EJBComponent DeploymentOrder="3" Name="wlpi-mdb-ejb.jar"
      Targets="myserver" URI="wlpi-mdb-ejb.jar"/>
   <EJBComponent DeploymentOrder="7" Name="wlai-ejb-server"
      Targets="myserver" URI="wlai-ejb-server.jar"/>
   <EJBComponent DeploymentOrder="6" Name="wlxtpi.jar"
      Targets="myserver" URI="wlxtpi.jar"/>
   <EJBComponent DeploymentOrder="9" Name="wlaiplugin-ejb.jar"
       Targets="myserver" URI="wlaiplugin-ejb.jar"/>
   <WebAppComponent Name="WLAIPlugin" Targets="myserver" URI="wlai-plugin.war"/>
   <EJBComponent DeploymentOrder="10" Name="sampleplugin-ejb.jar"
       Targets="myserver" URI="sampleplugin-ejb.jar"/>
   <WebAppComponent Name="com.bea.wlpi.SamplePlugin"
      Targets="myserver" URI="sampleplugin.war"/>
</Application>
     .
     .
     .

Note in the previous example that the wlpi-master-ejb.jar file, which contains the Plug-in Manager, is deployed before the plug-in sample file, sampleplugin-ejb.jar. The plug-in sample references the Plug-in Manager, which defines a dependency and, therefore, must be deployed after the Plug-in Manager file.

For more information about updating the config.xml file, see BEA WebLogic Server Configuration Reference at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/config_xml/index.html