de.aristaflow.adept2.core.processrepository

Interface ProcessTemplateManager

public interface ProcessTemplateManager

The process template manager provides the means to manage process templates the corresponding change histories (creation, retrieval, storing, purging) as well as the lifecycle of a template. Process templates can be retrieved by their ID.

New process templates are derived from existing parent templates. Since there are no changes yet, the parent template is copied and returned. While constructing the new child template can be stored and checked out again arbitrarily. When finished, the process template needs to comply to the ADEPT-metamodel. Compliant templates can be released after the check in. A released template can not be changed any more. Instead, a new child template has to be derived.

To allow for schema evolution between arbitrary templates, the change history (as well as a corresponding structural representation) relative from a parent version to a child version of a process type can be retrieved. This history can be purged before retrieval. Purged histories do not contain complementary entries, e.g. a node is inserted and deleted afterwards.

The state in the life cycle of a process template are defined in de.aristaflow.adept2.base.globals.ProcessConstants. State changes committed via the process template manager are automatically propagated to the process manager the corresponding template is deployed to.

There are three buildtime states:

• IN_CONSTRUCTION: a template is subject to modifications and does not comply to the ADEPT-metamodel
• VALID: a template may be subject to modifications but does yet comply to the ADEPT-metamodel
• RELEASED: a template may be instantiated but not modified any more

RELEASED has five substates. Four of these substates (excluding DERIVABLE) further distinguished regarding the scope of the state. The scope can be top-level usage of the template or using the template as a subprocess. For example, a template can be instantiable as a subprocess but not as a top-level process. If a template may not be used as a subprocess, the states with subprocess-scope will have to be ignored.

In future versions these states can be extended to make up access rules, which is specific users may instantiate or change a template or they can work concurrently.

Author:

Ulrich Kreher

See Also:

ProcessConstants

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CHECK_REPORT_ID The ID used by process repository specific process check reports.

Method Summary

Modifier and Type	Method and Description
java.util.Collection<CheckReport>	deployProcessTemplate(SessionToken session, java.util.UUID templateId, java.util.Collection<java.net.URI[]> pmUris, boolean includeReferenced, java.util.Locale... locales) Deploys a released process template and optionally all referenced subprocess templates to the designated process managers.
void	deployProcessTemplate(SessionToken session, java.util.UUID templateID, java.util.Set<java.net.URI[]> processManagerURIs) Deploys a released process template to the designated process managers.
ChangeableTemplate	deriveNewChildTemplate(SessionToken session, java.util.UUID parentTemplateID) Creates and locks a template as child of the designated parent template.
java.util.Set<TemplateProxy>	getAllTemplateProxies(SessionToken session, Filter filter) Gets all lightweight objects (TemplateProxy) that match the designated filter based on TemplateProxy.
RemoteIterator<java.util.List<TemplateProxy>>	getAllTemplateProxiesIterator(SessionToken session, Filter filter) The same as getAllTemplateProxies(SessionToken, Filter) but with partial retrieval of the lightweight objects for process templates.
ChangeableTemplate	getAndLockTemplate(SessionToken session, java.util.UUID templateID) Gets a template in construction for further modification.
TemplateStatus	getAndLockTemplateStatus(SessionToken session, java.util.UUID templateID) Gets an object containing the status of the designated process template and locks the template status for further manipulation, for instance, another status change, a schema-evolution or a new instantiation.
Template	getTemplate(SessionToken session, java.util.UUID templateID) Gets the designated process template without locking it.
TemplateProxy	getTemplateProxy(SessionToken session, java.util.UUID templateID) Gets a lightweight object (TemplateProxy) of the designated process template.
TemplateStatus	getTemplateStatus(SessionToken session, java.util.UUID templateID) Gets an object containing the status of the designated process template, that is, whether the template is outdated, may be derived, may be instantiated, whether instances may be migrated to the process template and whether instances are changeable.
void	release(SessionToken session, java.util.UUID templateID) Enables the instantiation and usage of the process template by setting the buildtime state to RELEASED.
TemplateDeltaLayer	retrieveTemplateDeltaLayer(SessionToken session, java.util.UUID templateID) Retrieves graph structures (deltas) representing all changes of the designated template relative to the null template.
TemplateDeltaLayer	retrieveTemplateDeltaLayer(SessionToken session, java.util.UUID templateID, java.util.UUID ancestorTemplateID) Retrieves graph structures (deltas) representing all changes of the designated template relative to the designated parent template.
void	setTemplateStatus(SessionToken session, TemplateStatus templateStatus) Sets the status of the template (identified by the template status object), to the new status.
CheckReport	storeTemplate(SessionToken session, Template template, boolean checkValidity, org.w3c.dom.Document history, TemplateDeltaLayer structuralChanges, java.util.Locale... locales) Stores (but does not unlock) a modified template (which has been checked out for modification beforehand.
int	unlockTemplate(SessionToken session, java.util.UUID templateID) Unlocks the designated process template for the user identified by the session and also the corresponding template status it this is also locked.
int	unlockTemplateStatus(SessionToken session, java.util.UUID templateID) Unlocks the status of the designated template, ignores made changes and releases the lock on the process template status.
CheckReport	validateTemplate(SessionToken session, java.util.UUID templateId, java.util.Locale... locales) Tries to validate the template and fills the designated CheckReport for useful feedback.

Field Detail

CHECK_REPORT_ID

static final java.lang.String CHECK_REPORT_ID

The ID used by process repository specific process check reports.

See Also:

Constant Field Values

Method Detail

getAllTemplateProxies

java.util.Set<TemplateProxy> getAllTemplateProxies(SessionToken session,
                                                   Filter filter)

Gets all lightweight objects (TemplateProxy) that match the designated filter based on TemplateProxy.

Parameters:

session - The session which is used to check for access rights on this method.

filter - The filter on TemplateProxy which all process template references have to match. If this is null, no filter will be applied and lightweight objects for all process templates will be returned.

Returns:

All lightweight objects (TemplateProxy) that match the designated filter.

getAllTemplateProxiesIterator

RemoteIterator<java.util.List<TemplateProxy>> getAllTemplateProxiesIterator(SessionToken session,
                                                                            Filter filter)

The same as getAllTemplateProxies(SessionToken, Filter) but with partial retrieval of the lightweight objects for process templates.

Parameters:

session - The session which is used to check for access rights on this method.

filter - The filter on TemplateProxy which all process template references have to match. If this is null, no filter will be applied and an iterator for the lightweight objects for all process templates will be returned.

Returns:

An iterator providing lightweight objects ( TemplateProxy) that match the designated filter.

getTemplateProxy

TemplateProxy getTemplateProxy(SessionToken session,
                               java.util.UUID templateID)

Gets a lightweight object (TemplateProxy) of the designated process template.

Parameters:

session - The session which is used to check for access rights on this method.

templateID - The unique ID of the (proxy of the) process template to be returned.

Returns:

A lightweight representation of the process template with the designated ID.

getTemplate

Template getTemplate(SessionToken session,
                     java.util.UUID templateID)

Gets the designated process template without locking it. The template may not be valid since it may be under construction by another user. The returned template can not be changed.

Parameters:

session - The session which is used to check for access rights on this method.

templateID - The ID of the process template to retrieve.

Returns:

An object representing the designated process template.

getAndLockTemplate

ChangeableTemplate getAndLockTemplate(SessionToken session,
                                      java.util.UUID templateID)
                               throws InvalidTemplateStateException,
                                      LockException

Gets a template in construction for further modification. The template will be locked and can not checked out by another user. A template lock is not reentrant, however, the locking agent can re-lock the template several times as well as the corresponding status.

The execution of this method will be prevented and lead to an InvalidTemplateStateException if the template is released.

Precondition:

 (template.getBuildtimeState() != ProcessConstants.TemplateBuildtimeState.RELEASED)
 

Parameters:

session - The session which is used to check for access rights on this method and to identify the locking agent and the corresponding organisational position.

templateID - The unique ID of the process template to be returned.

Returns:

The requested process template as a changeable template.

Throws:

InvalidTemplateStateException - If the process template is released, an InvalidTemplateStateException will be thrown.

LockException - If the template is locked by another user, an LockException will be thrown.

See Also:

TemplateReference.getBuildtimeState(), ProcessConstants.TemplateBuildtimeState

storeTemplate

CheckReport storeTemplate(SessionToken session,
                          Template template,
                          boolean checkValidity,
                          org.w3c.dom.Document history,
                          TemplateDeltaLayer structuralChanges,
                          java.util.Locale... locales)
                   throws InvalidLicenceException,
                          LockException

Stores (but does not unlock) a modified template (which has been checked out for modification beforehand. The history and the structural changes have to be relative to the parent template. There is no check whether the history correctly represents the changes between parent and new process template!

If the template should be released afterwards, the flag checkValidity should be set. This will check whether the template is valid and if so, will set the buildtime state to TemplateBuildtimeState.VALID. If the check fails or the validity should not be checked yet, the buildtime state will be TemplateBuildTimeState.IN_CONSTRUCTION. The result of the validation check is returned as CheckReport.

Before setting a template to TemplateBuildtimeState.VALID its nodes will be renumbered according to the topological sorting. This allows for a compact memory representation of all template nodes since there are no unused IDs. The mapping is also stored in the TemplateDeltaLayer.

The process template has to be locked by the designated user. Otherwise a LockException will be raised. After checking in the template it will be in state IN_CONSTRUCTION or VALID depending on the valid-flag. The valid flag has to be set automatically by the modelling component. It will have to be assured that the process template must only be set if the template complies to the ADEPT-metamodel.

Precondition:

 (template.getBuildtimeState() != ProcessConstants.TemplateBuildtimeState.RELEASED)
 

Postcondition:

 (template.getBuildtimeState() == ProcessConstants.TemplateBuildtimeState.IN_CONSTRUCTION)
  || (template.getBuildTimeState() == ProcessConstants.TemplateBuildtimeState.VALID)
 

Parameters:

session - The session which is used to check for access rights on this method and to identify the storing agent and the corresponding organisational position.

template - The template to store in the process repository.

checkValidity - Whether the designated process template should be checked for compliance to the ADEPT-metamodel. If this is not set, the template will be in state TemplateBuildtimeState.IN_CONSTRUCTION. Otherwise the validity will be checked and the report will be returned. Depending on the check results, the template will be set to state TemplateBuildtimeState.VALID

history - The change history of the process template relative to the corresponding parent template.

structuralChanges - The changes as graph structures relative to the corresponding process template.

locales - The locales the check report should provide (or at least a fallback of each). If this is null, Locale.ROOT will be used.

Returns:

Null in case no check is desired or a check report containing the result of the checks. Please refer to the CheckReport.getCheckResult() for checking whether the storage was successful ( CheckReport.ResultType.OK and CheckReport.ResultType.INFO).

Throws:

InvalidLicenceException - If the current licence does not support the process type of designated template, an InvalidLicenceException will be thrown.

LockException - If the process template not locked by the designated user, a LockException will be raised.

See Also:

TemplateReference.getBuildtimeState(), ProcessConstants.TemplateBuildtimeState

unlockTemplate

int unlockTemplate(SessionToken session,
                   java.util.UUID templateID)
            throws LockException

Unlocks the designated process template for the user identified by the session and also the corresponding template status it this is also locked. No changes are stored. The template has to be locked by the designated user. Otherwise a LockException will be thrown.

Parameters:

session - The session which is used to check for access rights on this method and to identify the checking in agent and the corresponding organisational position.

templateID - The unique ID of the process template to be unlocked.

Returns:

The amount of locks remaining on the template by the designated user after this unlock.

Throws:

LockException - If the process template not locked by the designated user, a LockException will be thrown.

validateTemplate

CheckReport validateTemplate(SessionToken session,
                             java.util.UUID templateId,
                             java.util.Locale... locales)
                      throws LockException

Tries to validate the template and fills the designated CheckReport for useful feedback. If the template has been validated successfully, its status will be adapted accordingly. Please refer to the check report or to the template status after calling this method for whether the validation has been successful.
A template may be validated several times even if already in state VALID or RELEASED.

The template status will only be updated if necessary (the status has changed due to validation). For updating the template status it will be locked (additionally) for a short time.

Parameters:

session - The session which is used to check for access rights on this method.

templateId - The ID of the process template to validate.

locales - The locales the check report should provide (or at least a fallback of each). If this is null, Locale.ROOT will be used.

Returns:

A check report containing the result of the checks. Please refer to the CheckReport.getCheckResult() for checking whether validation has been successful ( CheckReport.ResultType.OK and CheckReport.ResultType.INFO).

Throws:

LockException - If the template is valid and the template status needs to be adapted but the status object or the corresponding template is currently locked (except by the designated user), a LockException will be thrown.

deriveNewChildTemplate

ChangeableTemplate deriveNewChildTemplate(SessionToken session,
                                          java.util.UUID parentTemplateID)
                                   throws InvalidTemplateStateException,
                                          InvalidLicenceException,
                                          LockException

Creates and locks a template as child of the designated parent template. The new child template is just a copy of the corresponding parent template. For tracing purpose the user ID (agent and position) is stored with the child template. Remember to unlock the derived template as soon as the modification has finished.
While deriving, the corresponding parent template will be locked.

The execution of this method will be prevented and lead to an InvalidTemplateStateException if the parent template is not released or not derivable.

The template will be initially in this states: When releasing a template the substates are set to the following default values for both usages, top-level as well as subprocess:

• OUTDATED: false
• DERIVABLE (scope-independent): false
• INSTANCEABLE: false
• INSTANCES_MIGRATABLE_TO: false
• INSTANCES_CHANGEABLE: false

The template will be top-level usable but not as subprocess ( NO_SUBPROCESS).

Precondition:

 (parentTemplate.getBuildtimeState() == ProcessConstants.TemplateBuildtimeState.RELEASED)
     && parentTemplate.isDerivable()
 

Postcondition:

 (template.getBuildtimeState() == ProcessConstants.TemplateBuildtimeState.RELEASED)
     && !template.isOutdated(true | false)
     && !template.isDerivable()
     && !template.isInstantiable(true | false)
     && !template.areInstancesMigratableTo(true | false)
     && !template.areInstancesChangeable(true | false)
     && template.isTopLevelUsable()
     && template.getUsageAsSubprocess() == ProcessConstants.TemplateUsage.NO_SUBPROCESS
 

Parameters:

session - The session which is used to check for access rights on this method and to identify the deriving agent and the corresponding organisational position.

parentTemplateID - The ID of the parent template of which the new template is to be derived.

Returns:

A copy of the parent template as a changeable template which will become the child template.

Throws:

InvalidTemplateStateException - If the process template may not be derived, an InvalidTemplateStateException will be raised.

InvalidLicenceException - If the current licence does not support the process type of the parent template, an InvalidLicenceException will be thrown.

LockException - If the parent process template is locked and not by the current user, a LockException will be thrown.

See Also:

getAndLockTemplate(SessionToken, UUID), TemplateReference.getBuildtimeState(), TemplateReference.isOutdated(boolean), TemplateReference.isDerivable(), TemplateReference.isInstantiable(boolean), TemplateReference.areInstancesMigratableTo(boolean), TemplateReference.areInstancesChangeable(boolean), TemplateReference.isTopLevelUsable(), TemplateReference.getUsageAsSubprocess(), ProcessConstants.TemplateBuildtimeState, ProcessConstants.TemplateUsage

release

void release(SessionToken session,
             java.util.UUID templateID)
      throws InvalidTemplateStateException,
             LockException

Enables the instantiation and usage of the process template by setting the buildtime state to RELEASED. A released template may not be changed any more. One has to derive a new child template for modifications instead. Only a valid, that is a template compliant to the ADEPT-metamodel, may be released. the template status will remain unchanged except of the buildtime state of course.

No lock is required for releasing a template, but the released template (as well as the corresponding state) will keep its locks if there have been locks before releasing.

Precondition:

 (template.getBuildtimeState() == ProcessConstants.TemplateBuildtimeState.VALID)
 

Postcondition:

 (template.getBuildtimeState() == ProcessConstants.TemplateBuildtimeState.RELEASED)
 

Parameters:

session - The session which is used to check for access rights on this method.

templateID - The ID of the process template to release. The template has to be valid.

Throws:

InvalidTemplateStateException - If the process template is not valid, an InvalidTemplateStateException will be thrown.

LockException - If the process template is locked and not by the current user, a LockException will be thrown.

See Also:

TemplateReference.getBuildtimeState(), ProcessConstants.TemplateBuildtimeState

deployProcessTemplate

void deployProcessTemplate(SessionToken session,
                           java.util.UUID templateID,
                           java.util.Set<java.net.URI[]> processManagerURIs)
                    throws InvalidTemplateStateException,
                           LockException

Deploys a released process template to the designated process managers. The process managers are stored internally and are notified when changing the template status. While deploying the template will be locked to prevent concurrent modifications of the template status.

Parameters:

session - The session which is used to check for access rights on this method and to identify the deploying agent and the corresponding organisational position.

templateID - The unique ID of the process template to be deployed.

processManagerURIs - The URIs identifying the process managers to deploy the designated template to.

Throws:

InvalidTemplateStateException - If the process template is not yet released, an InvalidTemplateStateException will be thrown.

LockException - If the process template is locked and not by the current user, a LockException will be thrown.

deployProcessTemplate

java.util.Collection<CheckReport> deployProcessTemplate(SessionToken session,
                                                        java.util.UUID templateId,
                                                        java.util.Collection<java.net.URI[]> pmUris,
                                                        boolean includeReferenced,
                                                        java.util.Locale... locales)
                                                 throws InvalidTemplateStateException,
                                                        LockException

Deploys a released process template and optionally all referenced subprocess templates to the designated process managers. The process managers are stored internally and are notified when changing the template status. While deploying the template(s) will be locked to prevent concurrent modifications of the corresponding template status.

Parameters:

session - The session which is used to check for access rights on this method and to identify the deploying agent and the corresponding organisational position.

templateId - The unique ID of the (top-level) process template to be deployed.

pmUris - The URIs identifying the process managers to deploy the designated template to.

includeReferenced - Whether to include referenced subprocesses recursively when deploying.

locales - The locales the check report should provide (or at least a fallback of each). If this is null, Locale.ROOT will be used.

Returns:

The check reports from storing the template(s) to the designated process manager. The position in the collection corresponds to the position of the process manager in the URI collection.

Throws:

InvalidTemplateStateException - If the process template or one of the referenced templates is not yet released, an InvalidTemplateStateException will be thrown.

LockException - If the process template or one of the referenced templates is locked and not by the current user, a LockException will be thrown.

getTemplateStatus

TemplateStatus getTemplateStatus(SessionToken session,
                                 java.util.UUID templateID)

Gets an object containing the status of the designated process template, that is, whether the template is outdated, may be derived, may be instantiated, whether instances may be migrated to the process template and whether instances are changeable. The returned TemplateStatus-object does not allow to change the status (set-methods and release). For changing the status, the corresponding template status has to be locked.

Parameters:

session - The session which is used to check for access rights on this method.

templateID - The ID of the template to get the status of.

Returns:

An object containing the status of the designated process template.

See Also:

getAndLockTemplateStatus(SessionToken, UUID)

getAndLockTemplateStatus

TemplateStatus getAndLockTemplateStatus(SessionToken session,
                                        java.util.UUID templateID)
                                 throws LockException

Gets an object containing the status of the designated process template and locks the template status for further manipulation, for instance, another status change, a schema-evolution or a new instantiation. The returned object allows to change whether the template is outdated, may be derived, may be instantiated, whether instances may be migrated to and whether instances are changeable.
Template status locks are the same locks used for changing templates. When locking a template status no other user except the locking one may lock/have locked the corresponding template.

Parameters:

session - The session which is used to check for access rights on this method and to identify the locking agent and the corresponding organisational position.

templateID - The ID of the template to get and manipulate the status of.

Returns:

An object containing the status of the designated process template.

Throws:

LockException - If the corresponding status object or the corresponding template is subject to change and therefore already locked (except by the designated user), a LockException will be thrown.

setTemplateStatus

void setTemplateStatus(SessionToken session,
                       TemplateStatus templateStatus)
                throws LockException,
                       InvalidTemplateStateException

Sets the status of the template (identified by the template status object), to the new status. The caller needs to have the lock on the template status.

Parameters:

session - The session which is used to check for access rights on this method and to identify the setting agent and the corresponding organisational position.

templateStatus - The object containing the new status of the process template.

Throws:

LockException - If the corresponding status object is not locked by the designated user, a LockException will be thrown.

InvalidTemplateStateException - If the template of the designated status cannot be changed accordingly (set to outdated or not usable as referenced subprocess any more) since it is currently used as reference subprocess, a TemplateStateException will be thrown.

unlockTemplateStatus

int unlockTemplateStatus(SessionToken session,
                         java.util.UUID templateID)
                  throws LockException

Unlocks the status of the designated template, ignores made changes and releases the lock on the process template status. Unlocking will fail, if the designated user does not have the lock on the template status. In case of an exception, the lock will not be released and still be held by the current lock owning user!

Parameters:

session - The session which is used to check for access rights on this method and to identify the unlocking agent and the corresponding organisational position.

templateID - The ID of the template to unlock the status of.

Returns:

The amount of locks remaining on the template status (or template if both use the same lock) by the designated user after this unlock.

Throws:

LockException - If the corresponding status object is not locked by the designated user, a LockException will be thrown.

retrieveTemplateDeltaLayer

TemplateDeltaLayer retrieveTemplateDeltaLayer(SessionToken session,
                                              java.util.UUID templateID)

Retrieves graph structures (deltas) representing all changes of the designated template relative to the null template. Because of their nature, the structures are purged before retrieval.

Parameters:

session - The session which is used to check for access rights on this method.

templateID - The ID of the process template of which the history is retrieved.

Returns:

The complete change history (relative to the null template) as graph structures (deltas).

retrieveTemplateDeltaLayer

TemplateDeltaLayer retrieveTemplateDeltaLayer(SessionToken session,
                                              java.util.UUID templateID,
                                              java.util.UUID ancestorTemplateID)

Retrieves graph structures (deltas) representing all changes of the designated template relative to the designated parent template. Because of their nature, the structures are purged before retrieval. If the designated parent template is not an ancestor of the first one, an IllegalArgumentException will be raised.

Parameters:

session - The session which is used to check for access rights on this method.

templateID - The ID of the process template of which the history is retrieved.

ancestorTemplateID - The ID of the ancestor template or 0 for the null template.

Returns:

The complete change history relative to the designated ancestor template as an XML-document.

Throws:

java.lang.IllegalArgumentException - If the ancestorTemplateID does not correspond to an ancestor process template of processTemplateID, an IllegalArgumentException will be raised.