de.danet.an.workflow.api
Class WorkflowServiceFactory

java.lang.Object
  de.danet.an.workflow.api.WorkflowServiceFactory

public abstract class WorkflowServiceFactory

extends java.lang.Object

This class provides a factory API that enables clients to obtain a workflow service facility.

Version:

$Revision: 1.4 $

Author:

Constructor Summary

protected

WorkflowServiceFactory() Constructor.

Method Summary

protected java.util.Map	getProperties() Used by derived classes to access the properties.
static WorkflowServiceFactory	newInstance() Obtain a new instance of a WorkflowServiceFactory.
abstract WorkflowService	newWorkflowService() Creates a new instance of a WorkflowService.
void	setProperties(java.util.Map props) A convenience method that sets all properties in the Map.
void	setProperty(java.lang.String name, java.lang.Object value) Sets a property which is passed to the WorkflowService produced by this factory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WorkflowServiceFactory

protected WorkflowServiceFactory()

Constructor. Must be overridden with a parameterless public constructor by derived class.

Method Detail

newInstance

public static WorkflowServiceFactory newInstance()
                                          throws FactoryConfigurationError

Obtain a new instance of a WorkflowServiceFactory. This static method creates a new factory instance. The method uses the following ordered lookup procedure to determine the WorkflowServiceFactory implementation class to load:

• If an initial naming context is available, look for a a classname in java:comp/env/de.danet.an.workflow.api.WorkflowServiceFactory. The configuration for a class as workflow service factory thus looks like:

  <env-entry>
     <description>Configure the workflow service factory</description>
     <env-entry-name>de.danet.an.workflow.api.WorkflowServiceFactory</env-entry-name>
     <env-entry-type>java.lang.String</env-entry-type>
     <env-entry-value>FactoryImplementationClass</env-entry-value>
   </env-entry>

  Note that this environment entry must be inserted in the ejb-jar.xml or web.xml for every EJB resp. servlet that calls the newInstance method of WorkflowServiceFactory.
• Use the services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/de.danet.an.workflow.api.WorkflowServiceFactory. in jars available to the runtime.

Note that the specified workflow service factory may need additional configuration parameters.

Returns:

an instance of the WorkflowServiceFactory.

Throws:

FactoryConfigurationError - if a factory instance can't be created.

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)

Sets a property which is passed to the WorkflowService produced by this factory.

Valid properties generally depend on the underlying implementation. There are, however, a few exceptions.

If the workflow service implementation is based on the J2EE environment, clients derive the connection to a server from an InitialContext. There are cases when the user wants or needs to override the initial context used by the workflow service implementation. It is therefore defined that setting the property "javax.naming.InitialContext" to a value of type Context overrides any default method used by the workflow service implementation to obtain the initial context.

As an alternative, the property "javax.naming.InitialContext.Environment" may be set to a Hashtable that contains the environment to be used when creating an InitialContext.

Subsequent versions of this interface may define additional common properties. We therefore recommended to use "fully qulified" (i.e. package style) names for properties that are specific to a workflow service implementation.

Parameters:

name - the name of the property

value - the value of the property

setProperties

public void setProperties(java.util.Map props)

A convenience method that sets all properties in the Map.

Parameters:

props - the properties to be set

getProperties

protected java.util.Map getProperties()

Used by derived classes to access the properties.

Returns:

the defined properties

newWorkflowService

public abstract WorkflowService newWorkflowService()
                                            throws FactoryConfigurationError

Creates a new instance of a WorkflowService.

This API does not specify how a workflow service factory or workflow service should be implemented. If, however, the implementation is J2EE/EJB based, the following additional rules apply to achieve common bahaviour for J2EE based implementations.

In the J2EE environment, clients usually obtain the connection to a server from a directory service represented by an InitialContext instance. This instance need not be the default initial context available to the client (think of a servlet running in a servlet container that wants to access the workflow engine running in an application server on a different machine).

In an environment that uses an InitialContext to obtain the connection to the server (as described above), the following ordered lookup procedure must be implemented to determine this initial context.

• If the property "javax.naming.InitialContext" has been set, use it as initial context. if property "javax.naming.InitialContext.Environment" has been set, use it to obtain the initial context (see setProperty.
• If a default InitialContext is available during the execution of newInstance (i.e. "new InitialContext() succeeds), and entries java:comp/env/de.danet.an.workflow.api.WorkflowService.NAMING_CONTEXT_FACTORY and java:comp/env/de.danet.an.workflow.api.WorkflowService.NAMING_CONTEXT_URL exist, use them to obtain the initial context.
• If defined, execute vendor specific procedures to obtain an initial context.
• If a default InitialContext is available during the execution of newInstance use it (i.e. do not try to obtain another initial context (this is the common situation where a servlet based client and the workflow engine run in one application server).

Returns:

the workflow service.

Throws:

FactoryConfigurationError - if not all required resources can be obtained.