Package de.aristaflow.adept2.model.runtimeenvironment

Class ActivityData

java.lang.Object
de.aristaflow.adept2.model.runtimeenvironment.ActivityData
All Implemented Interfaces:
Closeable, AutoCloseable
public class ActivityData extends Object implements Closeable
ActivityData provides convenience methods for retrieval of input and output parameter types and values as well as writing the output parameter values. User-defined data types can be lists or other POJOs. Besides the parameters, there are also methods for accessing the configuration values. Mandatory parameters can be checked for existence. If problems occur when accessing a parameter or configuration value, an appropriate ApplicationEnvironmentException will be thrown. This applies for instance in case a mandatory value is not set or a required value has the wrong type.

Besides the specific methods, most convenience methods can be classified into the following groups:

  • readInput*: Gets the value of the corresponding input parameter or null in case the value has not been set. No conversion takes place, if the parameter is of the wrong type or does not exist, an exception will be thrown.
  • requireInput*: The same as the corresponding readInput*-method but this time an exception will be thrown, if the value is not present.
  • *ToNativeTypedValue: These methods are called when you request a value with conversion (@see getInputValue(ProcessModelParameter, boolean, boolean), getStoredValue(String) and getStoredValue(ProcessModelParameter, boolean)). Override this methods to change the type conversion.
  • readOutput*: Gets the value of the corresponding output parameter if it has already been written, either by the current execution or by a previous suspended execution. null will be returned if no value has been written. No conversion takes place, if the parameter is of the wrong type or does not exist, an exception will be thrown.
  • writeOutput*: Writes the designated value to the corresponding output parameter. No conversion takes place, if the parameter is of the wrong type or does not exist, an exception will be thrown.
  • objectTo*: These methods are called when you write a value with conversion (@see writeOutputValue(ProcessModelParameter, boolean, Object)). Override this methods to change the type conversion.
  • getConf*: Gets the value of the corresponding activity configuration value. If the configuration value does not exist, or is of another type, the designated default value will be returned.
  • requireConf*:: The same as the corresponding getConf*-method but this time an exception will be thrown, if the value is not present or the configuration entry has the wrong type.
  • getParamConf*: The same as the getConf* but this time for values of the configuration of the corresponding parameter.
  • requireParamConf*: The same as the requireConf* but this time for values of the configuration of the corresponding parameter.

  • Field Details

    • logger

      protected final Logger logger
      The logger for execution environment.

    • activityInstance

      protected final ActivityInstance activityInstance
      The activity (instance) which is encapsulated by the execution environment.

    • dataContext

      protected final DataContext dataContext
      The data context for the execution environment.

    • closeables

      protected final Collection<AutoCloseable> closeables
      The AutoCloseable values that are created internally, for instance via conversion which are not controlled by the dataContext.

    • cleanup

      protected final Cleanup<RuntimeException> cleanup
      The clean-up for closing the Closeables.

  • Constructor Details

    • ActivityData

      public ActivityData(ActivityInstance activityInstance, DataContext dataContext, Logger logger)
      Initialise activityInstance, dataContext and logger.
      Parameters:
      activityInstance - The activity (instance) which is encapsulated by the execution environment.
      dataContext - The data context for the execution environment.
      logger - The logger for the execution environment.

    • ActivityData

      public ActivityData(ActivityData actData)
      Constructor for replacing the designated instance of ActivityData with this one.
      Parameters:
      actData - The instance of ActivityData which to replace. The caller is responsible for closing.

  • Method Details

    • getCorrespondingJavaClass

      public Class<?> getCorrespondingJavaClass(Parameter parameter, boolean output)
      Gets the class object corresponding to the type of the designated parameter. This method should be overridden to return a correctly typed value.
      This implementation returns boolean, long, double, String, Object or URI).
      Parameters:
      parameter - The parameter for which the corresponding java class is to be retrieved.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The class object corresponding to the type of the designated parameter or null in case there is no such data type.

    • getInputParams

      public Collection<ProcessModelParameter> getInputParams()
      Returns all input parameters in a list.
      Returns:
      all input parameters in a list

    • getInputParam

      public ProcessModelParameter getInputParam(String parameterName)
      Returns the input parameter with the given name or null if no such parameter exists.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the input parameter or null

    • requireInputParam

      public ProcessModelParameter requireInputParam(String parameterName)
      Returns the input parameter with the given name, or throws an exception if the parameter does not exist.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the input parameter
      Throws:
      ApplicationEnvironmentException - if the parameter does not exist

    • hasParam

      public boolean hasParam(String parameterName, ActivityConstants.AccessType accessType)
      Returns whether the parameter with the specified name and access type exists.
      Parameters:
      parameterName - The name of the parameter.
      accessType - The access type of the parameter.
      Returns:
      Whether the parameter exists.

    • hasInputParam

      public boolean hasInputParam(String parameterName)
      Returns whether the input parameter with the specified name exists.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      whether the input parameter exists

    • hasInputListParam

      public boolean hasInputListParam(String parameterName, ProcessConstants.AdeptDataType elementDataType)
      Returns whether the input parameter with the specified name exists and is a list with the specified element type.
      Parameters:
      parameterName - name of the input parameter
      elementDataType - the expected element type of the list; null if this does not matter
      Returns:
      whether the input list parameter exists

    • getInputTypes

      public Class<?>[] getInputTypes()
      Gets the input parameter types in an array of the corresponding classes ordered by their position. The parameter in the first position is in the array at index 0.
      Returns:
      An array of class instances representing the input parameter types of the activity of this execution environment ordered by their position. At index 0 is the parameter with position 1.

    • hasInputValue

      public boolean hasInputValue(String paramName)
      Checks whether the value of the specified input parameter is set, i.e. is not null.
      Parameters:
      paramName - The identifier of the parameter
      Returns:
      Whether the input parameter has a value, false if the parameter is null.

    • getInputValue

      public Object getInputValue(String parameterName) throws ApplicationEnvironmentException
      Retrieves the value of the specified input parameter as an object of the closest related java type. The conversion methods are used for this.
      Parameters:
      parameterName - The identifier of the parameter
      Returns:
      The parameter value, or null if the parameter is not set. An AutoCloseable value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist, the data type is invalid or no value is provided an ApplicationEnvironmentException will be thrown.
      See Also:

    • getInputValue

      public Object getInputValue(ProcessModelParameter parameter) throws ApplicationEnvironmentException
      Retrieves the value of the designated input parameter as an object of the closest related java type. The conversion methods are used for this.
      Parameters:
      parameter - The input parameter for which to get the value.
      Returns:
      The parameter value, or null if the parameter is not set. An AutoCloseable value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist, the data type is invalid or no value is provided an ApplicationEnvironmentException will be thrown.
      See Also:

    • getInputValue

      public Object getInputValue(String parameterName, boolean required) throws ApplicationEnvironmentException
      Retrieves the value of the specified input parameter as an object of the closest related java type. The conversion methods are used for this.
      Parameters:
      parameterName - The identifier of the parameter
      required - Whether the input parameter is required (mandatory) and therefore an ApplicationEnvironmentException is to be thrown in case it is null.
      Returns:
      The parameter value, or null if the parameter is not set. An AutoCloseable value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist, the data type is invalid or no value is provided an ApplicationEnvironmentException will be thrown.
      See Also:

    • getInputValue

      public Object getInputValue(ProcessModelParameter parameter, boolean required) throws ApplicationEnvironmentException
      Retrieves the value of the designated input parameter as an object of the closest related java type. The conversion methods are used for this.
      Parameters:
      parameter - The input parameter for which to get the value.
      required - Whether the input parameter is required (mandatory) and therefore an ApplicationEnvironmentException is to be thrown in case it is null.
      Returns:
      The parameter value, or null if the parameter is not set. An AutoCloseable value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist, the data type is invalid or no value is provided an ApplicationEnvironmentException will be thrown.
      See Also:

    • getInputValue

      protected Object getInputValue(String parameterName, ProcessConstants.AdeptDataType expDt, boolean convert, boolean required) throws ApplicationEnvironmentException
      Retrieves the value of the specified input parameter as an object of the closest related java type. The conversion methods are used if requested. The designated expected data type improves the type safety. If it does not match the type of the parameter, an ApplicationEnvironmentException will be thrown.
      Parameters:
      parameterName - The name of the parameter for which to retrieve the value.
      expDt - The data type which is expected. If this is null, the data type of the parameter will not be checked.
      convert - Whether to convert the retrieved values with the appropriate methods.
      required - Whether the input parameter is required (mandatory) and therefore an ApplicationEnvironmentException is to be thrown in case it is null.
      Returns:
      The parameter value, or null if the parameter is not set. An AutoCloseable value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist, the data type is invalid or no value is provided for a required parameter an ApplicationEnvironmentException will be thrown.
      See Also:

    • getInputValue

      public Object getInputValue(ProcessModelParameter param, boolean convert, boolean required) throws ApplicationEnvironmentException
      Retrieves the value of the specified input parameter as an object of the closest related java type or the appropriate converted type.
      Parameters:
      param - The parameter for which to retrieve the value.
      convert - Whether to convert the retrieved values with the appropriate methods.
      required - Whether the input parameter is required (mandatory) and therefore an ApplicationEnvironmentException is to be thrown in case it is null.
      Returns:
      The parameter value, or null if the parameter is not set. An AutoCloseable value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist, the data type is invalid or no value is provided for a required parameter an ApplicationEnvironmentException will be thrown.
      See Also:

    • getInputValues

      public Object[] getInputValues()
      Gets the values of the input parameter in an array of object ordered by their position. The parameter in the first position is in the array at index 0. Exceptions lead to ApplicationEnvironmentExceptions.
      Returns:
      An array of object instances representing the input parameters values of the activity of this execution environment ordered by their position. At index 0 is the parameter with position 1.
      AutoCloseable values will be coupled to this ActivityData, so do not close them if applicable; clone one if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If a parameter does not exist, the data type is invalid or no value is provided for a required parameter an ApplicationEnvironmentException will be thrown.
      See Also:

    • getDualInputValue

      public <T> T getDualInputValue(String name, ProcessConstants.AdeptDataType type, Class<T> valueType)
      A "dual input parameter" is a parameter whose value can either be provided by an input parameter or by an activity configuration field with the same name or a combination of both. For this method the data type of the parameter is expected to be the given type and the value of the activity parameter configuration field must be a valid string representation of that data type. In case of ProcessConstants.AdeptDataType.DATE and ProcessConstants.AdeptDataType.USERDEFINED the special access method of the configuration will be used. It's basically an input parameter with a default value provided in the ATC.

      The following are the possible constellations:

      • if the parameter is present and not optional, the ATC field is ignored
      • if the parameter is present but optional, the value of the ATC field is only returned if the data element of the input parameter has not been written yet
      • if the parameter is not present, the value of the ATC field is always returned
      Type Parameters:
      T - The type which the requested value is expected to be of.
      Parameters:
      name - The name of the dual input parameter (i.e. input parameter + ATC field).
      type - The data type of the parameter or configuration entry.
      valueType - The (object) type of which the requested value is expected to be. An AutoCloseable value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      Returns:
      The value of the dual parameter.

    • readInputBoolean

      public Boolean readInputBoolean(String parameterName)
      Returns the value of the specified BOOLEAN input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputBoolean

      public Boolean readInputBoolean(ProcessModelParameter parameter)
      Returns the value of the specified BOOLEAN input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameter - the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputInteger

      public Long readInputInteger(String parameterName)
      Returns the value of the specified INTEGER input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputInteger

      public Long readInputInteger(ProcessModelParameter parameter)
      Returns the value of the specified INTEGER input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameter - the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputFloat

      public Double readInputFloat(String parameterName)
      Returns the value of the specified FLOAT input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputFloat

      public Double readInputFloat(ProcessModelParameter parameter)
      Returns the value of the specified FLOAT input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameter - the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputString

      public String readInputString(String parameterName)
      Returns the value of the specified STRING input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputString

      public String readInputString(ProcessModelParameter parameter)
      Returns the value of the specified STRING input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameter - the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputDate

      public Date readInputDate(String parameterName)
      Returns the value of the specified DATE input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputDate

      public Date readInputDate(ProcessModelParameter parameter)
      Returns the value of the specified DATE input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameter - the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputURI

      public URI readInputURI(String parameterName)
      Returns the value of the specified URI input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputURI

      public URI readInputURI(ProcessModelParameter parameter)
      Returns the value of the specified URI input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameter - the input parameter
      Returns:
      the retrieved value; may be null
      See Also:

    • readInputUDT

      public UDTValue readInputUDT(String parameterName)
      Returns the value of the specified USERDEFINED input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      The retrieved value; may be null. The UDTValue will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      See Also:

    • readInputUDT

      public UDTValue readInputUDT(ProcessModelParameter parameter)
      Returns the value of the specified USERDEFINED input parameter or null if no value is set or the parameter does not exist. Use this method for optional input parameters.
      Parameters:
      parameter - the input parameter
      Returns:
      the retrieved value; may be null. The UDTValue will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      See Also:

    • readInputList

      public <T extends Serializable> List<T> readInputList(String parameterName)
      Returns the list of the specified USERDEFINED input parameter or null if no value is set. Use this method for optional input parameters.
      Type Parameters:
      T - the element type of the list
      Parameters:
      parameterName - name of the input parameter
      Returns:
      The retrieved list; may be null. AutoCloseable list elements will be coupled to this ActivityData, so do not close them; clone one if required longer than this ActivityData.
      See Also:
      • requireInputList(String)

    • readInputList

      public <T extends Serializable> List<T> readInputList(ProcessModelParameter parameter)
      Returns the list of the specified USERDEFINED input parameter or null if no value is set. Use this method for optional input parameters.
      Type Parameters:
      T - the element type of the list
      Parameters:
      parameter - the input parameter
      Returns:
      The retrieved list; may be null. AutoCloseable list elements will be coupled to this ActivityData, so do not close them; clone one if required longer than this ActivityData.
      See Also:
      • requireInputList(String)

    • readInputList

      protected <T extends Serializable> List<T> readInputList(String pName, UDTValue value, String udtName)
      Gets the list of the designated ProcessConstants.AdeptDataType.USERDEFINED input parameter or null if the designated value is null. The designated UDT name is used to analyse the UDT and if it is neither a serialised list nor a list UDT, an ApplicationEnvironmentException will be thrown.
      Type Parameters:
      T - The type of the list elements.
      Parameters:
      pName - The name of the input parameter providing the list from a UDT value
      value - The UDT value containing the list. The caller is responsible for closing.
      udtName - The name of the UDT value (usually providing information on the list and its content).
      Returns:
      The list retrieved from the designated value or null if the designated value is null.
      AutoCloseable list elements will be coupled to this ActivityData, so do not close them; clone one if required longer than this ActivityData.
      See Also:

    • requireInputBoolean

      public boolean requireInputBoolean(String parameterName) throws ApplicationEnvironmentException
      Returns the value of the specified BOOLEAN input parameter or throws an exception if the value is not available. Use this method for mandatory input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value
      Throws:
      ApplicationEnvironmentException - if the input value could not be retrieved (parameter does not exist; wrong data type) or if the value is not available
      See Also:

    • requireInputInteger

      public long requireInputInteger(String parameterName) throws ApplicationEnvironmentException
      Returns the value of the specified INTEGER input parameter or throws an exception if the value is not available. Use this method for mandatory input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value
      Throws:
      ApplicationEnvironmentException - if the input value could not be retrieved (parameter does not exist; wrong data type) or if the value is not available
      See Also:

    • requireInputFloat

      public double requireInputFloat(String parameterName) throws ApplicationEnvironmentException
      Returns the value of the specified FLOAT input parameter or throws an exception if the value is not available. Use this method for mandatory input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value
      Throws:
      ApplicationEnvironmentException - if the input value could not be retrieved (parameter does not exist; wrong data type) or if the value is not available
      See Also:

    • requireInputString

      public String requireInputString(String parameterName) throws ApplicationEnvironmentException
      Returns the value of the specified STRING input parameter or throws an exception if the value is not available. Use this method for mandatory input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; never null
      Throws:
      ApplicationEnvironmentException - if the input value could not be retrieved (parameter does not exist; wrong data type) or if the value is not available
      See Also:

    • requireInputDate

      public Date requireInputDate(String parameterName) throws ApplicationEnvironmentException
      Returns the value of the specified DATE input parameter or throws an exception if the value is not available. Use this method for mandatory input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; never null
      Throws:
      ApplicationEnvironmentException - if the input value could not be retrieved (parameter does not exist; wrong data type) or if the value is not available
      See Also:

    • requireInputURI

      public URI requireInputURI(String parameterName) throws ApplicationEnvironmentException
      Returns the value of the specified URI input parameter or throws an exception if the value is not available. Use this method for mandatory input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; never null
      Throws:
      ApplicationEnvironmentException - if the input value could not be retrieved (parameter does not exist; wrong data type) or if the value is not available
      See Also:

    • requireInputUDT

      public UDTValue requireInputUDT(String parameterName) throws ApplicationEnvironmentException
      Returns the value of the specified USERDEFINED input parameter or throws an exception if the value is not available. Use this method for mandatory input parameters.
      Parameters:
      parameterName - name of the input parameter
      Returns:
      the retrieved value; never null. The value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - if the input value could not be retrieved (parameter does not exist; wrong data type) or if the value is not available
      See Also:

    • toNativeNull

      public Object toNativeNull(ProcessModelParameter parameter, boolean output)
      Gets an instance for null. This allows for converting to a specific null value.
      This implementation returns null.

      Overriding implementations creating a new object being an AutoCloseable itself or an object having AutoCloseable elements have to add them to closeables.

      Parameters:
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The null value.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.

    • booleanToNativeTypedValue

      public Object booleanToNativeTypedValue(Boolean value, ProcessModelParameter parameter, boolean output)
      Converts an instance of Boolean to an instance of the corresponding native type. This method should be overridden to return a correctly typed value.
      This implementation returns the instance unchanged.

      Overriding implementations creating a new object being an AutoCloseable itself or an object having AutoCloseable elements have to add them to closeables.

      Parameters:
      value - An instance of Boolean to be converted to native type.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value unchanged.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.

    • integerToNativeTypedValue

      public Object integerToNativeTypedValue(Long value, ProcessModelParameter parameter, boolean output)
      Converts an instance of Long to an instance of the corresponding native type. This method should be overridden to return a correctly typed value.
      This implementation returns the instance unchanged.

      Overriding implementations creating a new object being an AutoCloseable itself or an object having AutoCloseable elements have to add them to closeables.

      Parameters:
      value - An instance of Long to be converted to native type.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value unchanged.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.

    • floatToNativeTypedValue

      public Object floatToNativeTypedValue(Double value, ProcessModelParameter parameter, boolean output)
      Converts an instance of Double to an instance of the corresponding native type. This method should be overridden to return a correctly typed value.
      This implementation returns the instance unchanged.

      Overriding implementations creating a new object being an AutoCloseable itself or an object having AutoCloseable elements have to add them to closeables.

      Parameters:
      value - An instance of Double to be converted to native type.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value unchanged.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.

    • stringToNativeTypedValue

      public Object stringToNativeTypedValue(String value, ProcessModelParameter parameter, boolean output)
      Converts an instance of String to an instance of the corresponding native type. This method should be overridden to return a correctly typed value.
      This implementation returns the instance unchanged.

      Overriding implementations creating a new object being an AutoCloseable itself or an object having AutoCloseable elements have to add them to closeables.

      Parameters:
      value - An instance of String to be converted to native type.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value unchanged.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.

    • dateToNativeTypedValue

      public Object dateToNativeTypedValue(Date value, ProcessModelParameter parameter, boolean output)
      Converts an instance of Date to an instance of the corresponding native type. This method should be overridden to return a correctly typed value.
      This implementation returns the instance unchanged.

      Overriding implementations creating a new object being an AutoCloseable itself or an object having AutoCloseable elements have to add them to closeables.

      Parameters:
      value - An instance of Date to be converted to native type.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value unchanged.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.

    • userdefinedToNativeTypedValue

      public Object userdefinedToNativeTypedValue(UDTValue value, ProcessModelParameter parameter, boolean output)
      Converts an instance of UDTValue to an instance of the corresponding native type. This method should be overridden to return a correctly typed value.
      This implementation creates an instance of Object by interpreting the UDT as an object stream and de-serialising the appropriate object. In case of a ListUdt it will be unmarshalled appropriately and the corresponding list will be returned.
      The corresponding class of the object needs to be in the class path!

      Overriding implementations creating a new object being an AutoCloseable itself or an object having AutoCloseable elements have to add them to closeables.

      Parameters:
      value - The UDTValue containing a serialised object to be converted to native type. The caller is responsible for closing.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      An instance of Object read from the designated UDTValue or null in case the object can not be read.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.

    • uriToNativeTypedValue

      public Object uriToNativeTypedValue(URI value, ProcessModelParameter parameter, boolean output)
      Converts an instance of URI to an instance of the corresponding native type. This method should be overridden to return a correctly typed value.
      This implementation returns the instance unchanged.

      Overriding implementations creating a new object being an AutoCloseable itself or an object having AutoCloseable elements have to add them to closeables.

      Parameters:
      value - An instance of URI to be converted to native type.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value unchanged.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.

    • hasStoredValue

      public boolean hasStoredValue(String paramName)
      Checks whether the value of the specified output parameter has been written, i. e. is not null.
      Parameters:
      paramName - The name of the parameter of which to check whether a value has been written.
      Returns:
      Whether the output parameter has a value, false if the parameter value is null.

    • getStoredValue

      public Object getStoredValue(String parameterName) throws ApplicationEnvironmentException
      Retrieves the stored value of the specified output parameter as an object of the closest related java type. The conversion methods are used for this.
      Parameters:
      parameterName - The identifier of the parameter
      Returns:
      The parameter value, or null if the parameter has not been written yet.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist or the data type is invalid an ApplicationEnvironmentException will be thrown.
      See Also:

    • getStoredValue

      public Object getStoredValue(ProcessModelParameter parameter) throws ApplicationEnvironmentException
      Retrieves the stored value of the specified output parameter as an object of the closest related java type. The conversion methods are used for this.
      Parameters:
      parameter - The output parameter
      Returns:
      The parameter value, or null if the parameter has not been written yet.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist or the data type is invalid an ApplicationEnvironmentException will be thrown.
      See Also:

    • getStoredValue

      protected Object getStoredValue(String parameterName, ProcessConstants.AdeptDataType expDt, boolean convert) throws ApplicationEnvironmentException
      Retrieves the stored value of the specified output parameter as an object of the closest related java type. The conversion methods are used if requested. The designated expected data type improves the type safety. If it does not match the type of the parameter, an ApplicationEnvironmentException will be thrown.
      Parameters:
      parameterName - The name of the parameter for which to retrieve the value.
      expDt - The data type which is expected. If this is null, the data type of the parameter will not be checked.
      convert - Whether to convert the retrieved values with the appropriate methods.
      Returns:
      The parameter value, or null if the parameter is not set.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist or the data type is invalid an ApplicationEnvironmentException will be thrown.
      See Also:

    • getStoredValue

      public Object getStoredValue(ProcessModelParameter param, boolean convert) throws ApplicationEnvironmentException
      Retrieves the stored value of the specified output parameter as an object of the closest related java type or the appropriate converted type.
      Parameters:
      param - The parameter for which to retrieve the value.
      convert - Whether to convert the retrieved values with the appropriate methods.
      Returns:
      The parameter value, or null if the parameter is not set.
      An AutoCloseable value will be coupled to this ActivityData, so do not close it if applicable; clone it if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist or the data type is invalid an ApplicationEnvironmentException will be thrown.
      See Also:

    • getStoredValues

      public Object[] getStoredValues() throws ApplicationEnvironmentException
      Gets the stored values of the output parameter in an array of object ordered by their position. The parameter in the first position is in the array at index 0. Exceptions when reading a value of user-defined data type, incorrect parameter names and incorrect parameter types are logged and the corresponding parameter value is set to null.
      Returns:
      An array of object instances representing the output parameters values of the activity of this execution environment ordered by their position. At index 0 is the parameter with position 1.
      AutoCloseable values will be coupled to this ActivityData, so do not close them if applicable; clone one if required longer than this ActivityData.
      Throws:
      ApplicationEnvironmentException - If the parameter does not exist or the data type is invalid an ApplicationEnvironmentException will be thrown.
      See Also:

    • readOutputBoolean

      public Boolean readOutputBoolean(String parameterName)
      Returns the value stored for the specified BOOLEAN output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameterName - The name of the output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputBoolean

      public Boolean readOutputBoolean(ProcessModelParameter parameter)
      Returns the value stored for the specified BOOLEAN output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameter - The output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputInteger

      public Long readOutputInteger(String parameterName)
      Returns the value stored for the specified INTEGER output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameterName - The name of the output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputInteger

      public Long readOutputInteger(ProcessModelParameter parameter)
      Returns the value stored for the specified INTEGER output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameter - The output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputFloat

      public Double readOutputFloat(String parameterName)
      Returns the value stored for the specified FLOAT output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameterName - The name of the output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputFloat

      public Double readOutputFloat(ProcessModelParameter parameter)
      Returns the value stored for the specified FLOAT output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameter - The output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputString

      public String readOutputString(String parameterName)
      Returns the value stored for the specified STRING output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameterName - The name of the output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputString

      public String readOutputString(ProcessModelParameter parameter)
      Returns the value stored for the specified STRING output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameter - The output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputDate

      public Date readOutputDate(String parameterName)
      Returns the value stored for the specified DATE output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameterName - The name of the output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputDate

      public Date readOutputDate(ProcessModelParameter parameter)
      Returns the value stored for the specified DATE output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameter - The output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputURI

      public URI readOutputURI(String parameterName)
      Returns the value stored for the specified URI output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameterName - The name of the output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputURI

      public URI readOutputURI(ProcessModelParameter parameter)
      Returns the value stored for the specified URI output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameter - The output parameter.
      Returns:
      The previously stored value; may be null.
      See Also:

    • readOutputUDT

      public UDTValue readOutputUDT(String parameterName)
      Returns the value stored for the specified USERDEFINED output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameterName - The name of the output parameter.
      Returns:
      The previously stored value; may be null. The value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      See Also:

    • readOutputUDT

      public UDTValue readOutputUDT(ProcessModelParameter parameter)
      Returns the value stored for the specified USERDEFINED output parameter or null if no value is set or the parameter does not exist.
      Parameters:
      parameter - The output parameter.
      Returns:
      The previously stored value; may be null. The value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.
      See Also:

    • getOutputParams

      public Collection<ProcessModelParameter> getOutputParams()
      Returns all output parameters in a list.
      Returns:
      all output parameters in a list

    • getOutputParam

      public ProcessModelParameter getOutputParam(String parameterName)
      Returns the output parameter with the given name or null if no such parameter exists.
      Parameters:
      parameterName - name of the output parameter
      Returns:
      the input parameter or null

    • requireOutputParam

      public ProcessModelParameter requireOutputParam(String parameterName)
      Returns the output parameter with the given name, or throws an exception if the parameter does not exist.
      Parameters:
      parameterName - name of the output parameter
      Returns:
      the input parameter
      Throws:
      ApplicationEnvironmentException - if the parameter does not exist

    • hasOutputParam

      public boolean hasOutputParam(String parameterName)
      Returns whether the output parameter with the specified name exists.
      Parameters:
      parameterName - the output parameter name
      Returns:
      whether the output parameter exists

    • writeOutputValue

      public void writeOutputValue(String parameterName, Object value)
      Stores the value for the specified output parameter. This will overwrite any previously written value.

      The conversion methods are used for this. Per default they expect the object types to be the same as the matching type-specific setOutput methods. If the value is a List it will be serialised accordingly to a UDT value.

      Parameters:
      parameterName - The name of the output parameter.
      value - The value to be stored. The caller is responsible for closing if appropriate.
      See Also:

    • writeOutputValue

      public void writeOutputValue(ProcessModelParameter parameter, Object value)
      Stores the value for the specified output parameter. This will overwrite any previously written value.

      The conversion methods are used for this. Per default they expect the object types to be the same as the matching type-specific setOutput methods. If the value is a List it will be serialised accordingly to a UDT value.

      Parameters:
      parameter - The output parameter.
      value - The value to be stored. The caller is responsible for closing if appropriate.
      See Also:

    • writeOutputValue

      protected void writeOutputValue(String parameterName, ProcessConstants.AdeptDataType expDt, boolean convert, Object value)
      Stores the value for the specified output parameter. This will overwrite any previously written value. The designated expected data type improves the type safety. If it does not match the type of the parameter, an ApplicationEnvironmentException will be thrown.

      The conversion methods are used for this. Per default they expect the object types to be the same as the matching type-specific setOutput methods. If the value is a List it will be serialised accordingly to a UDT value.

      Parameters:
      parameterName - The name of the output parameter.
      expDt - The data type which is expected. If this is null, the data type of the parameter will not be checked.
      convert - Whether to convert the designated value with the appropriate methods before storing it.
      value - The value to be stored. The caller is responsible for closing if appropriate.
      See Also:

    • writeOutputValue

      protected void writeOutputValue(ProcessModelParameter param, boolean convert, Object value)
      Stores the value for the specified output parameter. This will overwrite any previously written value.
      Parameters:
      param - The output parameter.
      convert - Whether to convert the designated value with the appropriate methods before storing it.
      value - The value to be stored. The caller is responsible for closing if appropriate.
      See Also:

    • writeOutputValues

      public void writeOutputValues(Object returnValue, Object[] values)
      Writes the values of the output parameters and the return value into the data context. The designated return value is stored as value for the parameter with position 0. Exceptions when accessing the values (invalid positions or no values provided) are logged and the corresponding value is set to NULL.
      Parameters:
      returnValue - The return value of the application which is stored for the output parameter with position 0.
      values - The output parameter values as array of object. The positions need to correspond to the parameter positions defined for the executed activity while the parameter with position 1 is stored at index 0 in the array.
      The caller is responsible for closing the values if appropriate.

    • closeUnknown

      public void closeUnknown(Object... prospCloseables)
      Closes all of the designated instances which are AutoCloseable and which are not known by this ActivtiyData (have not been created by it and thus are not within closeables). This ensures closing of AutoCloseables created by the user (usually execution environments). Often these environments cannot distinguish between AutoCloseables provided by ActivityData for which they are not responsible and the ones they have created and are responsible for.
      Parameters:
      prospCloseables - Arbitrary objects of which all AutoCloseable instances which have not been created by this ActivtityData will be closed.

    • unwriteOutputValue

      public void unwriteOutputValue(String parameterName)
      Removes any previously written value for the specified output parameter.
      Parameters:
      parameterName - name of the output parameter

    • unwriteOutputValue

      public void unwriteOutputValue(ProcessModelParameter parameter)
      Removes any previously written value for the specified output parameter.
      Parameters:
      parameter - The output parameter.

    • writeOutputBoolean

      public void writeOutputBoolean(String parameterName, boolean value)
      Stores the value for the specified BOOLEAN output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - the value to be stored
      See Also:

    • writeOutputBoolean

      public void writeOutputBoolean(ProcessModelParameter parameter, boolean value)
      Stores the value for the specified BOOLEAN output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - the value to be stored
      See Also:

    • writeOutputInteger

      public void writeOutputInteger(String parameterName, long value)
      Stores the value for the specified INTEGER output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - the value to be stored
      See Also:

    • writeOutputInteger

      public void writeOutputInteger(ProcessModelParameter parameter, long value)
      Stores the value for the specified INTEGER output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - the value to be stored
      See Also:

    • writeOutputFloat

      public void writeOutputFloat(String parameterName, double value)
      Stores the value for the specified FLOAT output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - the value to be stored
      See Also:

    • writeOutputFloat

      public void writeOutputFloat(ProcessModelParameter parameter, double value)
      Stores the value for the specified FLOAT output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - the value to be stored
      See Also:

    • writeOutputString

      public void writeOutputString(String parameterName, String value)
      Stores the value for the specified STRING output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - the value to be stored
      See Also:

    • writeOutputString

      public void writeOutputString(ProcessModelParameter parameter, String value)
      Stores the value for the specified STRING output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - the value to be stored
      See Also:

    • writeOutputDate

      public void writeOutputDate(String parameterName, Date value)
      Stores the value for the specified DATE output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - the value to be stored
      See Also:

    • writeOutputDate

      public void writeOutputDate(ProcessModelParameter parameter, Date value)
      Stores the value for the specified DATE output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - the value to be stored
      See Also:

    • writeOutputURI

      public void writeOutputURI(String parameterName, URI value)
      Stores the value for the specified URI output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - the value to be stored
      See Also:

    • writeOutputURI

      public void writeOutputURI(ProcessModelParameter parameter, URI value)
      Stores the value for the specified URI output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - the value to be stored
      See Also:

    • writeOutputUDT

      public void writeOutputUDT(String parameterName, UDTValue value)
      Stores the value for the specified USERDEFINED output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - the value to be stored. The caller is responsible for closing.
      See Also:

    • writeOutputUDT

      public void writeOutputUDT(ProcessModelParameter parameter, UDTValue value)
      Stores the value for the specified USERDEFINED output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - the value to be stored. The caller is responsible for closing.
      See Also:

    • writeOutputUDT

      public void writeOutputUDT(String parameterName, byte[] value)
      Stores the value for the specified USERDEFINED output parameter. The same user-defined type will be assumed as the output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - the value to be stored.
      See Also:

    • writeOutputUDT

      public void writeOutputUDT(ProcessModelParameter parameter, byte[] value)
      Stores the value for the specified USERDEFINED output parameter. The same user-defined type will be assumed as the output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - the value to be stored.
      See Also:

    • writeOutputList

      public void writeOutputList(String parameterName, List<?> value)
      Stores the list value for the specified USERDEFINED output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - The list to be stored. The caller is responsible for closing the elements if appropriate.
      See Also:

    • writeOutputList

      public void writeOutputList(ProcessModelParameter parameter, List<?> value)
      Stores the list value for the specified USERDEFINED output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - The list to be stored. The caller is responsible for closing the elements if appropriate.
      See Also:

    • writeOutputList

      public void writeOutputList(String parameterName, ListUdt value)
      Stores the list value for the specified USERDEFINED output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - The ListUdt to be stored. The caller is responsible for closing.
      See Also:

    • writeOutputList

      public void writeOutputList(ProcessModelParameter parameter, ListUdt value)
      Stores the list value for the specified USERDEFINED output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - The ListUdt to be stored. The caller is responsible for closing.
      See Also:

    • writeOutputObject

      public void writeOutputObject(String parameterName, Serializable value)
      Stores the designated serialisable object for the specified USERDEFINED output parameter. This will overwrite any previously written value.
      Parameters:
      parameterName - name of the output parameter
      value - The serialisable object to store. The caller is responsible for closing if appropriate.
      See Also:

    • writeOutputObject

      public void writeOutputObject(ProcessModelParameter parameter, Serializable value)
      Stores the designated serialisable object for the specified USERDEFINED output parameter. This will overwrite any previously written value.
      Parameters:
      parameter - The output parameter.
      value - The serialisable object to store. The caller is responsible for closing if appropriate.
      See Also:

    • objectToBoolean

      public Boolean objectToBoolean(Object value, ProcessModelParameter parameter, boolean output)
      Converts an object (of native type) to an instance of Boolean. This method should be overridden to convert from the correct native type.
      This implementation casts the designated parameter.
      Parameters:
      value - An instance of Object (native data type) to be converted to Boolean. This may be null or native null.
      The caller is responsible for closing if appropriate.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value cast.

    • objectToInteger

      public Long objectToInteger(Object value, ProcessModelParameter parameter, boolean output)
      Converts an object (of native type) to an instance of Long. This method should be overridden to convert from the correct native type.
      This implementation casts the designated parameter.
      Parameters:
      value - An instance of Object (native data type) to be converted to Long. This may be null or native null.
      The caller is responsible for closing if appropriate.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value cast.

    • objectToFloat

      public Double objectToFloat(Object value, ProcessModelParameter parameter, boolean output)
      Converts an object (of native type) to an instance of Double. This method should be overridden to convert from the correct native type.
      This implementation casts the designated parameter.
      Parameters:
      value - An instance of Object (native data type) to be converted to Double. This may be null or native null.
      The caller is responsible for closing if appropriate.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value cast.

    • objectToString

      public String objectToString(Object value, ProcessModelParameter parameter, boolean output)
      Converts an object (of native type) to an instance of String. This method should be overridden to convert from the correct native type.
      This implementation casts the designated parameter.
      Parameters:
      value - An instance of Object (native data type) to be converted to String. This may be null or native null.
      The caller is responsible for closing if appropriate.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value cast.

    • objectToDate

      public Date objectToDate(Object value, ProcessModelParameter parameter, boolean output)
      Converts an object (of native type) to an instance of Date. This method should be overridden to convert from the correct native type.
      This implementation casts the designated parameter.
      Parameters:
      value - An instance of Object (native data type) to be converted to Date. This may be null or native null.
      The caller is responsible for closing if appropriate.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value cast.

    • objectToUri

      public URI objectToUri(Object value, ProcessModelParameter parameter, boolean output)
      Converts an object (of native type) to an instance of URI. This method should be overridden to convert from the correct native type.
      This implementation casts the designated parameter.
      Parameters:
      value - An instance of Object (native data type) to be converted to URI. This may be null or native null.
      The caller is responsible for closing if appropriate.
      parameter - The corresponding parameter for further information.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      The designated value cast.

    • objectToUserdefined

      public UDTValue objectToUserdefined(Object value, ProcessModelParameter parameter, boolean output)
      Converts an object to an instance of UDTValue by serialising the object and encapsulating the corresponding stream in the returned instance of UDTValue.
      The object needs to be serialisable! In case of a UDTValue, it will be used directly. If the object is not serialisable or serialisation fails, an ApplicationFailedException will be thrown.

      Overriding implementations creating a new UDTValue itself have to add it to closeables.

      Parameters:
      value - The object to store in an instance of UDTValue. This must not be null nor native null.
      The caller is responsible for closing if appropriate.
      parameter - The output parameter that needs a conversion from Object to UDTValue.
      output - Whether the designated parameter is an output parameter (or an input parameter otherwise).
      Returns:
      An instance of UDTValue encapsulating the serialised designated object. The value will be coupled to this ActivityData, so do not close it; clone it if required longer than this ActivityData.

    • getAllConfEntries

      public Collection<String> getAllConfEntries()
      Returns all configuration entry names.
      Returns:
      All entry names that have a value in this configuration or are retrieved from an input parameter or a process configuration.

    • hasConf

      public boolean hasConf(String entryName)
      Returns whether the specified configuration entry is set.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      whether the specified configuration entry is set

    • getConfBoolean

      public Boolean getConfBoolean(String entryName)
      Returns the configuration value of the specified entry or null if it is not set.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value if available or null

    • getConfBoolean

      public Boolean getConfBoolean(String entryName, Boolean defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as BOOLEAN. In the latter case a warning is logged.
      Parameters:
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getConfInteger

      public Long getConfInteger(String entryName)
      Returns the configuration value of the specified entry or null if it is not set.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value if available or null

    • getConfInteger

      public Long getConfInteger(String entryName, Long defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as INTEGER. In the latter case a warning is logged.
      Parameters:
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getConfFloat

      public Double getConfFloat(String entryName)
      Returns the configuration value of the specified entry or the given value if it is not set or could not be parsed as FLOAT. In the latter case a warning is logged.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value if available or null

    • getConfFloat

      public Double getConfFloat(String entryName, Double defaultValue)
      Returns the configuration value of the specified entry or the given value if it is not set or could not be parsed as FLOAT. In the latter case a warning is logged.
      Parameters:
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getConfString

      public String getConfString(String entryName)
      Returns the configuration value of the specified entry or null if it is not set.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value if available or null

    • getConfString

      public String getConfString(String entryName, String defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set.
      Parameters:
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getConfDate

      public Date getConfDate(String entryName)
      Returns the configuration value of the specified entry or null if it is not set.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value if available or null

    • getConfDate

      public Date getConfDate(String entryName, Date defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as DATE. In the latter case a warning is logged.
      Parameters:
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getConfURI

      public URI getConfURI(String entryName)
      Returns the configuration value of the specified entry or null if it is not set.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value if available or null

    • getConfURI

      public URI getConfURI(String entryName, URI defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as URI. In the latter case a warning is logged.
      Parameters:
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getConfUDT

      public byte[] getConfUDT(String entryName)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as USERDEFINED. In the latter case a warning is logged.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value if available or null

    • getConfUDT

      public byte[] getConfUDT(String entryName, byte[] defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as USERDEFINED. In the latter case a warning is logged.
      Parameters:
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • requireConfBoolean

      public boolean requireConfBoolean(String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as BOOLEAN

    • requireConfInteger

      public long requireConfInteger(String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as INTEGER

    • requireConfFloat

      public double requireConfFloat(String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as FLOAT

    • requireConfString

      public String requireConfString(String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing

    • requireConfDate

      public Date requireConfDate(String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as DATE

    • requireConfURI

      public URI requireConfURI(String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as URI

    • requireConfUDT

      public byte[] requireConfUDT(String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as USERDEFINED

    • hasParamConf

      public boolean hasParamConf(ActivityConstants.AccessType accessType, String parameterName, String entryName)
      Returns whether the specified configuration entry is set.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      Returns:
      whether the specified configuration entry is set

    • hasParamConf

      public boolean hasParamConf(ActivityConstants.AccessType accessType, Parameter parameter, String entryName)
      Returns whether the specified configuration entry is set.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      Returns:
      whether the specified configuration entry is set

    • getParamConfBoolean

      public Boolean getParamConfBoolean(ActivityConstants.AccessType accessType, String parameterName, String entryName, Boolean defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as BOOLEAN. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfBoolean

      public Boolean getParamConfBoolean(ActivityConstants.AccessType accessType, Parameter parameter, String entryName, Boolean defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as BOOLEAN. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfInteger

      public Long getParamConfInteger(ActivityConstants.AccessType accessType, String parameterName, String entryName, Long defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as INTEGER. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfInteger

      public Long getParamConfInteger(ActivityConstants.AccessType accessType, Parameter parameter, String entryName, Long defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as INTEGER. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfFloat

      public Double getParamConfFloat(ActivityConstants.AccessType accessType, String parameterName, String entryName, Double defaultValue)
      Returns the configuration value of the specified entry or the given value if it is not set or could not be parsed as FLOAT. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfFloat

      public Double getParamConfFloat(ActivityConstants.AccessType accessType, Parameter parameter, String entryName, Double defaultValue)
      Returns the configuration value of the specified entry or the given value if it is not set or could not be parsed as FLOAT. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfString

      public String getParamConfString(ActivityConstants.AccessType accessType, String parameterName, String entryName, String defaultValue)
      Returns the configuration value of the specified entry or null if it is not set.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfString

      public String getParamConfString(ActivityConstants.AccessType accessType, Parameter parameter, String entryName, String defaultValue)
      Returns the configuration value of the specified entry or null if it is not set.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfDate

      public Date getParamConfDate(ActivityConstants.AccessType accessType, String parameterName, String entryName, Date defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as DATE. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfDate

      public Date getParamConfDate(ActivityConstants.AccessType accessType, Parameter parameter, String entryName, Date defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as DATE. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfURI

      public URI getParamConfURI(ActivityConstants.AccessType accessType, String parameterName, String entryName, URI defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as URI. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfURI

      public URI getParamConfURI(ActivityConstants.AccessType accessType, Parameter parameter, String entryName, URI defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as URI. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfUDT

      public byte[] getParamConfUDT(ActivityConstants.AccessType accessType, String parameterName, String entryName, byte[] defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as USERDEFINED. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • getParamConfUDT

      public byte[] getParamConfUDT(ActivityConstants.AccessType accessType, Parameter parameter, String entryName, byte[] defaultValue)
      Returns the configuration value of the specified entry or the given default value if it is not set or could not be parsed as USERDEFINED. In the latter case a warning is logged.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      defaultValue - the default value that will be returned if the configuration value is missing; may be null
      Returns:
      the configuration value or the given default value

    • requireParamConfBoolean

      public boolean requireParamConfBoolean(ActivityConstants.AccessType accessType, String parameterName, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as BOOLEAN

    • requireParamConfBoolean

      public boolean requireParamConfBoolean(ActivityConstants.AccessType accessType, Parameter parameter, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as BOOLEAN

    • requireParamConfInteger

      public long requireParamConfInteger(ActivityConstants.AccessType accessType, String parameterName, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as INTEGER

    • requireParamConfInteger

      public long requireParamConfInteger(ActivityConstants.AccessType accessType, Parameter parameter, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as INTEGER

    • requireParamConfFloat

      public double requireParamConfFloat(ActivityConstants.AccessType accessType, String parameterName, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as FLOAT

    • requireParamConfFloat

      public double requireParamConfFloat(ActivityConstants.AccessType accessType, Parameter parameter, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      Returns:
      the configuration value
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as FLOAT

    • requireParamConfString

      public String requireParamConfString(ActivityConstants.AccessType accessType, String parameterName, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing

    • requireParamConfString

      public String requireParamConfString(ActivityConstants.AccessType accessType, Parameter parameter, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing

    • requireParamConfDate

      public Date requireParamConfDate(ActivityConstants.AccessType accessType, String parameterName, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as DATE

    • requireParamConfDate

      public Date requireParamConfDate(ActivityConstants.AccessType accessType, Parameter parameter, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as DATE

    • requireParamConfURI

      public URI requireParamConfURI(ActivityConstants.AccessType accessType, String parameterName, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as URI

    • requireParamConfURI

      public URI requireParamConfURI(ActivityConstants.AccessType accessType, Parameter parameter, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as URI

    • requireParamConfUDT

      public byte[] requireParamConfUDT(ActivityConstants.AccessType accessType, String parameterName, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameterName - the name of the parameter
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as USERDEFINED

    • requireParamConfUDT

      public byte[] requireParamConfUDT(ActivityConstants.AccessType accessType, Parameter parameter, String entryName)
      Returns the configuration value of the specified entry or throws an exception if it is not available.
      Parameters:
      accessType - the access type of the parameter
      parameter - The parameter.
      entryName - name of the configuration entry
      Returns:
      the configuration value; never null
      Throws:
      ApplicationEnvironmentException - if the value is missing or cannot be parsed as USERDEFINED

    • getActInstConfValue

      protected Object getActInstConfValue(String entryName, ProcessConstants.AdeptDataType expDt, boolean required, Object defValue)
      Gets the designated activity instance configuration value and logs messages or throws exceptions if it is not present.
      Parameters:
      entryName - the name of the configuration entry for which to retrieve the value.
      expDt - The expected data type of the configuration value.
      required - Whether the configuration value is required and an ApplicationEnvironmentException is to be thrown in case it is not present.
      defValue - The default value to be used in case the configuration value is optional and not set.
      Returns:
      The corresponding configuration value.

    • getParamConfValue

      protected Object getParamConfValue(ActivityConstants.AccessType accessType, String parameterName, String entryName, ProcessConstants.AdeptDataType expDt, boolean required, Object defValue)
      Gets the designated parameter configuration value and logs messages or throws exceptions if it is not present.
      Parameters:
      accessType - The access type of the parameter.
      parameterName - The name of the parameter.
      entryName - the name of the configuration entry for which to retrieve the value.
      expDt - The expected data type of the configuration value.
      required - Whether the configuration value is required and an ApplicationEnvironmentException is to be thrown in case it is not present.
      defValue - The default value to be used in case the configuration value is optional and not set.
      Returns:
      The corresponding configuration value.

    • getParamConfValue

      protected Object getParamConfValue(ActivityConstants.AccessType accessType, Parameter parameter, String entryName, ProcessConstants.AdeptDataType expDt, boolean required, Object defValue)
      Gets the designated parameter configuration value and logs messages or throws exceptions if it is not present.
      Parameters:
      accessType - The access type of the parameter.
      parameter - The parameter of which to get the configuration value.
      entryName - the name of the configuration entry for which to retrieve the value.
      expDt - The expected data type of the configuration value.
      required - Whether the configuration value is required and an ApplicationEnvironmentException is to be thrown in case it is not present.
      defValue - The default value to be used in case the configuration value is optional and not set.
      Returns:
      The corresponding configuration value.

    • getConfValue

      protected Object getConfValue(Configuration conf, String entryName, ProcessConstants.AdeptDataType expDt, boolean required, Object defValue, String paramText)
      Gets the designated configuration value and logs messages or throws exceptions if it is not present.
      Parameters:
      conf - The configuration to retrieve the value from.
      entryName - the name of the configuration entry for which to retrieve the value.
      expDt - The expected data type of the configuration value.
      required - Whether the configuration value is required and an ApplicationEnvironmentException is to be thrown in case it is not present.
      defValue - The default value to be used in case the configuration value is optional and not set.
      paramText - The additional text used for logging or the exceptions in case of a parameter configuration. This provides the name and the direction of the parameter. In case of the configuration of the activity instance this should be the empty string.
      Returns:
      The corresponding configuration value.

    • closeIfCreated

      protected void closeIfCreated(Object obj)
      Closes the designated object via IoTools.closeLogged(Logger, AutoCloseable...) if the object should be close by this ActivityData, that is, it is in closeables.
      Parameters:
      obj - The object which is closed in case it should been closed by this ActivityData.

    • closeElemsIfCreated

      protected void closeElemsIfCreated(Collection<?> coll, Object... survivors)
      Closes the elements of the designated collection via IoTools.closeLogged(Logger, AutoCloseable...) if the element should be close by this ActivityData, that is, it is in closeables.
      Parameters:
      coll - A collection of objects to close when created by this ActivityData.
      survivors - Objects that will not be closed when found in the list. Object identity is used for comparison, not Object.equals(Object)!

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • getParametersSortedByPosition

      public static Deque<ProcessModelParameter> getParametersSortedByPosition(Collection<? extends ProcessModelParameter> params)
      Gets the designated parameters sorted by the configured position. Parameters without a position will be ignored.
      Parameters:
      params - The parameters which to sort by their configured position.
      Returns:
      The designated parameters having a configuration for a position sorted by this position.