Interface Parameter

  • All Superinterfaces:
    LocalisedString, PluginDataContainer, UserAttributeContainer
    All Known Subinterfaces:
    ATParameter, ProcessModelParameter

    public interface Parameter
    extends UserAttributeContainer, PluginDataContainer, LocalisedString
    The parameter interface describes the common parameter information of the various data models. This includes parameters of operations and activity templates (from the activity model) and activities and process templates (from the process model).

    The object a parameter belongs to, e.g. an Activity, will in the following be referred to as the entity of the parameter.

    Input and Output Parameters

    In all entities, parameters are stored considering their data access type, cf. ActivityConstants.AccessType.
    In detail, for receiving the input parameters of an Operation, you need to specify the corresponding data access type when calling Operation.getParameters(de.aristaflow.adept2.model.globals.ActivityConstants.AccessType) .
    If a parameter is an input and an output value (cf. call by reference), it is represented as two parameters - one input parameter and one output parameter - with the same name.

    Optional Values

    Parameters may be obligatory (mandatory) or optional. If an input parameter (IN or INOUT) is flagged as optional, the data is not required by its entity. This corresponds e.g. to method signatures which allow for null values. An optional input parameter may have a default value. This value will be provided to the activity at runtime if the value of the corresponding data element is null.
    If an output parameter (OUT) is flagged as optional, the method or activity may return a value for it, but is not required to do so. If there is no return value, the value of the corresponding data element will not be changed. This is different from setting it explicitly to null.

    Identifier

    The type of the parameter can be described in detail using a reference to an identifier. Identifiers describe type, structure and semantics of a data type. Please refer to Identifier for further information.

    Failure Parameters

    An optional, non-virtual output parameter may be a failure parameter. This represents an exception that may occur when executing the activity but the exception can be handled explicitly in the corresponding process in lieu of a separate failure handling process. Compare this for instance with a boolean return value that indicates whether a method has been successful instead of throwing an exception.
    Whether a failure parameter needs to be an exception (failing the instance) or an output parameter depends on whether the activity instance provided to the corresponding execution environment has an output parameter for the corresponding failure parameter.

    Virtual Parameters

    A parameter may be a real parameter of a entity, but it may also be a virtual parameter. Virtual parameters represent data flows which are not under control of the process management system - i.e. there is no actual data processed by the PMS. These hidden data flows occur e.g. via database tables, paper documents, etc. By nature, virtual parameters can not be failure parameters and they can not have a default value.

    Default Values

    An optional non-virtual input parameter may have a default value. In case the corresponding data element is null when starting the activity, the default value will be provided via the data context instead of the null value. This is completely transparent for the execution environment. Therefore the corresponding underlying parameter may be/is usually mandatory, but it may be modelled as optional parameter and therefore being less demanding concerning its input parameters.

    Activity type specific data

    Like operations, also parameters may need to be annotated with additional information, which is required for the execution. E.g. the native data type of a parameter of a Java operation might be required to identify an overloaded Java method. These values may also stem from another parameter or from the process configuration.
    Cf. getConfiguration() and Operation.getConfiguration().
    • Method Detail

      • getName

        String getName()
        Returns the name of the parameter. Depending on the context, this may be the parameter of an activity template, activity or process template.

        The name of a parameter is unique within its data access scope (e.g. READ).

        Uses:

        • display purposes during modelling and plug and play
        • as default for data element names during plug and play
        • parameter matching in the execution environments, e.g. find the right parameter in a signature by using this name
        Returns:
        The parameter name.
      • getDescription

        String getDescription()
        Returns the description of the parameter for the end user.

        Uses:

        • display purposes for the end user.
        Returns:
        The description of the parameter for the end user.
      • getDataType

        ProcessConstants.AdeptDataType getDataType()
        Returns the ADEPT2 data type of the parameter.

        Uses:

        • find matching data elements during plug and play
        • matching of method signatures during execution
        • finding the right data type, e.g. in a generated form (execution)
        Returns:
        The ADEPT2 data type of the parameter.
      • getUDTName

        String getUDTName()
        Returns the name of the user-defined type, if the parameter is of type user-defined (cf getDataType()). This value might be used to further describe the data type, but will be interpreted by the corresponding runtime only.

        If the parameter is not user-defined, the method will return null.

        Uses:

        • find matching data elements during plug and play
        • find possible user defined functions
        Also see for UDTValue and ProcessConstants.AdeptDataType.USERDEFINED.
        Returns:
        The name of the user defined type, or null.
      • getIdentifierID

        UUID getIdentifierID()
        Returns the ID of the identifier which describes the type of the parameter in detail, or the constant ProcessConstants.UNIVERSAL_IDENTIFIER_ID.

        Uses:

        • modelling / plug and play
        • future use: check if data values correspond to the syntax described by the identifier.

        The data type long allows to change the name of the identifier. When importing/exporting the ID has to be mapped to the corresponding name since the ID may be already in use by another identifier on the target system. See Identifier for further detail.

        See the class description for further information.

        Returns:
        The ID of the identifier of this parameter, or the constant UNIVERSAL_IDENTIFIER_ID.
      • isOptional

        boolean isOptional()
        Returns true, if the parameter is optional.

        In case the parameter is an input parameter, the activity does not require the data of this parameter, but may use the data if it is available.
        In case of an output parameter, the activity might return the value, but is not required to do so. If there is no data returned, the attached data element will not be written.

        Uses:

        • modelling processes for checking data flows
        • execution for determining valid input and output data

        See the class description for further information.

        Returns:
        True, if the parameter is optional.
      • isVirtual

        boolean isVirtual()
        Returns true, if the parameter is virtual. A virtual parameter may not be a failure parameter and may not have a default value.

        Uses:

        • modelling / plug and play

        See the class description for further information.

        Returns:
        True, if the parameter is virtual.
      • isFailure

        boolean isFailure()
        Gets whether this (optional, non-virtual output) parameter represents a failure parameter. An execution environment allowing to switch between throwing an exception (failing the activity) or setting the information as output parameter needs to look for an appropriate output parameter (name) in the provided ActivityInstance.
        Returns:
        Whether this parameter represents a failure parameter and if it exists in the ActivityInstance provided to the execution environment, the activity should not fail but provide the necessary failure information as normal output value.
      • getDefaultValue

        String getDefaultValue()
        Gets the string representation of the default value for this (optional, non-virtual input) parameter. This will be provided to the execution environment in case the corresponding data element is set to null.
        The string has to conform to the strings used in the configuration for arbitrary types, that is it needs to be a valid representation for the data type of this parameter.
        Returns:
        The string representation of the default value for this (optional input) parameter that will be provided to the execution environment in case the corresponding data element is set to null.
      • getConfiguration

        ActivityConfiguration getConfiguration()
        Returns the configuration specific to this parameter and the corresponding execution environment.
        This may e.g. include the name of the native data type (e.g. int and the ADEPT2 data type INTEGER).
        Another example is the position of the parameter in a method signature.

        In case of a node parameter this methods returns an empty configuration since a node does not have a special parameter configuration.

        The configuration needs to corresponding to the configuration description of the corresponding ActivityModelParameter. While an ActivityModelParameter does not need to provide all configuration values for the corresponding description, a ProcessModelParameter does.

        Uses:

        • used by the execution environment
        Returns:
        Activity type specific configuration for this parameter.