The Danet Workflow Component

The specified workflow APIs (packages de.danet.an.workflow.omgcore and de.danet.an.workflow.api, see Section 3.2, “Client API”) are packaged in a separate jar de.danet.an.wfcore-apis.jar located in the distribution directory $DIST/lib/wfcore. Only this JAR file should be used in the classpath when compiling clients. Consequently, it must also be included in the runtime classpath of a client.

The runtime-classes needed by a client that wants to use the workflow component are provided as de.danet.an.wfcore-client.jar in $DIST/lib/wfcore. This JAR file is not self contained, i.e. it relies on the presence of the workflow APIs (de.danet.an.wfcore-apis.jar), the Danet AN utility classes (de.danet.an.util.jar, see following section) and the additional libraries described in Section 1.3.6, “Additional libraries”. In addition, the client needs some information about how to contact the server. See the description of the basic WorkflowServiceFactory (in Section A.2.51, “Class WorkflowServiceFactory”), the description of the WfMOpen specific factory implementation (in de.danet.an.workflow.ejbs.client.StandardWorkflowServiceFactory) and the remarks in Section 1.3.4, “Workflow module” below.

All J2EE based software from the division AN uses a library with some common utility objects and components. This library is supplied as de.danet.an.util.jar (again located in the $DIST/lib/wfcore). Some components in this library (currently the logging service) need server side support. This support is provided by the corresponding EJB module described below.

The Danet AN utility library (package de.danet.an.util) is a general library used at our site. This library is packaged as two JAR files. By default, classes are in de.danet.an.util.jar. Some classes in the package (sub-package de.danet.an.util.jsf), however, are helper classes for JSF based portlets. These classes are are not included in de.danet.an.util.jar. They can be found in de.danet.an.util-jsf.jar. The reason for separating those classes is that they may not be put in the common classpath of a J2EE application. In order to avoid classpath problems, you have to put these JSF utility classes in the same directory as the JSF libraries (usually the WEB-INF/lib directory of your web module). Note that the classes from de.danet.an.util.jsf are only needed by the portlets that come with the workflow component. The deployment of the workflow EJBs requires de.danet.an.util.jar only.

The central (server side) workflow component is an EJB-type J2EE module. This module is not self contained, i.e. it relies on the presence of the workflow APIs, the Danet AN utility library and the additional libraries listed below. The module is located in the distribution directory $DIST/lib/wfcore as de.danet.an.wfcore-ejbs.jar.

The manifest file of de.danet.an.wfcore-ejbs.jar includes in its Class-Path: statement the entries lib/de.danet.an.wfcore-apis.jar and lib/de.danet.an.util.jar. Thus, the dependencies between the workflow module, the workflow APIs and the Danet AN utility library will be resolved automatically if de.danet.an.util.jar is put in the lib/ directory of the enterprise archive (the .ear-file).

As described above, all J2EE based software from the division AN uses some common utility objects and components. While most of these elements can be simply supplied as a library, some components (currently the logging support) consist of a client and a server part. The J2EE server side elements are packaged in the distinct EJB-type J2EE module de.danet.an.util-ejbs.jar that is also located in the $DIST/lib/wfcore distribution directory. This module must be deployed along with the workflow module.

As the utility module is intended to be used in several applications, we have deliberately not defined defaults for some information needed during deployment. Providing defaults for these values would imply the risk that different applications inadvertently access each others utility EJBs. Instead of defaults we use symbolic names in the deployment descriptors that can reliably be replaced automatically.

All symbolic names are described below. The description should be sufficient to allow you to adapt the deployment descriptors for your application. For more information about these EJBs, see the maintenance manual.

The symbolic names used are:

As distributed, the utility module's descriptors do not specify any security constraints. We do, however, strongly recommend adding such constraints as appropriate for an application's security domain when assembling the application^[6]. A common configuration is to introduce the same security role as used for the workflow engine EJBs (i.e. "WfMOpenAdmin", see Section 1.3.4, “Workflow module”) and allow this role to execute all methods.

The module includes support for executing the required adaptions. See Section 1.4.1, “Preparing the modules” for details.

As is usually the case with complex Java applications, the workflow component needs some third party libraries in addition to the standard JDK. Those libraries are:

When you want to use WfMOpen with JDK/JRE 1.4, updated versions of the JRE XML packages (org.w3c.dom, org.xml.sax, org.xml.sax.ext and org.xml.sax.helpers) are needed. You you must therefore use the Endorsed Standards Override Mechanism of the JDK to provide those newer versions, i.e. you have to set the system property java.endorsed.dirs to the directory $DIST/lib/wfdemo/endorsed^[7]. For the versions of the XML libraries currently used see the CVS information in the tools/endorsed subdirectory.

As has been described in the previous sections, the deployment descriptors of the EJB modules must be adapted to the application that integrates the workflow engine. In order to facilitate this task, the EJB JARs have in their subdirectory assembly-resources ant scripts with targets that may be called to perform the adaption. Of course, these scripts do not have to be used to adapt the EJBs, they are simply provided as useful helpers.

# # Information needed for
        application assembly #

# Adapt utility EJBs' JNDI names. They have no "reasonable" defaults,
# so we have to specify very much. Note that these JNDI names are
# define separately as the utility EJBs may be shared between
# different applications. Note that "ejb/" will be prepended to the names
# specified below automatically and the entries for local home interfaces
# have "Local" appended to the name.
@@@_Utility-EJBs_UtilEJB_JNDI_Name_@@@ = \
          de.danet.an.wfdemo.util-lib.Util
@@@_Utility-EJBs_KeyGenEJB_JNDI_Name_@@@ = \
          de.danet.an.wfdemo.util-lib.KeyGen
@@@_Utility-EJBs_KeyGenLockEJB_JNDI_Name_@@@ = \
          de.danet.an.wfdemo.util-lib.KeyGenLock
@@@_Utility-EJBs_EJBSinkEJB_JNDI_Name_@@@ = \
          de.danet.an.wfdemo.util-lib.EJBSink
# Adapt utility EJB's data source reference
java\:/DefaultDS = java:/WfMOpenDS

# Adapt other EJBs' JNDI names. Most application servers require that
# you specify JNDI names although all references to the EJB are via
# links within the application. We simply define a prefix for those.
# This prefix is also used for JNDI names of other resources. Note that
# "ejb/" will be prepended to the prefix specified below when used to
# derive JNDI names for EJBs.
@@@_JNDI_Name_Prefix_@@@ = de.danet.an.wfdemo.

util-ejbs-security-domain = java:/jaas/wfdemo
util-ejbs-security-roles = \
  WfMOpenAdmin: \
    KeyGen*KeyGenLock*EJBSink*Util;
util-ejbs-security-identities = TimeoutHandler:WfMOpenAdmin
util-ejbs-security-principals = TimeoutHandler:WfMOpenAdmin_Principal

# Adapt workflow engine (note that the engine uses the util EJBs, 
# necessary replacements are already covered by the properties above).
java\:/jaas/wfmopen = java:/jaas/wfdemo

The workflow EJBs can be deployed in the usual way defined by J2EE:

<application>
  <display-name>My application using WfMOpen</display-name>
  <module>
    <ejb>de.danet.an.util-ejbs.jar</ejb>
  </module>
  <module>
    <ejb>de.danet.an.wfcore-ejbs.jar</ejb>
  </module>

  <module>
    <ejb>some.user.my.application.jar</ejb>
  </module>
</application>

Make sure that you have included all libraries needed by the workflow EJBs in the lib/ directory of your J2EE application as described in Section 1.3.4, “Workflow module”. This is a usable configuration if you only define workflow processes without any resources (i.e. only automatically executed activities). If resource assignment to activities is needed, some additional services have to be supplied as described below.

If you combine the workflow engine EJBs and servlets (packed as WARs) in a single EAR, it is advisable to have libraries used by both components only in the EAR (i.e. not in the WARs' WEB-INF/lib directory. In such a configuration, the libraries must explicitly be deployed as Java modules in application.xml. Note that this and other packaging aspects are not WfMOpen specific. Rather they apply to J2EE applications in general and details are bexond the scope of this manual. See one of the many books about J2EE for further informations.

An issue not necessarily handled by a workflow core service is the issue of resource assignment. The OMG specification explicitly leaves this topic to a to-be-defined resource assignment facility. We have therefore chosen to introduce a simple interface to a resource assignment service in our design. This interface is described in detail in the package de.danet.an.workflow.spis.ras.

In order to keep this interface easily implementable by any kind of architecture, access to this service is not based on JNDI and an EJB home interface. Access rather follows the established generic pattern to create a service using a factory class. In order to use the workflow component, an implementation of this service must be provided.

The workflow component includes a sample implementation of a resource assignment service. If you want to use this implementation, some additional configuration issues arise which are discussed in Section 6.1, “The sample assignment service”.

Debugging mode is enabled for a specific process by calling setDebugEnabled(true) on the process after creating, but before starting the process (see setDebugEnabled(boolean)).

Debugging can also be enabled for a process type by default using the XPDL extension mechanism as described in Section 4.2.5.2, “Extensions on Package and Process Level”.

When debug mode is enabled, the execution of activities breaks before the invocation of a tool and before completion of an activity.

Immediately before invoking a tool, the activity's state changes to open.running.debug.invoking. To continue the execution, the activity's state must be changed to either open.running or to open.running.debug.skipping. In the former case, the tool will be invoked as in non-debugging mode. In the latter case, tool invocation will be skipped and the activity will either assume the state open.running.debug.invoking again (if there are more tools to be executed by the activity) or the state open.running.debug.completing (if the invocation of the last tools has been skipped, see below). Of course, the process data must subsequently be modified manually to reflect the changes that would have been made by the tool invocation.

Before the activity is eventually closed, it enters one of the states open.running.debug.terminating, ...aborting or ...completing depending on the closed-state that the activity will assume. To continue execution and cause the activity to assume it proper closed state, the activity's state must be changed to open.running.

In debugging mode, exceptions thrown by tools (i.e. calls to abandon, see abandon(java.lang.String) will cause the activity to assume the state open.running.debug.abandoning. To continue the execution, it is not sufficient to provide the possibility to change the state to open.running as described above for the "normal" transitions to the closed state. There may be several exceptional transitions defined, and it must be possible to specify which exception should be used, else it wouldn't be possible to test the different paths during debugging.

In order to avoid polluting the interface with methods that are only used for debugging, we have defined a special sequence of method invocations that cause the execution to continue (i.e. the state will change to closed.completed.abandoned and the execution of subsequent activities will be triggered as specified by the transitions). You first change the state to open.running.debug.awaiting_exception and then call abandon (see abandon(java.lang.String)) with the name of the exception to be processed. The preceding state change causes abandon(String) to behave differently from normal operation, effectively continuing execution as described above.

In order to avoid any ambiguities, we strongly recommend to execute the two operations (state change and abandoning) in a single transaction. This may be achieved by using a user transaction as described in the J2EE specification or by using the method invocation batch (see Section A.2.31, “Class MethodInvocationBatch”).

WorkflowService wfs = ...;
MethodInvocationBatch mib = new MethodInvocationBatch(true);
mib.addInvocation (activity, "changeState", 
		   new String[] {"java.lang.String"},
		   new Object[] {"open.running.debug.awaiting_exception"});
mib.addInvocation (activity, "abandon",
		   new String[] {"java.lang.String"},
		   new Object[] {exception});
MethodInvocationBatch.Result mir
    = (MethodInvocationBatch.Result)wfs.executeBatch(mib);

Deadlines will be be started in debugging mode just as in non-debugging mode. However, nothing happens when deadlines are reached. The state of deadlines may be monitored by calling deadlines(). To cause the process to proceed as if a synchronous deadline had been reached, you must first call abandon(String), which causes the activity to assume the state open.running.debug.abandoning, and then continue execution as described for exceptions in general above (see Section 2.6.3, “Effect on exceptions”). This may, of course, be done before the deadline has been reached, i.e. the effect of a deadline may be tested without actually waiting for the associated time (which may be quite long) to elapse.

In order to simulate an asynchronous deadline, the state of an activity must first be changed to open.running.debug.forwarding_exception. This causes a subsequent call to abandon to mimic the behavior of an asynchronous deadline, i.e. transitions will be triggered as specified for the given exception. The activity will automatically resume the state that it had before the change to open.running.debug.forwarding_exception. Of course, this sequence of method calls should also be executed in a single transaction, as described above.

As a first step, we have adapted the API specified by OMG's Workflow Management Facility Specification, V1.2 to the Java domain. The result of this adaptation can be found in the package description of de.danet.an.workflow.omgcore (see de.danet.an.workflow.omgcore or