Package de.aristaflow.adept2.model.datamanagement

Interface DataContainer

  • All Superinterfaces:
    AutoCloseable, Cloneable, Closeable, InputDataContainer, PluginDataContainer, Serializable, TypedCloneable<DataContainer>, UserAttributeContainer
    All Known Subinterfaces:
    InstanceDataContainer
    public interface DataContainer
extends InputDataContainer, TypedCloneable<DataContainer>
    This interface encapsulates the data context of an application as provided by the execution manager for the runtime manager, that is, the values of the input and output parameters of an application. It extends InputDataContainer to also support writing and storing of (output) parameter values. The methods resemble the ones in ProcessAwareAccess but with less information. When using DataContainer only the name of the corresponding parameter and a session token is necessary since all other information (instance, data element, agent,...) is already provided when retrieving the container.
    The DataContainer also provides read access to the (intermediate) written data values. This allows to distinguish the input value and the already written output value of an INOUT-parameter (a parameter that is read as well as written). A significant implication of this is that a data container need to store every value written by an activity - internally or directly in the data manager. The latter requires that these values must not be read by another activity from the data manager before the writing activity has finished. Normally this is done by calling ProcessAwareAccess.validateWrittenValues(SessionToken, de.aristaflow.adept2.model.processmodel.Instance, int, int, String) after the data container has been flushed.
    The data container may be lazy, which means, it retrieves the values of the data elements when they are accessed. It is also allowed to be eager and store all values internally and it may be in-between, for instance, store simple values internally and retrieve big values lazily.
    Since this procedure also applies to storing, the data container has to be flushed to make all values persistent.

    A data container may also be stored intermediately for instance in case an application is running while the server is temporarily offline. Only unsaved values need to be stored in this case, use the getUnsave*-methods for this. After the server is online again, a new data container may be provided that provides the unsaved values when flushed.

    The retrieval of written values is also used for "re-executing" an already finished activity - if it supports this (see ProcessConstants.ExecutionMode.VIEW_ONLY). This execution mode provides the input parameter as well as the output parameters written by the corresponding activity. Since it is obviously not allowed to change any of these values, this container is read only and all writing methods of the corresponding data container throw an UnsupportedOperationException.

    Implementations of this interface may not store an Instance internally since a process instance must be accessible by other components. Instead, all needed information has to be encapsulated in the container. The instance may be provided, for instance, in the constructor, but the reference to it has to be released afterwards.

    • Field Detail

      • serialVersionUID

        static final long serialVersionUID
        Generated ID for serialisation.
        See Also:
        Constant Field Values

    • Method Detail

      • isReadOnly

        boolean isReadOnly()
        Returns whether this data container is read only and therefore does not allow to store values (and throws an UnsupportedOperationException at the corresponding methods).
        Returns:
        Whether this data container is read only and therefore does not allow to store values.

      • ignoreValue

        void ignoreValue​(SessionToken session,
                 String parameterName)
          throws NoSuchParameterException
        Ignores the value of the designated parameter. Per default every parameter value is unset, therefore this method is used to remove values that have been set by calling an appropriate store-method beforehand. This differs from setting a value explicitly to null (which is not allowed).
        Parameters:
        session - The session which is used to check for access rights on this method and to retrieve the accessing agent and the corresponding organisational position.
        parameterName - The name of the parameter to be ignored.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.

      • ignoredValue

        boolean ignoredValue​(String parameterName)
              throws NoSuchParameterException
        Returns whether the value of the designated output parameter is or has not been set (ignored) by the application.
        Parameters:
        parameterName - The name of the output parameter to check for being unset.
        Returns:
        true if the value of the designated output parameter is or has not been written.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.

      • storeInteger

        void storeInteger​(SessionToken session,
                  String parameterName,
                  long value)
           throws NoSuchParameterException,
                  InvalidDataTypeException
        Stores the INTEGER value of the designated parameter of the process instance and the corresponding metadata which is the writing node and its current iteration.
        Parameters:
        session - The session which is used to check for access rights on this method and to retrieve the accessing agent and the corresponding organisational position.
        parameterName - The name of the parameter to be stored.
        value - The value as Java-type long of the parameter of ADEPT2-type INTEGER.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated parameter is not of type INTEGER, an InvalidDataTypeException will be raised.
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.INTEGER

      • storedInteger

        long storedInteger​(String parameterName)
            throws NoSuchParameterException,
                   InvalidDataTypeException
        Retrieves the long value of the designated output parameter of type INTEGER stored before. Callers should first check whether the value is NULL by calling ignoredValue(String). Otherwise in case of NULL an IllegalStateException will be thrown.
        Parameters:
        parameterName - The name of the output parameter to be read.
        Returns:
        The value of the parameter of ADEPT2-type INTEGER and of Java-type long.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated output parameter is not of type INTEGER, an InvalidDataTypeException will be raised.
        IllegalStateException - If the value of the designated parameter is NULL an IllegalStateException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.INTEGER

      • storeFloat

        void storeFloat​(SessionToken session,
                String parameterName,
                double value)
         throws NoSuchParameterException,
                InvalidDataTypeException
        Stores the FLOAT value of the designated parameter of the process instance and the corresponding metadata which is the writing node and its current iteration.
        Parameters:
        session - The session which is used to check for access rights on this method and to retrieve the accessing agent and the corresponding organisational position.
        parameterName - The name of the parameter to be stored.
        value - The value as Java-type double of the parameter of ADEPT2-type FLOAT.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated parameter is not of type FLOAT, an InvalidDataTypeException will be raised.
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.FLOAT

      • storedFloat

        double storedFloat​(String parameterName)
            throws NoSuchParameterException,
                   InvalidDataTypeException
        Retrieves the double value of the designated output parameter of type FLOAT stored before. Callers should first check whether the value is NULL by calling ignoredValue(String). Otherwise in case of NULL an IllegalStateException will be thrown.
        Parameters:
        parameterName - The name of the output parameter to be read.
        Returns:
        The value of the output parameter of ADEPT2-type FLOAT and of Java-type double.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated output parameter is not of type FLOAT, an InvalidDataTypeException will be raised.
        IllegalStateException - If the value of the designated parameter is NULL an IllegalStateException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.FLOAT

      • storeBoolean

        void storeBoolean​(SessionToken session,
                  String parameterName,
                  boolean value)
           throws NoSuchParameterException,
                  InvalidDataTypeException
        Stores the BOOLEAN value of the designated parameter of the process instance and the corresponding metadata which is the writing node and its current iteration.
        Parameters:
        session - The session which is used to check for access rights on this method and to retrieve the accessing agent and the corresponding organisational position.
        parameterName - The name of the parameter to be stored.
        value - The value as Java-type boolean of the parameter of ADEPT2-type BOOLEAN.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated parameter is not of type BOOLEAN, an InvalidDataTypeException will be raised.
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.BOOLEAN

      • storedBoolean

        boolean storedBoolean​(String parameterName)
               throws NoSuchParameterException,
                      InvalidDataTypeException
        Retrieves the boolean value of the designated output parameter of type BOOLEAN stored before. Callers should first check whether the value is NULL by calling ignoredValue(String). Otherwise in case of NULL an IllegalStateException will be thrown.
        Parameters:
        parameterName - The name of the output parameter to be read.
        Returns:
        The value of the output parameter of ADEPT2-type BOOLEAN and of Java-type boolean.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated output parameter is not of type BOOLEAN, an InvalidDataTypeException will be raised.
        IllegalStateException - If the value of the designated parameter is NULL an IllegalStateException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.BOOLEAN

      • storeString

        void storeString​(SessionToken session,
                 String parameterName,
                 String value)
          throws NoSuchParameterException,
                 InvalidDataTypeException
        Stores the string value of the designated parameter of the process instance and the corresponding metadata which is the writing node and its current iteration.
        Parameters:
        session - The session which is used to check for access rights on this method and to retrieve the accessing agent and the corresponding organisational position.
        parameterName - The name of the parameter to be stored.
        value - The value as Java-type String of the parameter of ADEPT2-type STRING.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated parameter is not of type STRING, an InvalidDataTypeException will be raised.
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.STRING

      • storedString

        String storedString​(String parameterName)
             throws NoSuchParameterException,
                    InvalidDataTypeException
        Retrieves the string value of the designated output parameter of type STRING stored before. Callers should first check whether the value is NULL by calling ignoredValue(String). Otherwise in case of NULL an IllegalStateException will be thrown.
        Parameters:
        parameterName - The name of the output parameter to be read.
        Returns:
        The value of the output parameter of ADEPT2-type STRING and of Java-type String.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated output parameter is not of type STRING, an InvalidDataTypeException will be raised.
        IllegalStateException - If the value of the designated parameter is NULL an IllegalStateException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.STRING

      • storeDate

        void storeDate​(SessionToken session,
               String parameterName,
               Date value)
        throws NoSuchParameterException,
               InvalidDataTypeException
        Stores the DATE value of the designated parameter of the process instance and the corresponding metadata which is the writing node and its current iteration.
        Parameters:
        session - The session which is used to check for access rights on this method and to retrieve the accessing agent and the corresponding organisational position.
        parameterName - The name of the parameter to be stored.
        value - The value as Java-type java.util.Date of the parameter of ADEPT2-type DATE.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated parameter is not of type DATE, an InvalidDataTypeException will be raised.
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.DATE

      • storedDate

        Date storedDate​(String parameterName)
         throws NoSuchParameterException,
                InvalidDataTypeException
        Retrieves the date value of the designated output parameter of type DATE stored before. Callers should first check whether the value is NULL by calling ignoredValue(String). Otherwise in case of NULL an IllegalStateException will be thrown.
        Parameters:
        parameterName - The name of the output parameter to be read.
        Returns:
        The value of the parameter of ADEPT2-type DATE and of Java-type java.util.Date.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated output parameter is not of type DATE, an InvalidDataTypeException will be raised.
        IllegalStateException - If the value of the designated parameter is NULL an IllegalStateException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.DATE

      • storeURI

        void storeURI​(SessionToken session,
              String parameterName,
              URI value)
       throws NoSuchParameterException,
              InvalidDataTypeException
        Stores the URI value of the designated parameter of the process instance and the corresponding metadata which is the writing node and its current iteration.
        Parameters:
        session - The session which is used to check for access rights on this method and to retrieve the accessing agent and the corresponding organisational position.
        parameterName - The name of the parameter to be stored.
        value - The value as Java-type java.net.URI of the parameter of ADEPT2-type URI.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated parameter is not of type URI, an InvalidDataTypeException will be raised.
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.URI

      • storedURI

        URI storedURI​(String parameterName)
       throws NoSuchParameterException,
              InvalidDataTypeException
        Retrieves the URI value of the designated output parameter of type URI stored before. Callers should first check whether the value is NULL by calling ignoredValue(String). Otherwise in case of NULL an IllegalStateException will be thrown.
        Parameters:
        parameterName - The name of the output parameter to be read.
        Returns:
        The value of the parameter of ADEPT2-type URI and of Java-type java.net.URI.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the output designated parameter is not of type URI, an InvalidDataTypeException will be raised.
        IllegalStateException - If the value of the designated parameter is NULL an IllegalStateException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.URI

      • storeUDT

        void storeUDT​(SessionToken session,
              String parameterName,
              UDTValue value)
       throws NoSuchParameterException,
              InvalidDataTypeException
        Stores the value of user-defined type of the designated parameter of the process instance and the corresponding metadata which is the writing node and its current iteration.
        Parameters:
        session - The session which is used to check for access rights on this method and to retrieve the accessing agent and the corresponding organisational position.
        parameterName - The name of the parameter to be stored.
        value - The value of the parameter of ADEPT2-type USERDEFINED. The caller is responsible for closing.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated parameter is not of type USERDEFINED, an InvalidDataTypeException will be raised.
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.USERDEFINED

      • storedUDT

        UDTValue storedUDT​(String parameterName)
            throws NoSuchParameterException,
                   InvalidDataTypeException
        Retrieves (the proxy of) the value of the designated output parameter of user-defined type (UDT) stored before. Callers should first check whether the value is NULL by calling ignoredValue(String). Otherwise in case of NULL an IllegalStateException will be thrown.
        Parameters:
        parameterName - The name of the output parameter to be read.
        Returns:
        The value of the output parameter of ADEPT2-type USERDEFINED and of Java-type UDTValue. The UDTValue will be coupled to this DataContainer, so do not close it; clone it if required longer than this DataContainer.
        Throws:
        NoSuchParameterException - If the output parameter of the designated name does not exist, a NoSuchParameterException will be thrown.
        InvalidDataTypeException - If the designated output parameter is not of type USERDEFINED, an InvalidDataTypeException will be raised.
        IllegalStateException - If the value of the designated parameter is NULL an IllegalStateException will be thrown.
        See Also:
        ProcessConstants.AdeptDataType.USERDEFINED

      • storeSessionState

        void storeSessionState​(SessionToken session,
                       byte[] sessionState)
        Stores the state of the suspended activity this data container is associated with in order to enable the resume of the activity.
        When storing null the corresponding savepoint will be removed.
        Parameters:
        session - The session which is used to identify the user, to synchronise access and to check for access rights on this method.
        sessionState - A byte array that contains the state of the suspended activity or null.
        Throws:
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.

      • restoreSessionState

        byte[] restoreSessionState​(SessionToken session,
                           String savepoint)
        Restores the session context of an suspended activity to be resumed.
        Parameters:
        session - The session which is used to synchronise access and to check for access rights on this method.
        savepoint - The savepoint for which to retrieve the session state. Use null to get the current session state that has no savepoint yet.
        Returns:
        The session state as byte array or null in case no session state with the corresponding savepointID has been assigned to the activity.
        Throws:
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.

      • setSavepoint

        void setSavepoint​(SessionToken session,
                  String savepoint)
        Assigns the designated savepoint to the current state of the data, that is application state and data values. This is similar to commit an a versioning system except that persisting the savepoint (and its state) in the server (flushing) is optional.
        Parameters:
        session - The session which is used to synchronise access and to check for access rights on this method.
        savepoint - The identifier by which the current data state could be retrieved. This must neither be null nor the empty string.

      • getSavepoints

        List<String> getSavepoints​(SessionToken session)
        Returns the IDs of the stored savepoints kept in the DataContainer. Note that this list may contain the savepoint for the additional view-only data.
        Parameters:
        session - The session which is used to synchronise access and to check for access rights on this method.
        Returns:
        The IDs of the stored session states in the order they have been created (latest at the end).
        Throws:
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.

      • getLastSavepoint

        String getLastSavepoint​(SessionToken session)
        Returns the last savepoint stored within this data container.
        Parameters:
        session - The session which is used to synchronise access and to check for access rights on this method.
        Returns:
        The last savepoint stored for the designated activity or null in case no savepoint has been stored yet explicitly.
        Throws:
        UnsupportedOperationException - If this data container is only for displaying purpose, an UnsupportedOperationException will be thrown.

      • getInstanceID

        UUID getInstanceID()
        Gets the ID of the instance this data container is for a node of.
        Returns:
        The ID of the instance this data container is for a node of.

      • getNodeID

        int getNodeID()
        Gets the ID of the node for which this data container provides the parameter values. In case of a top-level instance data container this value is undefined.
        Returns:
        The ID of the node for which this data container provides the parameter values.

      • getNodeIteration

        int getNodeIteration()
        Gets the iteration of the node for which this data container provides the parameter values. In case of a top-level instance data container this value is undefined.
        Returns:
        The iteration of the node for which this data container provides the parameter values.

      • getUnsavedTypes

        Map<String,​ProcessConstants.AdeptDataType> getUnsavedTypes()
        Gets all names of unsaved parameters and the corresponding data types.
        Returns:
        All names of unsaved parameters and the corresponding data types.

      • getUnsavedIgnoredParameters

        Collection<String> getUnsavedIgnoredParameters​(String savepoint)
        Gets the names of the parameters for the designated savepoint that should be ignored and that have not been saved yet.
        Parameters:
        savepoint - The savepoint for which to retrieve the ignored parameter values that have not been saved yet. null is for all parameters ignored after the last savepoint.
        Returns:
        The names of the parameters for the designated savepoint that should be ignored and that have not been saved yet.

      • getUnsavedValues

        Map<String,​Serializable> getUnsavedValues​(String savepoint)
        Gets the parameter values for the designated savepoint that have not been saved yet. The map is from parameter name to corresponding value.
        Parameters:
        savepoint - The savepoint for which to retrieve the parameter values that have not been saved yet. null is for all parameters values set after the last savepoint.
        Returns:
        The parameter values for the designated savepoint that have not been saved yet. The values will be coupled to this DataContainer, so do not close them; clone them if required longer than this DataContainer.

      • getUnsavedSessionState

        byte[] getUnsavedSessionState​(String savepoint)
        Gets the session states for the designated savepoint that have not been saved yet.
        Parameters:
        savepoint - The savepoint for which to retrieve the session states that have not been saved yet. null is for the unsaved session set after the last savepoint.
        Returns:
        The session state for the designated savepoint that has not been saved yet or null in case there is no such session state or it has been stored already.

      • getUnsavedSavepoints

        List<String> getUnsavedSavepoints()
        Gets the names of all savepoints that have not been stored yet. If there are changes without an explicit savepoint, the implicit savepoint null will be at the end of the list.
        Returns:
        All savepoints that have not been saved yet in the order they have been created. This is used for storing them intermediately.

      • savedSavepoints

        void savedSavepoints​(String[] savepoints)
        Signals this data container that the designated savepoints have been saved.
        Parameters:
        savepoints - The savepoints that have been saved now. This must not be null nor contain null nor empty strings.

      • clone

        DataContainer clone()
        Clones this DataContainer in case it is Cloneable, otherwise a CloneNotSupportedException will be thrown (which is what this default implementation does). Subclasses should provide a corresponding implementation and also extend Cloneable. Those which do not, should forward to this default implementation.
        Specified by:
        clone in interface TypedCloneable<DataContainer>
        Returns:
        A clone of this DataContainer instance.
        Throws:
        CloneNotSupportedException - If the instance (is of a subclass that) is not cloneable, a CloneNotSupportedException will be thrown. This must not be thrown if (the subclass of) the instance is cloneable.