This package doesn't contain any tests. Rather, it provides support calsses for the test cases in the othe packages.

This package is the project specific contribution to AN's general Java library. It supplements this library as the project currently demands. When the project has finished, its contents will be reviewed and merged with general library to broaden the code base for future projects.

This package some helper classes for writing JUnit tests.

This package implements an EJBAppender and an EJBSinkEJB bean for storing of logging messages into database.

This package defines a util classes FileInfo and HttpMultiPartParser for receiving multipart content. It be used for import of ProcessDefinition in ProcessDefinitionDirectory.

This package contains implementations of the {@link de.danet.an.util.PersistentMap PersistentMap} interface.

This package provides some helper classes for using SAX parsers.

This package defines an interface to a service that stores user preferences. User preferencies are small chunks of data (usually just an interger or a string) that are used e.g. to control display layout etc.

The interface is as open as possible. It defines a factory class that can be used to access the service and the service itself.

This package consists of classes that help in implementing the web-tier of an application.

The webaction package provides support for handling HTTP requests that want an action to be performed.

An action is included in the request by adding a paramter WAA (webaction action) with the name of the action to perform as value. The action name is mapped to a method call as descriped below. Additional parameters to be passed to the method call may be added by including request parameters WAP1, WAP2 etc.

Methods can be registered as invokable by HTTP very much like the JUnit assembles test cases. The requests are handled by instances of the class {@link de.danet.an.util.web.action.WebActionHandler WebActionHandler} . Actually, not the class itself is instantiated, rather it is used as base class for classes that implement web action handlers and register methods as invokable by web requests. See the description of class {@link de.danet.an.util.web.action.WebActionHandler WebActionHandler} for details.

{@link de.danet.an.util.web.action.WebActionHandler WebActionHandler}s are assembled into {@link de.danet.an.util.web.action.WebActionDispatcher WebActionDispatcher}s. WebActionDispatchers may contain other WebActionDispatchers as well, thus allowing a complex web action dispatcher handler to be constructed from simple web action dispatch handlers.

This package defines the the workflow API provided by Danet's workflow component. The API extends the {@link de.danet.an.workflow.omgcore core API} derived from the OMG "Workflow Management Facility Sepcification, V1.2". We consider the interfaces and classes in this package (together with the interfaces and classes in the core API) to be useable as a general Java workflow API, i.e. if there was a JSR for a Java workflow API, we think the merger of these two packages would be a good starting point.

Trying to implement workflow clients using the OMG interface, we found that it lacks some functions that are either absolutely necessary or nice to have. For some OMG interfaces we have therefore defined a corresponding interface that extends the OMG base interface.

We have also added some interface for areas that the OMG specification has purposely omitted from its scope (e.g. access to process definitions).

Finally, the OMG specification has left it open how to access the root objects of type {@link de.danet.an.workflow.omgcore.WfProcessMgr WfProcessMgr}. We have therefore defined a {@link de.danet.an.workflow.api.WorkflowService WorkflowService} and its corresponding {@link de.danet.an.workflow.api.WorkflowServiceFactory factory} that provides this access (among some other useful function).

This package extends some of the interfaces defined in {@link de.danet.an.workflow.api the api package} in order to allow additional communication between the implementation objects defined in {@link de.danet.an.workflow.domain the domain package}.

The additional methods are needed because domain objects need some knowledge of each other that should not be exposed to the user api. Nevertheless, the additional methods must be defined in interfaces as the implementations may only know about the interfaces of other domain objects, not about the implementation (else we could not provide the objects as remote objects).

Previously, these interfaces used to be in the domain package. However, this leads to cycles in package dependencies.

This package provides a simple resource assignment service as specified by {@link de.danet.an.workflow.spis.ras de.danet.an.workflow.spis.ras}. It is independant of a specific resource management service, as it uses only the service API defined by {@link de.danet.an.workflow.spis.rms de.danet.an.workflow.rms} to access a resource management system.

The service is implemented by the class {@link de.danet.an.workflow.assignment.StandardResourceAssignmentService StandardResourceAssignmentService}. It acts as a front-end (client) for the server-side component (back-end). The server-side component is provided by the {@link de.danet.an.workflow.ejbs.assignment.AssignmentServiceEJB AssignmentServiceEJB}.

For the 1. iteration, we have simple base implementations for the omg interfaces:

• The class AbstractExecutionObject implemements the interface {@link de.danet.an.workflow.omgcore.WfExecutionObject WfExecutionObject} and provides a simple status handling.
• The interface Process extends the interface {@link de.danet.an.workflow.omgcore.WfProcess WfProcess} and provides additional methods for handling a process at runtime.
• The class AbstractProcess implemements the interface {@link de.danet.an.workflow.api.Process Process} and provides a simple mechanism for starting activities.
• The interface Activity extends the interface {@link de.danet.an.workflow.omgcore.WfActivity WfActivity} and provides additional methods for handling an activity at runtime.
• The class AbstractActivity implemements the interface {@link de.danet.an.workflow.domain.AbstractActivity Activity} and provides a simple no-operation with joining or splitting. It provides start- and finish mode settings to control the execution.
• The class ProcessMgr implemements the interface {@link de.danet.an.workflow.omgcore.WfProcessMgr WfProcessMgr} and supports three fixed tepes of processes to start.
• The class Requester implemements the interface {@link de.danet.an.workflow.omgcore.WfRequester WfRequester} .
• The class Contributor implemements the interfaces {@link de.danet.an.workflow.omgcore.WfRequester WfRequester} and {@link de.danet.an.workflow.omgcore.WfResource WfResource} . It provides simple implementation as a requester.

The class ProcessDirectory is an ejb interface for the web client of the 1. iteration. It allows to start a new process and to retrieve information about all activities stored in in the workflow db.

The class ProcessDefinitionDirectory is an ejb interface for the web client of the 1. iteration. It allows to import a new process definition from a XPDL file, to remove or retrieve one or all process definitions stored in in the workflow db. @since V1.0

This package contains client side helper classes used to access the EJBs.

For the first iteration, it has the following features:

• No implementation of the interfaces WfResource, WfAuditHandler, WfAuditEvent and WfAssignment
• No process data handling in processes and activities
• WfProcessMgr: Support of three fixed process types. Most of the interface methods are not implemented.
• No transitions defined between activities. All activities are started at the start of the process.
• A process is completed, if all activities are completed.
• No states Suspended, Terminated, Aborted
• Activities support a start and a finish mode

This package provides some utility EJBs.

This package extends some of the interfaces defined in {@link de.danet.an.workflow.localapi the api package} in order to allow additional communication between the implementation objects defined in {@link de.danet.an.workflow.domain the domain package}.

The additional methods are needed because domain objects need some knowledge of each other that should not be exposed to the user api. Nevertheless, the additional methods must be defined in interfaces as the implementations should only know about the interfaces of other domain objects, not about their implementation.

This package extends some of the interfaces defined in {@link de.danet.an.workflow.localcoreapi the localcoreapi package} in the same way as the {@link de.danet.an.workflow.api the remote API} extends the {@link de.danet.an.workflow.omgcore the OMG API}.

This package provides local variants (i.e. without RemoteException) of {@link de.danet.an.workflow.omgcore the OMG API}.

This package defines the core domain of a workflow management system. It is an adaption of the OMG "Workflow Management Facility Sepcification, V1.2". We consider the interfaces and classes in this package (together with the interfaces and classes in the {@link de.danet.an.workflow.api extended API}) to be useable as a general Java workflow API, i.e. if there was a JSR for a Java workflow API, we think the merger of these two packages would be a good starting point.

We have tried to follow the original specification as close as possible. However, some conventions used by OMG do not fit in the Java environment and changes have been made accordingly.

The main differences are:

• OMG separates words in identifiers using underscores. In the Java environment, words are delimited by using a capital letter.
• The pattern for relationships has been replaced by a single access method RELNAMEs that returns a collection (the plural "s" has been omitted from the relation history of interface {@link de.danet.an.workflow.omgcore.WfExecutionObject WfExecutionObject} for gramatical reasons).
• The OMG model introduces a class WfEventAudit. While the collection of WfEventAudits may be considered the result of an audit, we think that individual items are rather WfAuditEvents. This conforms better to the Java naming scheme where event classes end with "...Event" and the corresponding listener interfaces with "...Listener".
• We have appended "...Exception" to the names of the exceptions, as is usual in Java. Additionally, we have put the exceptions in a separate sub-package to avoid naming conflicts when all omgcore classes are imported with a wildcard import.
• There are no enumeration types in Java. While, in general, elements of enumeration types can simply be mapped to constant definitions, we have not followed this approach in all cases.
  • In the Java environment, the states and substates of an execution object can conveniently be modelled as a {@link de.danet.an.workflow.omgcore.WfExecutionObject.State class hierarchy}. This provides type safe usage and allows to define some convenient methods for handling state.

We have, however not changed the following:

• The access method for attributes have not been renamed getAttribute(). The getX()/setX(...) pattern has been introduced by JavaBeans for the configuration of component properties, not as a general mechanism to access attributes. The properties used in the OMG model are dynamic data properties, not configuration options. Therefore, there is no reason why they should follow the getX()/setX(...) pattern

The documentation of classes and methods in this package consists mostly of an abbreviated version of the description provided by OMG's "Workflow Management Facility Specification, V1.2". Unless otherwise stated, the description from the specification applies fully, i.e. you can use the specification to obtain a detailed understanding of the functionallity provided.

The following picture shows the complete model.

This package defines the client API of the resource adapter modules for the EIS RMS.

This package defines the application invocation interface used by the workflow package to invoke tool agents that control applications.

Java classes that are to be used as tool agents must implement the interface {@link de.danet.an.workflow.spis.aii.ToolAgent ToolAgent}. Tool agents are declared in a workflow using the application tag in the XPDL. This declaration is associated with the implementation class of ToolAgent using an extension. The extension syntax supported allows to specify the Java class to use and additional properties of the tool agent (see the User Manual for details).

Note that a tool agent can be implemented with full functionallity based on the tool agent interface only. The remainder of this package description explains how tool agent implementation may be simplified and how the performance of tool agent invocations may be improved. As with the {@link de.danet.an.workflow.api client API}, we have tried to keep this extended interface as independant of the implementation framework (J2EE) as possible. However, this attempt is limited by requirements imposed by transaction handling. While the interfaces could be kept clean of dependencies on J2EE interfaces or classes, their usage pattern is partially motivated by EJB transaction semantics.

From the workflow engine's point of view, tool agent invocation is asynchronous, i.e. it does not expect a result from the {@link de.danet.an.workflow.spis.aii.ToolAgent#invoke invoke} method. The invoked application must at some point in time call {@link de.danet.an.workflow.omgcore.WfActivity#setResult WfActivity.setResult} and {@link de.danet.an.workflow.omgcore.WfActivity#complete WfActivity.complete} to signal completion of its work. Although the tool agent model assumes that this is done "later" (e.g. by the application process), these calls may also be made in the implementation of the invoke method, thus effectively combining the tool agent with the application that it controls (making the tool agent a tool).

If you try to call setResult and complete in the invoke method of your tool implementation, you'll sooner or later notice that these methods (being remote calls) may throw RemoteExceptions, indicating some temporary failure. If you do not handle these exceptions, they will be handled by the workflow engine and your tool will simply be re-invoked. If, however, your invoke method is "expensive" or has side effects, you may not want it to be re-executed because of a temporary failure during setResult or complete.

Consequently, you put a while loop around these calls, repeating them until they run without a RemoteException. Regrettably, this is where EJB semantics come in. While the repeat pattern works in a stand-alone EJB client, it won't work here because invoke is called in the context of an EJB method and the RemoteException from setResult or complete is noticed by the EJB container, and the complete tool agent invocation transaction will be rolled back. So you have to execute the calls to setResult and complete in a new transaction. This is what {@link de.danet.an.workflow.spis.aii.ToolAgentContext#finishActivity ToolAgentContext.finishActivity} has been defined for. This method calls setResult and complete in a new transaction (and repeats the calls until no RemoteException is thrown). If you want to use this method (or another method from the tool agent context), your tool agent must implement {@link de.danet.an.workflow.spis.aii.ContextRequester ContextRequester} in order to receive the context before invoke is called.

Having a closer look at transactions, there is a drawback to the solution described above. If we look at open transactions, we find that there is one transaction handling the tool invocation; this has been suspended for a new transaction that executes the actual tool agent invocation (this must be done in its own transaction, else the workflow engine cannot terminate an activity if an exception is thrown by the tool agent as, again, the invoking transaction would be marked for rollback by the application server). By calling finishActivity during invoke, the transaction executing the tool invocation will also be suspended in favour of the transaction that finishes the activity. This situation may, under certain circumstances lead to deadlocks.

To avoid these "excessive" nested transaction suspends, the calls to setResult and complete should better be done after tool invocation by the the same transaction that has invoked the tool. Tools (i.e. tool agents that want to return a result and complete the activity during invoke) should therefore implement {@link de.danet.an.workflow.spis.aii.ResultProvider ResultProvider}. This allows the tool to simply leave the result evaluated during invoke in an attribute from where it will be retrieved after invoke by the workflow engine. The workflow engine then calls setResult and complete on the activity. Besides avoiding transaction problems, usage of ResultProvider actually simplifies the tool implementation.

This package defines the Resource Assignment Service used in the de.danet.an.workflow package. This service is both used (by the core workflow component) and provided (as a sample implementation by de.danet.an.workflow.assignment).

The service interface follows the standard conventions for a service interface, i.e. it defines an abstract factory class and a service interface.

This package defines the interface to a resource management service (RMS) as used in the de.danet.an.workflow.spis.ras sample implementation. Note that the implementation of the workflow core does not require a resource management service. However, the sample resource assignment service (RAS) needs a resource management service. We have based the sample RAS on this interface to allow a deployer to use the sample RAS with any resource management service by simply writing an adapter.

The service interface follows the standard conventions for a service interface, i.e. it defines an abstract factory class and a service interface.

Implementing this interface implies a particular problem. The RMS must provide objects that implement {@link de.danet.an.workflow.omgcore.WfResource WfResource}. This interface has, as specified by OMG, methods workItems isMemberOfWorkItems and release. While it is obvious (from an OO point of view) that those methods are defined as methods of WfResource the RMS cannot really implement them. They can only be implemented by an RAS, as it is its task to track assignments. Thus the objects defined and returned by an RMS can only implement the methods by delegating to the RAS.

There may, however, be several instances of RASs in an environment that request resources from the RMS. How can the RMS know, where to delegate to? One way to solve this problem would be to have every RAS "register" itself with the RMS if it assigns a resource from that RMS. This approach has a major drawback. In order to be able to recover from an application restart, the RMS would have to implement such a registry for RASs in persistent store. Depending on the implementation of an RAS, this may be from difficult to impossible.

A much more simple solution is to have a central runtime registry of all available RASs and use the RASs registered there to implement the above mentioned WfResource methods⁽¹⁾. This approach is even more charming as something very close to such a registry exists anyway. While not designed to fulfill this function in the first place, the {@link de.danet.an.workflow.spis.ras.ResourceAssignmentServiceFactory ResourceAssignmentServiceFactory} actually implements a kind of registry, as it must know about all RASs in the system (else there is no way that the workflow core uses it for resource assignment anyway).

The ResourceAssignmentServiceFactory therefore provides the methods needed to implement workItems isMemberOfWorkItems and release. As a convenience this package provides a class {@link de.danet.an.workflow.spis.rms.ResourceSupport ResourceSupport} that uses the methods provided by the ResourceAssignmentServiceFactory and can be directly used by an RMS as base class for providing its implementation of WfResource.

(1)Few things in life are free. There is a small performance penalty to pay for this approach. As the RMS doesn't keep track of the RASs that have requested a particular resource, the central registry has to query all known RASs. However, tracking RAS information (e.g. with identifiers usable as hints for the central registry) in the RMS would impose an overhead as well.

This package contains the builtin tools of WfMOpen. Note that most tools are compiled into a separate tool jar. The subpackages util and timing are, however, included in the EJB jar as they use EJBs and we want to avoid the extra deployment.

This package contains tools for accessing Scarab (http://scarab.tigris.org).

This package provides support classes for the implementation of tool agents and applications. Unlike the {@link de.danet.an.workflow.omgcore core API} and the {@link de.danet.an.workflow.api extended API} (including the {@link de.danet.an.workflow.spis.aii application invocation interface}) this package is not intended to be part of a general Java workflow API. Rather, it provides some WfMOpen specific utilities that ease the implementation of tool agents and applications to be used with the WfMOpen workflow engine.

Using the asynchronous tool invocation API typically requires that the activity and the data passed to the tool agent as parameters are saved in persistent store. The tool (application) that is to actually work with the information typically runs completely independent of the workflow engine in another operating system process or at least in another thread. It accesses the persisted information and e.g. presents the tasks that require human interaction in a GUI. When the interaction has completed, the application retrieves the activity and calls "setResult()" and "complete()" on it.

To support the implementation of the function described above, this package provides a {@link de.danet.an.workflow.util.SimpleApplicationDirectory SimpleApplicationDirectory}. This class implements a general purpose persistent store for the data passed to the tool agent (i.e. the activity and the actual parameters) and additional state information. Tool agents create ("register") instances in this directory. Each instance represents a tool invocation (task) currently running in an external application. Creating an entry results in a unique id that may subsequently be used to retrieve, update or remove the instance. Instances may also be retrieved using an arbitrary key associated with the instance by the registering tool agent, or by activity or by searching instances assigned to a particular WfResource.

Tool agents using the directory should be derived from {@link de.danet.an.workflow.tools.util.SimpleApplicationAgent SimpleApplicationAgent}. They can access the directory by simply invoking the method {@link de.danet.an.workflow.tools.util.SimpleApplicationAgent#applicationDirectory() applicationDirectory()}. External application should use the workflow service and {@link de.danet.an.workflow.tools.util.SimpleApplicationDirectoryLookup SimpleApplicationDirectoryLookup} to access the directory. Applications that run within the application server (or components running within the applictaion server that act on behalf of the external application) may obtain the application directory's local interface by looking it up in JNDI. The name to use for the lookup depends on your application configuration, see section "Application and client assembly", subsection "Workflow module" in the user manual.

Note that the directory may also be used to persist application state across several tool agent invocations by {@link de.danet.an.workflow.tools.util.SimpleApplicationDirectory#updateInvokingActivity associating} an existing instance with a new activity. An example of this requirement is the timer tool. One tool agent creates a timer in a conceptually independently running application and gets an id for it. Another tool agent may then cancel this time or wait for it to expire. I.e. the task initiated by the first tool agent in the application runs spans several tool agent invocations.

Entries in the directory are automatically cleaned when the process they relate to (i.e. the activity's container) is removed.

The class JDBCUtil is a supporting class providing an easier handling for setting parameters in a prepared statement.

The class W3CDomUtil is a supporting class providing an easier handling for getting elements of the org.w3c.dom package. @since V1.0

This package contains unit test cases for domain classes. The tests use the domain classes only, i.e. they do not need a running EJB server.

The tests usually complete the abstract classes defined in de.danet.an.workflow.domain with "dummy" methods and thus obtain instantiable classes usable for the tests.

This package provides a set of test cases intended to give information about WfMOpen's load behaviour. Please note the package is under construction. Thus, the current state of the package is a preliminary one.

The tests are implemented as client applications based on jUnit and jUnitPerf. Each test client performs one or more activities each one covered by a jUnit test case and will be executed within jUnitPerf frame. This allows to perform an action a number of times as defined by a repeating factor as concurrently initiated by several users with a pre-defined constant delay (that may be zero).

In addition to the investigations related to this three variances (number of users, repeating factor, delay) there's an additional variance in the structure of the process definitions, which is under investigation, too.

The package contains

• a set of files containing single jUnit test cases
• a set of files containing load test cases using jUnitPerf
• a file AllLoadTests.java that performs all the load tests (if the are correctly defined within the file)

The test cases currently available are:

	Variance	Filename	XPDL Data	Description
	number of activities and transitions	LoadU1R5D0AvTvseq.java	A5nmmT4seq.xml A10nmmT9seq.xml A20nmmT19seq.xml	This test examines the load behaviour depending on the number of activities contained in a process. The activities will not start automatically. Hence, there should not be any interference with running processes. 1 user starts creating a process with 5 activities repeating 5 times 1 user starts creating a process with 10 activities repeating 5 times 1 user starts creating a process with 20 activities repeating 5 times
	process structure	LoadU1R5D0A10T9var.java	A20nmmT19seq.xml A20nmmT19par.xml	This test examines the load behaviour depending on the construction of a process. The activities will not start automatically. Hence, there should not be any interference with running processes. 1 user starts creating a process with parallel successors activities concurrently repeating 20 times 1 user starts creating a process with serial successors activities concurrently repeating 20 times
	repeating factor	LoadU10RvD0A5T4seq.java	A5nmmT4seq.xml	This test examines the load behaviour depending on the number of times a process is started sequentially. The activities will not start automatically. Hence, there should not be any interference with running processes. 10 users start concurrently - each creating a process repeating 5 times 10 users start concurrently - each creating a process repeating 10 times 10 users start concurrently - each creating a process repeating 20 times
	number of concurrent users	LoadUvR20D0A5T4seq.java	A5nmmT4seq.xml	This test examines the load behaviour depending on the number of users concurrently starting a process. The activities will not start automatically. Hence, there should not be any interference with running processes. 5 users start concurrently - each creating a process repeating 20 times 10 users start concurrently - each creating a process repeating 20 times 20 users start concurrently - each creating a process repeating 20 times
	delay	LoadU20R20DvA5T4seq.java	A5naaT4seq.xml	This test examines the load behaviour depending on the number of users concurrently starting a process. Processes with automatically starting end ending activities are used. Hence, there's an influence cuased by additional load of running processes. 20 users start concurrently - each creating a process repeating 20 times 20 users start with a delay of one second - each creating a process repeating 20 times 20 users start with a delay of two seconds - each creating a process repeating 20 times In the first case there's a load starting at once. The processes are doing somewhat. Hence, compared with test as shown above, there's an additional load on the system. In the two latter cases the load is started with a delay. Thus, the system evolves step by step, first inflating followed by a constant load factor, then deflating.

These tests may be executed by using the build.xml file with the default target run in order to execute a single test, e.g.

        ant -Dtest=<value>

where <value> is the classname (without the package name, which will be assumed as systemtest.load.) that contains the required test suite to be executed.

Using the target run-all all the tests may be successively executed following the sequence as defined in AllLoadTests.java.

System test cases for process definition

• Import definition (Case name: Import)
  • Import of a minimal process definition
  • Import of faulty process definitions (attempt) and corrected versions for the following error cases:
    • Activity with illegal implementation (implementation-*.xml)
    • Activity with illegal performer (performer-*.xml)
    • Transition with illegal activity reference (activityRef-*.xml)
    • Transition restriction with illegal transition reference (transitionRef-*.xml)
    • Block activity with illegal activity set reference (blockActivityRef-*.xml)
  • Regular removal of (prior imported) process definitions
  • Irrgular removal of process definitions (attempt) for the following error cases:
    • Process with illegal package id
    • Process with illegal process id
  • Extensive check of imported process definition
• Process creation (Case name: Create)
  • Enabling/Disabling creation of a process
  • Regular creation of a process
• Process data (Case name: ProcData)
  • Process data info
  • Process data

System test cases for process

• States (Case name: ProcLifeCycle*)
  
• Transitions (Case name: Transition)
  
• Tool invocation
• Process removal