Building an Enterprise Archive (EAR)

Building an Enterprise Workflow Application based on the Imixs JEE Workflow components you typical start with an Enterprise Archive (EAR). An EAR splits the business logic (EJBs) and the users web frontend (WAR) into separate modules. Basically the structure of an EAR looks typical like this:

        /
        +- META-INF/
        |  |- application.xml
        |- my_ejb_module.jar
        |- my_web_module.war

As explained before there is no need to implement any EJB code if you are using the Imixs JEE Implementation. As all Imixs JEE components follow the JEE specification you can simply included them into the EAR. The following section describes the steps integrating the Imixs JEE Components into an Enterprise Archive (EAR).

Note:

There are different ways and scenarios how to deploy an enterprise application. The section below describes the most typical way for the deployment. You can also check out the sample application imixs-workflow-jsf-sample from the source code repository or generate a new project using the Imixs Maven archetype to get a quick start solution.

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.

Java Persistence API - persistence.xml

Finally you need to add a persistence.xml file into your ejb module. The persistence.xml file defines how the workitems managed by the Imixs Workflow Manager will be persisted into a database. To configure a database connection read the install section. So add one additional file into your ejb module named persistence.xml:

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

The persistence.xml descirbes the location of you database. The following example shows a typical configuration using the Eclipselink driver provided by most JEE Application servers.

<?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
        -->
        <!-- eclipselink -->
        <persistence-unit name="org.imixs.workflow.jee.jpa" transaction-type="JTA">     
                <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>    
                <jta-data-source>jdbc/workflow-db</jta-data-source>
                <jar-file>imixs-workflow-jee-2.1.0-SNAPSHOT.jar</jar-file>
                <properties>
                        <property name="eclipselink.ddl-generation"
                                value="create-tables" />
                        <property name="eclipselink.logging.level" value="INFO"/>
                </properties>                           
        </persistence-unit>     
</persistence>

Take care about the different settings used by the persistence.xml:

• persistence-unit:

  The persistence unit name is fixed defined by the Imixs JEE Workflow Implementation and need to be set to "org.imixs.workflow.jee.jpa" which is the package name of the Entity EJBs provided by the Imixs JEE Implementation.

• jta-data-source:

  The jta-data-source points to a JNDI Database resource located on the Application server. This JNDI Name is a JDBC Resource which is provided by the Application Server running the Application. In Glassfish Server a JDBC Resource can be defined in the Section Resources - JDBC

• jar-file:

  The jar-file defines the java library containing the Entity EJBs to be stored in the Database. This tag should always point to the imixs-workflow-jee Jar File. Take care about the version number used by your application.

In the example the jta-data-source point to a JDBC Ressource with the JNDI Name 'jdbc/workflow-db' and the jar-file points to the imixs-workflow-jee Implementation with the Version number 2.1.0-SNAPSHOT located in the root of your EAR.

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.

Maven

All Imixs JEE components are provided as maven artifacts. This makes it very easy to setup an Enterprise Application using the Imixs JEE components. Read the maven deplyoment section to see how an EAR can be build with maven.

Glassfish V2.1

If you are running on Glassfish V2.1 you need to take care about some additional configuration. Thesse configuration is explained in the JEE5 Deployment section.

Using shared libraries

In difference to the deplyoment example shown above you can deploy part of the Imixs JEE components as shared libraries into a EAR. In this case you put the jars into the /lib/ folder of your EAR. Jars deployed into the /lib folder of an ear are visible to all other modules and components. Exept for the imixs-jee-impl.jar you can place all Imixs jars into the lib. So in this case the EAR structure will look like this:

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

If you prefere this EAR layout you should care about the persistence.xml file in you ejb module as the JPA implementation is now located at '/lib/imixs-workflow-jee-2.1.0.jar'. On the other hand the EJB module now only needs to include the imixs-workflow-jee-impl-2.1.0.jar into the classpath. So the MANIFEST.MF file can be changed to:

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