de.danet.an.workflow.spis.ras
Interface ResourceAssignmentService

public interface ResourceAssignmentService

This interface defines the resource assignment facility used by the workflow component. A central design issue for this interface is the identification of activites.

The "key" method of WfActivity is by definition only unique within the scope of the containing process and can thus not easily be used to identify a single activity in a workflow engine. Even worse, a resource assignment service might be used by more than one workflow engine.

At this interface, an activity is therefore identified using an ActivityFinder and an identifier that is unique with respect to the ActivityFinder. The ActivityFinder provides both a namespace to allow different consumers to request resources and a means for the assignment facility to map the identifier back to an actual WfActivity object. See the description of ActivityFinder for more details.

From the workflow engine's point of view, the resource assignment service is the only source of objects of type WfResource and WfAssignment. Implementations of resource assignment services may be (but need not be) based on a resource management service as defined in package de.danet.an.workflow.spis.rms.

Method Summary

WfResource	asResource(java.security.Principal principal) Given a principal, return the workflow resource associated with this principal.
java.util.Collection	assignments(ActivityFinder finder, java.lang.String actId, WfActivity activity) Return the assignments to an activity.
java.util.Collection	authorizers(WfResource resource) Given a WfResource object, return the collection of resources this resource is authorized for.
java.util.Collection	autoAssignResources(ActivityFinder finder, java.lang.String actId, WfActivity activity, java.security.Principal principal, Participant participant) Triggers the automatic assignment of resources to an activity that is about to become ready.
void	changeAssignment(ActivityFinder finder, java.lang.String actId, WfActivity activity, WfResource oldResource, WfResource newResource) Change an assignment for enacting an activity.
WfResource	getResource(WfAssignment asnmnt) Get the resource associated with an Assignment.
boolean	isMemberOfWorkItems(WfResource resource, WfAssignment assignment) Find out if a given assignment belongs to the work items assigned to a particular resource.
java.util.Collection	knownResources() Returns at least the collection of all the workflow resources being assigned to activities, but should also return the additional workflow resources that are known to the resource assignment service.
void	removeAssignment(ActivityFinder finder, java.lang.String actId, WfActivity activity, WfResource resource) Remove the assignment of a resource to an activity.
WfResource	resourceByKey(java.lang.String key) Given the key of a WfResource (obtained with resourceKey()), return the workflow resource associated with this key.
java.util.Collection	workItems(WfResource resource) Return the assignments of a given resource.

Method Detail

asResource

public WfResource asResource(java.security.Principal principal)
                      throws java.rmi.RemoteException,
                             InvalidKeyException

Given a principal, return the workflow resource associated with this principal.

As the workflow core does not have a defined access to a resource management facility, this mapping functionality must be brought to the workflow core by the resource assignment service. If the resource assignment service is based on a resource management service as defined in package de.danet.an.workflow.spis.rms, it can simply delegate this call to ResourceManagementService.asResource. The workflow engine does not need this method for its operation; however, it provides a method for accessing this information as part of the client interface to ease the implementation of clients that e.g. want to generate a list of assignments for the current user. The implementation of this method by a resource assignment service is therefore optional. If not implemented, a call to this method must result in a UnsupportedOperationException.

Parameters:

principal - the principal.

Returns:

a WfResource object corresponding to the given principal.

Throws:

InvalidKeyException - if the resource with the given key can't be found.

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.2

resourceByKey

public WfResource resourceByKey(java.lang.String key)
                         throws InvalidKeyException,
                                java.rmi.RemoteException

Given the key of a WfResource (obtained with resourceKey()), return the workflow resource associated with this key.

For the workflow core, the resource assignment interface is the only source of WfResource objects. While resourceKey() provides an easy mapping of those objects to unique keys, the reverse mapping can only be provided by the resource management facility that has created the WfResource objects.

As the workflow core does not have a defined access to a resource management facility, this reverse mapping functionality must be brought to the workflow core by the resource assignment service. (Which is quite reasonable, as it has delivered the WfResource objects in the first place.) If the resource assignment service is based on a resource management service as defined in package de.danet.an.workflow.spis.rms, it can simply delegate this call to ResourceManagementService.resourceByKey. The workflow engine does not need this method for its operation; however, it provides a method for accessing this information as part of the client interface to ease the implementation of clients. The implementation of this method by a resource assignment service is therefore optional. If not implemented, a call to this method must result in a UnsupportedOperationException.

Parameters:

key - the key.

Returns:

a WfResource object corresponding to the given key.

Throws:

InvalidKeyException - if the resource with the given key can't be found. As the environment is a concurrent multi user environment, WfResource objects (and keys obtained from WfResource objects) may become invalid.

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.2

knownResources

public java.util.Collection knownResources()
                                    throws java.rmi.RemoteException

Returns at least the collection of all the workflow resources being assigned to activities, but should also return the additional workflow resources that are known to the resource assignment service.

If the resource assignment service is based on a resource management service as defined in package de.danet.an.workflow.spis.rms, it can simply delegate this call to ResourceManagementService.listResources. The workflow engine does not need this method for its operation; however, it provides a method for accessing this information as part of the client interface to ease the implementation of clients. The implementation of this method by a resource assignment service is therefore optional. If not implemented, a call to this method must result in a UnsupportedOperationException.

Returns:

the collection of resources known to the resource assignment service (instances of WfResource).

Throws:

java.rmi.RemoteException - if a system-level error occurs.

authorizers

public java.util.Collection authorizers(WfResource resource)
                                 throws java.rmi.RemoteException

Given a WfResource object, return the collection of resources this resource is authorized for.

The resource assignment service usually uses its underlying resource management facility to implement this method, returning all groups the resource is a member of and all roles assigned to the resource. Resource assigments facilities may, however, modify this information e.g. according to configured delegation rules.

If the resource assignment service is based on a resource management service as defined in package de.danet.an.workflow.spis.rms, it can simply delegate this call to ResourceManagementService.authorizers. The workflow engine does not need this method for its operation; however, it provides a method for accessing this information as part of the client interface to ease the implementation of clients. The implementation of this method by a resource assignment service is therefore optional. If not implemented, a call to this method must result in a UnsupportedOperationException.

Parameters:

resource - the resource.

Returns:

a collection of WfResource objects, not including resource

Throws:

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.2

autoAssignResources

public java.util.Collection autoAssignResources(ActivityFinder finder,
                                                java.lang.String actId,
                                                WfActivity activity,
                                                java.security.Principal principal,
                                                Participant participant)
                                         throws java.rmi.RemoteException

Triggers the automatic assignment of resources to an activity that is about to become ready.

Usually, criteria for the resource selection must be determined within the resource assignment, e.g. based on the name of the activity, the process it belongs to etc. In some cases, however, the worflow component may have some resource selection information available. The workflow component may have obtained such information e.g. as part of the process description. If such information is available, it may optionally be passed to the automatic assignment. The type and valid values of such information depends totally on the resource assignment service used and remains undefined in the scope of this interface.

Parameters:

actId - a unique (with respect to an ActivityFinder) identifier for the Activity. The length of actId is guaranteed not to exceed 64.

finder - the finder used to lookup activities by their finderIds.

activity - the activity that is about to become ready.

principal - the creator of the process, may be null.

participant - the Participant that describes resource selection criteria. The paramter may be null

Returns:

the assigned resources (instances of WfResource).

Throws:

java.rmi.RemoteException - if a system-level error occurs.

See Also:

ActivityFinder

changeAssignment

public void changeAssignment(ActivityFinder finder,
                             java.lang.String actId,
                             WfActivity activity,
                             WfResource oldResource,
                             WfResource newResource)
                      throws java.rmi.RemoteException,
                             InvalidResourceException,
                             AlreadyAssignedException,
                             NotAssignedException

Change an assignment for enacting an activity. This method is called by the workflow engine in Activity.changeAssignment which should be used by resource assignment services to implement WfAssignment.setAssignee.

Parameters:

finder - the finder used to lookup activities by their finderIds

actId - a unique (with respect to an ActivityFinder) identifier for the Activity. The length of actId is guaranteed not to exceed 64

activity - the activity being enacted

oldResource - the resource that has its assignment removed

newResource - the resource to be assigned

Throws:

java.rmi.RemoteException - if a system-level error occurs

InvalidResourceException - if the resource is invalid. As the environment is a concurrent multi user environment, WfResource objects may become invalid

AlreadyAssignedException - if the assignment already exists

NotAssignedException - if there is no assignment to the old resource

See Also:

ActivityFinder

removeAssignment

public void removeAssignment(ActivityFinder finder,
                             java.lang.String actId,
                             WfActivity activity,
                             WfResource resource)
                      throws java.rmi.RemoteException,
                             InvalidResourceException,
                             NotAssignedException

Remove the assignment of a resource to an activity. This method is called by the workflow engine in Activity.removeAssignment which, in turn, should be used by resource management services to implement WfResource.release.

Parameters:

finder - the finder used to lookup activities by their finderIds

actId - a unique (with respect to an ActivityFinder) identifier for the Activity. The length of actId is guaranteed not to exceed 64.

activity - the activity that is about to become ready

resource - the resource to be assigned

Throws:

java.rmi.RemoteException - if a system-level error occurs

InvalidResourceException - if the resource is invalid. As the environment is a concurrent multi user environment, WfResource objects may become invalid.

NotAssignedException - if the resource is not assigned to the given activity

See Also:

ActivityFinder

assignments

public java.util.Collection assignments(ActivityFinder finder,
                                        java.lang.String actId,
                                        WfActivity activity)
                                 throws java.rmi.RemoteException

Return the assignments to an activity.

Parameters:

actId - a unique (with respect to an ActivityFinder) identifier for the Activity. The length of actId is guaranteed not to exceed 64.

finder - the finder used to lookup activities by their finderIds.

activity - the activity.

Returns:

the collection of assignments (instances of WfAssignment).

Throws:

java.rmi.RemoteException - if a system-level error occurs.

workItems

public java.util.Collection workItems(WfResource resource)
                               throws java.rmi.RemoteException,
                                      NoSuchResourceException

Return the assignments of a given resource.

Parameters:

resource - the resource.

Returns:

the collection of assigned work items (instances of WfAssignment).

Throws:

java.rmi.RemoteException - if a system-level error occurs.

NoSuchResourceException - if the resource is invalid. As the environment is a concurrent multi user environment, WfResource objects may become invalid.

isMemberOfWorkItems

public boolean isMemberOfWorkItems(WfResource resource,
                                   WfAssignment assignment)
                            throws java.rmi.RemoteException,
                                   NoSuchResourceException

Find out if a given assignment belongs to the work items assigned to a particular resource.

Parameters:

resource - the resource.

assignment - the assignment in question.

Returns:

true if the assignment belongs to the work items of the resource.

Throws:

java.rmi.RemoteException - if a system-level error occurs.

NoSuchResourceException - if the resource is invalid. As the environment is a concurrent multi user environment, WfResource objects may become invalid.

getResource

public WfResource getResource(WfAssignment asnmnt)
                       throws java.rmi.RemoteException

Get the resource associated with an Assignment.

Parameters:

asnmnt - the assignment

Returns:

the resource

Throws:

java.rmi.RemoteException - if a system-level error occurs.

Since:

1.3.4