Imixs Workflow ...the open source workflow technology for business applications

Engine

Deployment on Glassfish V2.1 (JEE5)

Deploying the Imixs JEE Workflow components on a JEE5 Server like Glassfish V2.1 differs in some details from the deployment on a JEE6 compliant server like Glassfish v3. So examine carefully the following hints if you are deploying the Imixs JEE components on a JEE5 Server. The following section will explain the additional configuration for an Imixs Enterprise Workflow Project to be deployed on Glassfish V2.1 (JEE5).

Note:
The configuration for other JEE5 application servers like glassfish will differ in some details. But most informations provided here should help deploying the Imixs components also on other JEE5 servers. Please provide your experience or ask your questions in the Imixs Forum.

Read the JEE5 / JBoss section for deployment introductions on JBoss Application Server 5.1

Packaging the Imixs JEE Component into an EAR

The first step is simple. Just copy the Imixs JEE components (JARs) into the root of your EAR structure. So you get the following file structure:

        /
        +- META-INF/
        |  |- application.xml
        |- my_ejb_module.jar
        |- my_web_module.war
        |- imixs-workflow-api-2.1.0.jar
        |- imixs-workflow-jee-2.1.0.jar
        |- imixs-workflow-jee-impl-2.1.0.jar
        |- imixs-workflow-rest-2.1.0.war
        |- imixs-workflow-xml-2.1.0.jar

The Imixs JEE Components are now part of the EAR. But the EJBs implemented in the imixs-workflow-jee-impl.jar will not be deployed until the components are included into an EJB module. So the next step is to configure your EJB module to use the Imixs JEE Workflow components.

Configuring the EJB Module

To get the Imixs JEE components be deployed together with your EJB module (my_ejb_module.jar) you simply add the components to the classpath of your EJB Module. This step makes the Imixs JEE components visible to all other EAR modules but it allows you also to specify server specific configurations like the JDBC/Database or the security realm by overwriting the default settings used by the Imixs JEE components.

So next we will configure the EJB Module. If you have not written any EJB code the EJB module of your EAR will look like this:

        /
        +- META-INF/
        |  |- MANIFEST.MF
        |  |- ejb-jar.xml

In the MANIFEST.MF file you can now declare additional component libraries to be used by the EJB module. Simply add the Class-Path definition to the META-INF/MANIFEST.MF file of your ejb module including all Imixs jar files.

Manifest-Version: 1.0
Class-Path: imixs-workflow-jee-impl-2.1.0-SNAPSHOT.jar imixs-workflow-jee-2.1.0-SNAPSHOT.jar imixs-workflow-api-2.1.0-SNAPSHOT.jar imixs-workflow-xml-2.1.0-SNAPSHOT.jar

This makes the Imixs Workflow EJBs part of your EJB module. The ejb-jar.xml included in your EJB module can be left empty as EJBs will be deployed automatically. But the ejb-jar.xml file gives you more control about the default behavior of the EJBs provided by the Imixs JEE components. For example if you want to define a 'run-as-principal' role to a ejb or a method. Or you would like to rename a ejb or inject a local jndi-mail or jndi-directory resource by name. In this cases you can do this now by overwriting the ejb-jar.xml which is located in your ejb module (my-ejb.jar) and which is under your control. This is the reason why we recommend to provide an empty EJB module including the Imixs JEE components.

ejb-jar.xml

Glassfish 2.1 did not parse provided jars automatically for EJB annotations. For this reason the EJB components provided in the imixs-workflow-jee-impl jar file will be ignored. To get the provided ejbs deployed successfully into the EJB container you need to provide an ejb-jar.xml descriptor declaring all included ejbs. So add the following ejb-jar.xml file into your EJB module.

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://java.sun.com/xml/ns/javaee" xmlns:ejb="http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
        version="3.0">
        
        <!-- Glassfish 2.1 descriptions are dispansable in JEE6 -->
        <enterprise-beans>
                <session>
                        <ejb-name>EntityServiceBean</ejb-name>
                        <ejb-class>org.imixs.workflow.jee.ejb.EntityServiceBean</ejb-class>
                        <session-type>Stateless</session-type>
                </session>      
                <session>
                        <ejb-name>ModelServiceBean</ejb-name>
                        <ejb-class>org.imixs.workflow.jee.ejb.ModelServiceBean</ejb-class>
                        <session-type>Stateless</session-type>
                </session>
                <session>
                        <ejb-name>WorkflowServiceBean</ejb-name>
                        <ejb-class>org.imixs.workflow.jee.ejb.WorkflowServiceBean</ejb-class>
                        <session-type>Stateless</session-type>
                </session>
                <session>
                        <ejb-name>ReportServiceBean</ejb-name>
                        <ejb-class>org.imixs.workflow.jee.ejb.ReportServiceBean</ejb-class>
                        <session-type>Stateless</session-type>
                </session>
                
                <session>
                        <ejb-name>WorkflowSchedulerBean</ejb-name>
                        <ejb-class>org.imixs.workflow.jee.ejb.WorkflowSchedulerBean</ejb-class>
                        <session-type>Stateless</session-type>
                </session>
                
        </enterprise-beans>

        <assembly-descriptor>
        </assembly-descriptor>
</ejb-jar>

The sun-ejb-jar.xml - optional

The sun-ejb-jar.xml is an optional deployment descriptor used by the Glassfish application server. This descriptor can be used to defin unique JNDI names for provided EJBs or define RunAs principals provided by the EJB container. The following example shows an typical configuration of the sun-jar.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 9.0 EJB 3.0//EN" "http://www.sun.com/software/appserver/dtds/sun-ejb-jar_3_0-0.dtd">
<sun-ejb-jar>
        <enterprise-beans>
                <!-- Imixs Workflow Service EJBs - JNDI Definition -->
                <ejb>
                        <ejb-name>EntityServiceBean</ejb-name>
                        <jndi-name> ejb/ImixsAppEntityServiceBean </jndi-name>
                </ejb>
                <!-- RunAs declaration -->
                <ejb>
                        <ejb-name>WorkflowSchedulerBean</ejb-name>
                        <principal>
                                <name>WorkflowScheduler</name>
                        </principal>
                </ejb>
        </enterprise-beans>
</sun-ejb-jar>

The descriptor defines a remote jndi name for the EntityService bean ( ejb/ImixsAppEntityServiceBean). This name can be used by the Imixs JEE Admin Client to access the Workflow engine remote, and the RunAs principal 'WorkflowScheduler' used by the Imxis Workflow Scheduler EJB.

Toplink JPA - persistence.xml

Glassfish V2.1 comes with the Toplink JPA provider. The newer Eclipselink JPA provider included in Glassfish V3 is not part of Glassfish V2.1. So the persistence.xml file provided in the ejb module should be configured with the toplink jpa Extensions to work properly . The following example shows the perstence.xml file to be used in glassfish v2.1:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence">
        <!--
                Imixs JPA definition Make sure that the imixs-workflow-jee library
                version maches the version provided by the EAR/EJB
        -->
        <!-- toplink -->
        <persistence-unit name="org.imixs.workflow.jee.jpa">
                <jta-data-source>jdbc/workflow-db</jta-data-source>
                <jar-file>lib/imixs-workflow-jee-2.1.0-SNAPSHOT.jar</jar-file>
                <properties>
                        <property name="toplink.ddl-generation"
                                value="create-tables" />
                </properties>
        </persistence-unit>
</persistence>
Note:
The jar-file property should match the imixs-workflow-jee jar provided by the EAR /lib folder.

Jersey support

The Imixs REST Web Service implementation is based on the JAX-RS Jersey implementation. JAX-RS and Jersey are not part of Glassfish V2.1. To provide the server with the necessary JAX-RS implementation it is necessary to add the jersey-core and jsr311-api to your Imixs Enterprise Workflow EAR.

This additional configuration can be done esyly using the following maven dependency configuration in the pom.xml of your EAR module.

....
        <build>
                <plugins>
                        <plugin>
                                <groupId>org.apache.maven.plugins</groupId>
                                <artifactId>maven-ear-plugin</artifactId>
                                <configuration>
                                        <version>5</version>
                                        <modules>
                                                ....
                                                ..........
                                                <!-- REST Service -->
                                                <webModule>
                                                        <groupId>org.imixs.workflow</groupId>
                                                        <artifactId>imixs-workflow-rest</artifactId>
                                                        <contextRoot>/workflow-rest</contextRoot>
                                                </webModule>

                                                .....
                                                <!-- Glassfish 2.1 - Jersey configuration  -->
                                                <JarModule>
                                                        <groupId>javax.ws.rs</groupId>
                                                        <artifactId> jsr311-api</artifactId>
                                                        <bundleDir>lib</bundleDir>
                                                </JarModule>
                                                <JarModule>
                                                        <groupId>com.sun.jersey</groupId>
                                                        <artifactId>jersey-server</artifactId>
                                                        <bundleDir>lib</bundleDir>
                                                </JarModule>

                                        </modules>
                                        .....
                        
        <dependencies>
                .......
                <!--
                        Glassfish 2.1 - Jersey configuration - these dependecies are only
                        necessary for jee5 - old versions 1.0
                -->

                <dependency>
                        <groupId>com.sun.jersey</groupId>
                        <artifactId>jersey-server</artifactId>
                        <version>1.3</version>
                </dependency>
       .......
        </dependencies>
......

If you are not using maven make sure hat your EAR provides the following shared libs:

  • jersey-sever-1.3.jar
  • jsr311-api-1.1.1.jar
  • asm-3.1.jar
  • jersey-core-1.3.jar