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

    • Field Detail

      • SUCCESSFULLY_STORED

        static final String SUCCESSFULLY_STORED
        The (prefix for the) check report message for the entry that all templates have been successfully stored. This allows to have check reports with CheckReport.ResultType.WARNING as final result type yet storing the templates succeeded since the warning does not prevent instantiating and running these templates.
        See Also:
        Constant Field Values

    • Method Detail

      • getTemplate

        Template getTemplate​(SessionToken session,
                     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,
                                       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,
                                             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

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

      • getAllTemplateIDs

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

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

      • findTemplates

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

      • storeNewTemplate

        CheckReport storeNewTemplate​(SessionToken session,
                             Template template,
                             TemplateStatus templateStatus,
                             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 not CheckReport.ResultType.FAILURE and the message of the last report entry starts with SUCCESSFULLY_STORED).
        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 it for determining whether the storage was successful (CheckReport.getCheckResult() is not CheckReport.ResultType.FAILURE and the message of the last report entry starts with SUCCESSFULLY_STORED).

      • storeNewTemplates

        CheckReport storeNewTemplates​(SessionToken session,
                              Template[] templates,
                              TemplateStatus[] templateStatuses,
                              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 not CheckReport.ResultType.FAILURE and the message of the last report entry starts with SUCCESSFULLY_STORED).
        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 it for determining whether the storage was successful (CheckReport.getCheckResult() is not CheckReport.ResultType.FAILURE and the message of the last report entry starts with SUCCESSFULLY_STORED).

      • 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 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 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,
                          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<Collection<UUID>,​Map<UUID,​UUID>> archiveTemplate​(SessionToken session,
                                                                              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.

      • getTemplateTrees

        Map<UUID,​TemplateNode> getTemplateTrees​(SessionToken session,
                                              String procType)
        Gets trees for all Templates belonging to the designated process type. The map contains the roots of the template trees indexed by the root template IDs.
        Parameters:
        session - The session which is used to check for access rights on this method.
        procType - The name of the process type for which to create the template trees.
        Returns:
        The roots of the template trees indexed by the corresponding root template ID.

      • getTemplateTree

        TemplateNode getTemplateTree​(SessionToken session,
                             TemplateReference root)
        Gets a template (sub-)tree of the designated Template.
        Parameters:
        session - The session which is used to check for access rights on this method.
        root - The template for which to create a template (sub-)tree.
        Returns:
        The template node of the designated template.