Package de.aristaflow.adept2.model.processmodel

Interface ChangePrimitives

  • All Known Subinterfaces:
    ChangeableInstance, ChangeableTemplate
    public interface ChangePrimitives

    The ProcessChangePrimitive interface provides all basic functions for changing a process (template or instance). These primitive functions do not care about the graph being valid and might leave it invalid. Their purpose is to provide all basic needs for a higher level set of change operations.

    If the following descriptions refer to a "process", it is either a Template or an Instance. TODO describe change transactions; usage of topo-IDs, branchIDs, splitNodeIDs, correspondingBIDs within a transaction is not allowed / possible. TODO describe the different internal behaviour of the primitives concerning changes on template and instance level. ########## TODO Add a generic description like the following If this method is called in the context of an instance specific change, the changed attribute (including at least the id of the data element) is stored in the delta layer. In the context of a process type change (Template) - in addition to storing the changed attribute in the delta layer - the attribute specified by dataElementProperty is overwritten by the changed attribute value included in the dataElement object, i.e the change is materialised (see TWiki "Flexibilitaet" for further detail). ########### While performing changes it may not be relied on the topological sorting. This applies to internal functions of template as well as functions using the topological sorting. Depending on the implementation of the processmodel the described situation can be pointed out by setting a special "topSortUsable" flag at the beginning of a change transaction which is reset at the end of the transaction by endTransaction() .

    Note: TODO This part needs further description concerning pre-conditions and effects of the functions! Furthermore its important to describe the differences between the implementation of the change primitives for templates (direct materialisation and delta layer)and instances (only delta layer).

    • Method Detail

      • startTransaction

        void startTransaction()
        Signals the beginning of a change transaction. See ChangePrimitives for further information.

      • endTransaction

        void endTransaction()
        Signals the end of a change transaction and corrects the topological sorting.
        After calling this method, the topological sorting, the split node IDs, the corresponding block node IDs and the branch IDs must be valid again.
        The topological sorting is corrected within this method; the other IDs (branchID etc) have to be set by the change operations. See ChangePrimitives for further information.

      • setName

        void setName​(String name)
        Set the name of the process.
        Parameters:
        name - The name of the process.

      • setSupervisorAgent

        void setSupervisorAgent​(QualifiedAgent supervisorAgent)
        Set the agent ID of the supervisor of the process.
        Parameters:
        supervisorAgent - The supervisor agent of the process.

      • setInputParameters

        void setInputParameters​(Set<ProcessModelParameter> inputParameters)
        Sets the input parameters of the process.
        Parameters:
        inputParameters - the input parameters

      • setOutputParameters

        void setOutputParameters​(Set<ProcessModelParameter> outputParameters)
        Sets the output parameters of the process.
        Parameters:
        outputParameters - the output parameters

      • addNode

        Node addNode​(Node node)
        Creates a new node in the process, using the data of the given object. The parameter is just a container of the node data. The object itself will be thrown away after copying its data to the new Node. The newly created node object, including its system generated ID will be returned. The following node properties will be copied from the given object:
        • NAME
        • EXECUTABLE_BUSINESS_PROCESS
        • USER_ATTRIBUTE
        • DESCRIPTION
        • STAFF_ASSIGNMENT_RULE
        Other attributes will be discarded, since they either must be set using other change primitives, or are set implicitly. The property EXECUTABLE_BUSINESS_PROCESS may be null. If it is set, addNode will implicitly create connectors and map them to parameter names. The values for the property NAME must not be null. If the value of the property USER_ATTRIBUTE is null, it is assumed that no user attributes exist. TODO describe required steps which will be done by addNode to keep the delta layer automatically purged.
        Parameters:
        node - The data for the new node.
        Returns:
        The newly created node as object.

      • updateNode

        Node updateNode​(Node node,
                ProcessConstants.NodeProperty... nodeProperties)
        Updates a node object using the data in the given node. The given node is just used as a temporary container for the new values. The properties specify which attributes of the node will be updated. The following properties may be updated from the given object:
        • NAME
        • DESCRIPTION
        • STAFF_ASSIGNMENT_RULE
        • EXECUTABLE_BUSINESS_PROCESS (and implicitly CONNECTOR_PARAMETER_MAPPING)
        • SYSTEM_READ_PARAMS
        • SYSTEM_WRITE_PARAMS
        Removing the ExecutableBusinessProcsess from a node:
        If EXECUTABLE_BUSINESS_PROCESS is set in the parameter nodeProperties and getExecutableBusinessProcess() of the given node returns null, the EBP and the parameter/data-connector mapping is removed from the node as well as all data-connectors which are not connected (i.e marked as disabled or connect later) with a data edge.
        Setting a new ExecutableBusinessProcsess to a node:
        If the property EXECUTABLE_BUSINESS_PROCESS is set, and the attribute returns a value, the returned ExecutableBusinessProcess will be used as a new EBP. This means that the old EBP is removed (like described above), and afterwards added. Changing attributes of the ExecutableBusinessProcsess of a node:
        Please use updateExecutableBusinessProcess(int, ExecutableBusinessProcess, ExecutableBusinessProcessProperty[]).
        Note: The declaration of CONNECTOR_PARAMETER_MAPPING in nodeProperties is senseless because the data parameter mapping is always changed if the ebp is changed. Therefore calling the method with the argument CONNECTOR_PARAMETER_MAPPING will produce an exception. In turn to that calling the method with EXECUTABLE_BUSINESS_PROCESS forces the user to store a correct connector mapping in the given node object.
        Parameters:
        node - A temporary node object, containing the new values.
        nodeProperties - Possible values of NodeProperty are described above.
        Returns:
        The updated node object from the process.

      • removeNode

        void removeNode​(int nodeID)
        Removes the node with the given ID from the template, without caring about any possibly affected edges. Ensures that all node attributes (including corresponding block node, connectors, etc.) are deleted.
        Parameters:
        nodeID - The ID of the node to be removed.

      • setNodeType

        void setNodeType​(int nodeID,
                 ProcessConstants.NodeType type)
        Sets the type of the given node. The type characterises the functionality of a node. It can be one of NT_NORMAL, NT_STARTFLOW, NT_ENDFLOW, NT_AND_SPLIT, NT_AND_JOIN, NT_XOR_SPLIT, NT_XOR_JOIN, NT_STARTLOOP or NT_ENDLOOP. If the node with the given nodeId does not exists an IllegalArgumentException is thrown.
        Parameters:
        nodeID - The ID of the node to be changed.
        type - the type the node is to be set
        Throws:
        IllegalArgumentException - if nodeID does not exist
        See Also:
        Template.getNodeType(int)

      • setCorrespondingBlockNode

        void setCorrespondingBlockNode​(int split,
                               int join)
        Sets the corresponding block node attribute for the split node with ID split to the value given by join.
        Parameters:
        split - ID of the split node.
        join - ID of the corresponding join node.

      • setBranchID

        void setBranchID​(int startNodeID,
                 int endNodeID,
                 boolean newIDNecessary,
                 int existingID)
        Sets the branch ID attribute of the nodes between startNodeID and endNodeID. startNodeID and endNodeID have to be on the same branch, nodes which are inside of blocks on that branch, are not considered. Preconditions: - To be able to navigate through the graph, all edges within the given range must be set. - For efficient navigation, all split-nodes between startNodeID and endNodeID must have their corresponding join-node attribute set. If the parameter newIDNecessary is set to true, a new branch ID will be created and set (in this case, the value of existingID will be ignored). If the parameter newIDNecessary is set to false, the branchID in the parameter existingID will be set. Note: The given branchID must already exist!
        Parameters:
        startNodeID - The ID of the node which marks the beginning of the sequence.
        endNodeID - The ID of the node which marks the end of the sequence.
        newIDNecessary - If set to true, a new branch ID will be generated and used.
        existingID - If newIDNecessary is false, this ID will be used.

      • setSplitNodeID

        void setSplitNodeID​(int startNodeID,
                    int endNodeID,
                    int splitNodeID)
        Sets the split node ID attribute of the nodes between startNodeID and endNodeID. startNodeID and endNodeID have to be on the same branch, nodes which are inside of blocks on that branch, are not considered. Preconditions: - To be able to navigate through the graph, all edges within the given range must be set. - For efficient navigation, all split-nodes between startNodeID and endNodeID must have their corresponding join-node attribute set. The ID of the parameter splitNodeID will be set to all of the described nodes. Note: The node of the given ID must exist in the process.
        Parameters:
        startNodeID - The ID of the node which marks the beginning of the sequence.
        endNodeID - The ID of the node which marks the end of the sequence.
        splitNodeID - The ID of the split node.

      • reMapDataElement

        void reMapDataElement​(int dataElementID,
                      int nodeID,
                      ActivityConstants.AccessType type,
                      String parameterName)
        This method remaps a data element to the given parameter of a node. Thereby the data edge between the data element and the node with the given data access type must already exist and the parameter must not be marked as disabled (otherwise exceptions are thrown; Note: the initial mapping is created with addDataEdge). Furthermore node must have an assigned ebp at all. The intended task of this method is to change the already existent logical mapping between a data element and a parameter of an ebp. Example of intended usage: Activity a1 assigned to node n1 has to input parameters (ip1, ip2) with the same type. ip1 is connected to connector c1, ip2 is connected to c2. Furthermore data edges between n1 and data element d1 and n1 and data element d2 exists. Now data element d2 should be mapped to ip1 and d1 to ip2. To achieve this the connectorID where d2 is connected with (c2) must be changed from c2 to c1 (d1 analogous). Thereby the "inner" mapping between ip1 and c1 and ip2 and c2 can remain unchanged. Similar scenario if ip2 is unconnected.
        Parameters:
        dataElementID -
        nodeID -
        type -
        parameterName -

      • addDisabledConnector

        void addDisabledConnector​(int nodeID,
                          int connectorID)
        Adds the information that a connector (respectively its corresponding parameter) is disabled to the template
        Parameters:
        nodeID - the id of the node where the connector is to be marked as disabled
        connectorID - the connector id

      • removeDisabledConnector

        void removeDisabledConnector​(int nodeID,
                             int connectorID)
        Removes the information that a connector (respectively its corresponding parameter) is disabled
        Parameters:
        nodeID - the id of the node where the disabled connector is to be removed
        connectorID - the connector id

      • updateExecutableBusinessProcess

        void updateExecutableBusinessProcess​(int nodeID,
                                     ExecutableBusinessProcess ebp,
                                     ProcessConstants.ExecutableBusinessProcessProperty... ebpProperties)
        Updates the Executable Business Process of the node with the given ID, using the values of the given EBP object. The EBP object is used as an container only. The following attributes / properties of the EBP may be updated (depending on the type of the EBP, i.e. an Activity or an LWP):
        • NAME
        • STAFF_ASSIGNMENT_RULE (Activity)
        • EXECUTABLE_COMPONENT_NAME (Activity)
        • CONFIGURATION (Activity)
        • TEST_CONFIGURATION (Activity)
        The EBP will not be replaced by the given EBP object (use updateNode with property EXECUTABLE_BUSINESS_PROCESS). Updating user attributes is done using updateUserAttribute.
        Parameters:
        nodeID - The ID of the node, the given EBP belongs to.
        ebp - The executable business process.
        ebpProperties - The properties of the EBP which should be updated.
        See Also:
        ExecutableBusinessProcess

      • addEdge

        Edge addEdge​(int srcNodeID,
             int destNodeID,
             Edge edge)
        Add an edge between the given nodes, using the values of the given edge object (e.g. the edge type). The given edge object is used as a container only and will be thrown away. The implementation of the primitive adds the structural information and the element information. The following attributes / properties of the given edge will be used:
        • TYPE
        • EDGE_CODE
        • USER_ATTRIBUTE
        If the value of the USER_ATTRIBUTE property is null, it will be assumed that the edge does not have any user attribute. The value of TYPE must not be null.
        Parameters:
        srcNodeID - The source node.
        destNodeID - The destination node.
        edge - The object containing the values for the new edge.
        Returns:
        The new edge object.
        See Also:
        ProcessConstants.EdgeType

      • updateEdge

        Edge updateEdge​(int srcNodeID,
                int destNodeID,
                Edge edge,
                ProcessConstants.EdgeProperty... edgeProperty)
        Updates the edge which is identified by the given source and destination node IDs and the type of the edge (i.e. stored in the Edge object). The edge object is used as a container only and will not be used afterwards. The following properties may be updated:
        • EDGE_CODE
        Parameters:
        srcNodeID - The ID of the node the Edge starts at.
        destNodeID - The ID of the node the Edge ends at.
        edge - The temporary Edge object conatining the new values.
        edgeProperty - The values to be updated.
        Returns:
        The updated edge object.

      • removeEdge

        void removeEdge​(int srcNodeID,
                int destNodeID,
                ProcessConstants.EdgeType edgeType)
        Removes the edge of the given type between the given nodes.
        Parameters:
        srcNodeID - The ID of the source node.
        destNodeID - The ID of the destination node.
        edgeType - The type of the edge.

      • addDataElement

        DataElement addDataElement​(DataElement dataElement)
        Adds a new data element to the process, using the values of the given data element object. The given data element will be used as a container only. The following attributes / properties will be used from the given object:
        • NAME
        • TYPE
        • USER_DEFINED_TYPE
        • IDENTIFIER
        • VIRTUAL
        • USER_ATTRIBUTE
        The property USER_DEFINED_TYPE will only be used, if the TYPE of the data element is ProcessConstants.AdeptDataType.USERDEFINED. If the value of the USER_ATTRIBUTE property is null, it will be assumed that the data element does not have any user attribute. All other attributes must be set.
        Parameters:
        dataElement -
        Returns:
        The newly created data element.

      • updateDataElement

        DataElement updateDataElement​(DataElement dataElement,
                              ProcessConstants.DataElementProperty... dataElementProperties)
        Updates the data element attributes given by dataElementProperties. The values of the changed attributes are contained in the given dataElement itself. The given data element is used as a container only. The following attributes / properties may be updated:
        • NAME
        • DESCRIPTION
        • TYPE
        • USER_DEFINED_TYPE
        • IDENTIFIER
        • VIRTUAL
        Parameters:
        dataElement - The name of the data element.
        dataElementProperties - A constant describing the changed data element attribute
        Returns:
        The updated data element object.

      • removeDataElement

        void removeDataElement​(int dataElementID)
        Removes a data element from a process, without caring about existing data accesses from nodes.
        Parameters:
        dataElementID - The ID of the data element to remove.

      • addDataEdge

        DataEdge addDataEdge​(int node,
                     int connector,
                     int dataElement,
                     DataEdge dataEdge)
        This method is called when the node has an assigned activity. The caller has to specify an existing connector. Furthermore the connector must not be marked as disabled, otherwise an IllegalArgumentException is thrown. Note: If a data element should be connected to a connector which is marked as disabled call removeDisabledConnector(node, connector) first to mark the connector as unconnected
        Parameters:
        node - The node which is accessing the data element.
        connector - the connector where the data edge is connected to
        dataElement - The data element which will be accessed
        dataEdge -
        Returns:
        the new DataEdge

      • addDataEdge

        DataEdge addDataEdge​(int node,
                     int dataElement,
                     DataEdge dataEdge)
        Use this method to connect a data element to a node which does not have an assigned activity yet. If it is called for a node which already has an assigned activity, a runtime exception will be thrown. This is due to the fact that there may not be any connectors not connected to a parameter when there is already an activity assigned. To take care about the connector concept, this method implicitly creates a new connector.
        Parameters:
        node - The node which is accessing the data element.
        dataElement - The data element which will be accessed
        dataEdge - a temporary data edge object which contains the data edge attributes
        Returns:
        a data edge object

      • updateDataEdge

        DataEdge updateDataEdge​(int nodeID,
                        int dataElementID,
                        ActivityConstants.AccessType accessType,
                        DataEdge dataEdge,
                        ProcessConstants.DataEdgeProperty... dataEdgeProperties)
        Updates the data edge attribute given by dataEdgeProperty. The values of the changed attributes are contained in the given dataEdge itself. The following attributes / properties are changeable:
        • OPTIONAL
        • VIRTUAL
        Parameters:
        nodeID - The ID of the node which is accessing the dataElement.
        dataElementID - The ID of the DataElement which is accessed.
        accessType - Whether the DataElement is read or written.
        dataEdge - The data edge values which are updated, in a container object.
        dataEdgeProperties - The properties which are updated.
        Returns:
        The updated data edge object.

      • removeDataEdge

        void removeDataEdge​(int node,
                    int dataElement,
                    ActivityConstants.AccessType dataEdgeType)
        Removes the data edge between the given node and data element and of the given access type from the process. This method implicitly removes a connector, as long as there is no assigned activity, which means, the connector is linked to a parameter.
        Parameters:
        node - The node which is accessing the data element.
        dataElement - The data element which has been accessed
        dataEdgeType - the type of access (read or write)

      • updateUserAttribute

        void updateUserAttribute​(UserAttributeContainer container,
                         String name,
                         String value)
        Sets the value of the user defined attribute identified by name to value. User attribute containers are e.g. Node, Edge, DataElement, ...
        Parameters:
        container - The attribute container.
        name - The name of the user defined attribute to be modified.
        value - The new value.

      • removeUserAttribute

        void removeUserAttribute​(UserAttributeContainer container,
                         String name)
        Removes the User defined Attribute identified by name.
        Parameters:
        container - The user attribute container.
        name - the Name of the User defined attribute to be removed

      • updatePluginDataContainer

        void updatePluginDataContainer​(PluginDataContainer pluginContainer,
                               String extensionPointID,
                               String pluginDataID,
                               PluginData pluginData)
        Sets the plug in data for the extension point in the plug in data container. A value of null for pluginData signals that the plug in with the given plug in ID should be removed (remove). If the container already contains the given plug in for the given extension point, the already existent pluginData is replaced with the given pluginData (update). If it does not exist the pluginData is added to the given extension point (add). Plug in data containers are e.g. Node, ...
        Parameters:
        pluginContainer - the plug in container object where the method is performed on
        extensionPointID - the extension point ID where the plug in data should be updated (added/removed) name
        pluginDataID - the ID of the plug in data
        pluginData - the object which holds the pluginData or null to remove from the extension point.

      • addMovedNode

        void addMovedNode​(int node)
        Adds a moved node as meta-information to a process Note: This method is not necessary for a correct process representation but essential for an efficient schema evolution. (By storing moved nodes a comparison between two changes becomes much easier). Therefore it has to be called for every node being moved by a changeoperation like moveNodes .
        Parameters:
        node - The name of the moved node