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

    States of a process template

    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.

    See Also:
    ProcessConstants

    • Field Detail

      • CHECK_REPORT_ID

        static final String CHECK_REPORT_ID
        The ID used by process repository specific process check reports.
        See Also:
        Constant Field Values

    • Method Detail

      • getAllTemplateProxies

        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<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. The caller is responsible for closing.

      • getTemplateProxy

        TemplateProxy getTemplateProxy​(SessionToken session,
                               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,
                     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,
                                      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,
                          Document history,
                          TemplateDeltaLayer structuralChanges,
                          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,
                   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,
                             UUID templateId,
                             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.

      • release

        void release​(SessionToken session,
             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,
                           UUID templateID,
                           Set<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

        Collection<CheckReport> deployProcessTemplate​(SessionToken session,
                                              UUID templateId,
                                              Collection<URI[]> pmUris,
                                              boolean includeReferenced,
                                              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,
                                 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,
                                        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,
                         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,
                                              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,
                                              UUID templateID,
                                              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:
        IllegalArgumentException - If the ancestorTemplateID does not correspond to an ancestor process template of processTemplateID, an IllegalArgumentException will be raised.