de.aristaflow.adept2.core.processmanager

Interface TemplateManager

public interface TemplateManager

This sub-interface of the process manager handles all runtime issues of process templates. It allows to store process templates, retrieve specific process templates and manages the status of templates, for instance, outdate a template or disallow instantiation.
Template status objects use a simple lock mechanism when manipulated. They are locked when retrieved for changing and unlocked when the changes are committed. If a template status object is locked when accessed or unlocked although the commit is called, a LockException will be thrown.
If the designated template ID on any method expecting one does not exist, an IllegalArgumentException will be thrown.

Methods not throwing a LockException do not synchronise that is the retrieved data may be slightly out of date.

Implementors of this interface should take special care of synchronising template locks with instance locks. When locking a template status, instances should neither be created nor changed on the corresponding template since the template status change may allow/disallow this in the future.

The template manager needs to handle embedded templates appropriately. This means they need to be stored separately just like referenced templates, they need to be retrieved separately. Additionally, since an embedded template has no status of its own, a request for the status of an embedded template is replied with the status of the corresponding parent template.

Author:

Ulrich Kreher

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TemplateManager.TemplateKind A template can be of different kind: normal (top-level or referenced subprocess), embedded (as subprocess), specific for one instance (modified template), an embedded template that is specific to one instance (but itself unmodified) or an embedded and modified template.

Method Summary

Modifier and Type	Method and Description
SerialisablePair<java.util.Collection<java.util.UUID>,java.util.Map<java.util.UUID,java.util.UUID>>	archiveTemplate(SessionToken session, java.util.UUID templateID) Archives the designated template, which removes: the template itself, modified templates based on this template, its embedded templates, all corresponding template statuses, all of its instances (including the ones from the modified and embedded templates based on the designated template, all corresponding instance statuses, This also archives all corresponding instances.
java.util.Set<TemplateReference>	findTemplates(SessionToken session, Filter templateFilter, Filter templateStatusFilter) Finds all templates (except embedded and instance-specific ones) matching the two filters on Template and TemplateStatus and returns their template references.
RemoteIterator<java.util.List<TemplateReference>>	findTemplatesIterator(SessionToken session, Filter templateFilter, Filter templateStatusFilter) The same as findTemplates(SessionToken, Filter, Filter) but with partial retrieval of the template references.
java.util.Set<java.util.UUID>	getAllTemplateIDs(SessionToken session) Gets the IDs of all process templates managed by this process manager except IDs of separated embedded process templates and instance-specific templates.
java.util.Set<java.util.UUID>	getAllTemplateIDs(SessionToken session, TemplateManager.TemplateKind kind) Gets the IDs of all process templates managed by this process manager of the designated kind.
RemoteIterator<java.util.List<java.util.UUID>>	getAllTemplateIDsIterator(SessionToken session) The same as getAllTemplateIDs(SessionToken) but with partial retrieval of the template IDs.
RemoteIterator<java.util.List<java.util.UUID>>	getAllTemplateIDsIterator(SessionToken session, TemplateManager.TemplateKind kind) The same as getAllTemplateIDs(SessionToken, TemplateKind) but with partial retrieval of the template IDs.
java.util.Set<TemplateReference>	getAllTemplateReferences(SessionToken session) Gets the lightweight representations of all process templates managed by this process manager except the ones for embedded and instance-specific process templates.
RemoteIterator<java.util.List<TemplateReference>>	getAllTemplateReferencesIterator(SessionToken session) The same as getAllTemplateReferences(SessionToken) but with partial retrieval of the template references.
TemplateStatus	getAndLockTemplateStatus(SessionToken session, java.util.UUID templateID) Gets an object containing the status of the designated process template and locks the template 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 conforming to the ADEPT2-process model.
TemplateManager.TemplateKind	getTemplateKind(SessionToken session, java.util.UUID templateID) Gets the kind of the template with the designated ID, that is whether the template is embedded and/or instance-specific.
TemplateReference	getTemplateReference(SessionToken session, java.util.UUID templateID) Gets the lightweight representation 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	setTemplateStatus(SessionToken session, TemplateStatus templateStatus) Sets the status of the template (identified by the template status object), to the new status.
CheckReport	storeNewTemplate(SessionToken session, Template template, TemplateStatus templateStatus, java.util.Locale... locales) Stores the designated template and the corresponding status object in the process manager.
CheckReport	storeNewTemplates(SessionToken session, Template[] templates, TemplateStatus[] templateStatuses, java.util.Locale... locales) Stores the designated templates and the corresponding status objects in the process manager.
void	unlockTemplateStatus(SessionToken session, java.util.UUID templateID) Unlocks the status of the designated template, ignores made changes and and releases the lock on the process template status.

Method Detail

getTemplate

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

Gets the designated process template conforming to the ADEPT2-process model. The returned template can not be changed.
This method also returns embedded templates as stand-alone.

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.

getTemplateReference

TemplateReference getTemplateReference(SessionToken session,
                                       java.util.UUID templateID)

Gets the lightweight representation of the designated process template. This method also returns lightweight representations of embedded templates.

Parameters:

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

templateID - The ID of the process template to retrieve the lightweight representation of.

Returns:

The lightweight representation of the designated process template.

getTemplateKind

TemplateManager.TemplateKind getTemplateKind(SessionToken session,
                                             java.util.UUID templateID)

Gets the kind of the template with the designated ID, that is whether the template is embedded and/or instance-specific.

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 get the kind of.

Returns:

The kind of the designated template, that is, normal, embedded, instance-specific for embedded instance-specific.

getAllTemplateReferences

java.util.Set<TemplateReference> getAllTemplateReferences(SessionToken session)

Gets the lightweight representations of all process templates managed by this process manager except the ones for embedded and instance-specific process templates.

Parameters:

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

Returns:

The lightweight representations of all (top-level) process templates managed by this process manager.

getAllTemplateReferencesIterator

RemoteIterator<java.util.List<TemplateReference>> getAllTemplateReferencesIterator(SessionToken session)

The same as getAllTemplateReferences(SessionToken) but with partial retrieval of the template references.

Parameters:

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

Returns:

The lightweight representations of all (top-level) process templates managed by this process manager as iterator.

getAllTemplateIDs

java.util.Set<java.util.UUID> getAllTemplateIDs(SessionToken session)

Gets the IDs of all process templates managed by this process manager except IDs of separated embedded process templates and instance-specific templates.

Parameters:

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

Returns:

The IDs of all (top-level) process templates managed by this process manager.

getAllTemplateIDs

java.util.Set<java.util.UUID> getAllTemplateIDs(SessionToken session,
                                                TemplateManager.TemplateKind kind)

Gets the IDs of all process templates managed by this process manager of the designated kind.

Parameters:

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

kind - The kind of templates to retrieve the IDs of.

Returns:

The IDs of all process templates managed by this process manager of the designated kind.

getAllTemplateIDsIterator

RemoteIterator<java.util.List<java.util.UUID>> getAllTemplateIDsIterator(SessionToken session)

The same as getAllTemplateIDs(SessionToken) but with partial retrieval of the template IDs.

Parameters:

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

Returns:

The IDs of all (top-level) process templates managed by this process manager as iterator.

getAllTemplateIDsIterator

RemoteIterator<java.util.List<java.util.UUID>> getAllTemplateIDsIterator(SessionToken session,
                                                                         TemplateManager.TemplateKind kind)

The same as getAllTemplateIDs(SessionToken, TemplateKind) but with partial retrieval of the template IDs.

Parameters:

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

kind - The kind of templates to retrieve the IDs of.

Returns:

The IDs of all process templates managed by this process manager of the designated kind as iterator.

findTemplates

java.util.Set<TemplateReference> findTemplates(SessionToken session,
                                               Filter templateFilter,
                                               Filter templateStatusFilter)

Finds all templates (except embedded and instance-specific ones) matching the two filters on Template and TemplateStatus and returns their template references.

Parameters:

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

templateFilter - the filter on the the Templates (optional)

templateStatusFilter - the filter on the template's status (optional)

Returns:

a set of TemplateReferences that match the filters

findTemplatesIterator

RemoteIterator<java.util.List<TemplateReference>> findTemplatesIterator(SessionToken session,
                                                                        Filter templateFilter,
                                                                        Filter templateStatusFilter)

The same as findTemplates(SessionToken, Filter, Filter) but with partial retrieval of the template references.

Parameters:

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

templateFilter - the filter on the the Templates (optional)

templateStatusFilter - the filter on the template's status (optional)

Returns:

A set of TemplateReferences that match the filters as iterator.

storeNewTemplate

CheckReport storeNewTemplate(SessionToken session,
                             Template template,
                             TemplateStatus templateStatus,
                             java.util.Locale... locales)

Stores the designated template and the corresponding status object in the process manager. It is checked whether the template already exists. If it does, it will not be stored again.
A check report will be provided. Please refer to it for determining whether the storage was successful (CheckReport.getCheckResult() is either CheckReport.ResultType#OK or CheckReport.ResultType#INFO).

Parameters:

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

template - The representation of a process template conforming to the ADEPT2-process model.

templateStatus - The status object for the designated 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:

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).

storeNewTemplates

CheckReport storeNewTemplates(SessionToken session,
                              Template[] templates,
                              TemplateStatus[] templateStatuses,
                              java.util.Locale... locales)

Stores the designated templates and the corresponding status objects in the process manager. Every template is checked whether it already exists. If it does, it will not be stored again.
To allow for process template hierarchies, this method accepts multiple templates. Be sure to store dependent templates after storing the template they depend on (from subprocess to top-level-process).
A check report will be provided. Please refer to it for determining whether the storage was successful (CheckReport.getCheckResult() is either CheckReport.ResultType#OK or CheckReport.ResultType#INFO).

Parameters:

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

templates - The representations of process templates conforming to the ADEPT2-process model. Process hierarchies have to be ordered so that the top-level-process template is at the end.

templateStatuses - The status objects corresponding to the templates at the same index in the array.

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 the storage was successful ( CheckReport.ResultType#OK and CheckReport.ResultType#INFO).

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 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 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. The template is locked by the designated user.
Neither a process template nor its status may be retrieved when it has been locked, except by the user who locked it (reentrant lock).

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 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

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

Unlocks the status of the designated template, ignores made changes and 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.

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.

Throws:

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

archiveTemplate

SerialisablePair<java.util.Collection<java.util.UUID>,java.util.Map<java.util.UUID,java.util.UUID>> archiveTemplate(SessionToken session,
                                                                                                                    java.util.UUID templateID)
                                                                                                             throws InvalidTemplateStateException,
                                                                                                                    InvalidInstanceStateException,
                                                                                                                    LockException,
                                                                                                                    DataConsistencyException

Archives the designated template, which removes:

• the template itself,
• modified templates based on this template,
• its embedded templates,
• all corresponding template statuses,
• all of its instances (including the ones from the modified and embedded templates based on the designated template,
• all corresponding instance statuses,

This also archives all corresponding instances. For this to work, none of the templates, template statuses and instances (as well as their status) may be locked. Additionally, all templates may not be instantiable and they need to be outdated for top-level as well as subprocess usage ( TemplateStatus.isInstantiable(boolean) and TemplateStatus.isOutdated(boolean)), all of their instances have to be IE_FINISHED or IE_ABORTED. The designated template must neither be an embedded one nor a modified one. The latter can be archived by archiving the corresponding instance.

Use this method carefully! Archiving one template will also archive a lot of dependent data. When archiving distributed template hierarchies (parent or child templates are handled by different template managers), one has to take care of the consistency manually.

Parameters:

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

templateID - The ID of the template which to remove from this template manager.

Returns:

The IDs of all archived templates (first element of the pair) and a map of all archived instances (second element of the pair. The instances provide the logical ID (key) and the log ID (value). The template IDs will contain normal and embedded templates but no IDs of modified templates.

Throws:

InvalidTemplateStateException - If one of the templates to be removed is instantiable or not outdated for top-level or subprocess usage, an InvalidTemplateStateException will be thrown.

InvalidInstanceStateException - If one of the instances of the designated template is not IE_FINISHED or IE_ABORTED, an InvalidInstanceStateException will be thrown.

LockException - If the designated template can not be removed since a lock is held on either the template, its status, or one of its instances or instance status, a LockException will be thrown.

DataConsistencyException - If removing the template leads to inconsistencies, that is, the prerequisites (other than the template status) are not fulfilled, a DataConsistencyException will be thrown.