Package de.iip_ecosphere.platform.connectors.model

Interface ModelAccess

All Known Implementing Classes:
AbstractModelAccess, AbstractTypeMappingModelAccess
public interface ModelAccess
Provides access to a model-based protocol such as OPC UA or AAS. This interface shall be implemented by the connector and provided to the protocol adapter/type translators so that they can access the underlying model in a uniform manner. This interface is preliminary and not complete. Qualified names (qName) follow a hierarchical naming schema separated by getQSeparator(). For now, we assume a simple property/operation-based model with basic support for individual struct/record-based types. In individual protocols, some operations may not be supported and shall be terminated by an exception. The assumption is that the respective adapter is either programmed having the protocol in mind or adequately generated. See the annotation MachineConnector that a connector shall be decorated with to steer the generation. Initially we considered having direct access into the connector instance as fallback. However, in the mean time we believe that we then have to adjust the abstraction accordingly.
Author:
Holger Eichelberger, SSE

  • Method Details

    • topInstancesQName

      String topInstancesQName()
      Returns the prefix to be used to access the instances within this model.
      Returns:
      the prefix, may be empty for none

    • getQSeparator

      String getQSeparator()
      Returns the qualified name separator.
      Returns:
      the qualified name separator, empty if MachineConnector.supportsHierarchicalQNames() is false

    • qName

      String qName(String... names)
      Composes multiple names to a qualified name using getQSeparator().
      Parameters:
      names - the names (may be empty but shall be ignored then)
      Returns:
      the composed qualified name, empty if no names were given

    • iqName

      String iqName(String... names)
      Composes multiple names to a qualified instance name starting with topInstancesQName() using getQSeparator().
      Parameters:
      names - the names (may be empty but shall be ignored then)
      Returns:
      the composed qualified name, empty if no names were given

    • call

      Object call(String qName, Object... args) throws IOException
      Calls an operation on the model.
      Parameters:
      qName - the qualified name of the operation (composed using getQSeparator()).
      args - the arguments for the call
      Returns:
      the return value (may be null for void)
      Throws:
      IOException - in case that the call fails or calls are not implemented (see MachineConnector.supportsModelCalls() is false)

    • get

      Object get(String qName) throws IOException
      Returns a property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value (may be null for void)
      Throws:
      IOException - in case that the access fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • get

      default Object get(String qName, int lifetime) throws IOException
      Returns a property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      lifetime - cache of a node value in the cache, 0 = no caching, negative = forever, positive = lifetime
      Returns:
      the property value (may be null for void)
      Throws:
      IOException - in case that the access fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getInt

      default int getInt(String qName) throws IOException
      Returns an int property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value
      Throws:
      IOException - in case that the access/conversion fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getFloat

      default float getFloat(String qName) throws IOException
      Returns a float property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value
      Throws:
      IOException - in case that the access/conversion fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getDouble

      default double getDouble(String qName) throws IOException
      Returns a double property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value
      Throws:
      IOException - in case that the access/conversion fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getLong

      default long getLong(String qName) throws IOException
      Returns a double property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value
      Throws:
      IOException - in case that the access/conversion fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getShort

      default short getShort(String qName) throws IOException
      Returns a short property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value
      Throws:
      IOException - in case that the access/conversion fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getByte

      default byte getByte(String qName) throws IOException
      Returns a byte property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value
      Throws:
      IOException - in case that the access/conversion fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getBoolean

      default boolean getBoolean(String qName) throws IOException
      Returns a byte property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value
      Throws:
      IOException - in case that the access/conversion fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getString

      default String getString(String qName) throws IOException
      Returns a byte property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      Returns:
      the property value
      Throws:
      IOException - in case that the access/conversion fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • getMultiValue

      default <C> List<de.iip_ecosphere.platform.transport.serialization.QualifiedElement<C>> getMultiValue(Class<C> eltCls, String name, boolean enumerated, String... qualifiers) throws IOException
      Returns the value of a multi-valued property in IDTA style.
      Type Parameters:
      C - the type of the element value
      Parameters:
      eltCls - the class of the element value type
      name - the (basic, generic) name of the property
      enumerated - whether the name used for identifying multi-values in a sequence or whether their qualifiers shall be used
      qualifiers - the qualifier(s) denoting the properties to return if enumerated is false
      Returns:
      the value(s), may be null for none, may be null at individual positions if casting to cls fails
      Throws:
      IOException - an exception if accessing a relevant property/value fails (always, see MachineConnector.supportsMultiValued())

    • set

      void set(String qName, Object value) throws IOException
      Changes a property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setInt

      default void setInt(String qName, int value) throws IOException
      Changes an int property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setLong

      default void setLong(String qName, long value) throws IOException
      Changes a long property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setByte

      default void setByte(String qName, byte value) throws IOException
      Changes a byte property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setShort

      default void setShort(String qName, short value) throws IOException
      Changes a short property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setBoolean

      default void setBoolean(String qName, boolean value) throws IOException
      Changes a boolean property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setDouble

      default void setDouble(String qName, double value) throws IOException
      Changes a double property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setFloat

      default void setFloat(String qName, float value) throws IOException
      Changes a float property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setString

      default void setString(String qName, String value) throws IOException
      Changes a string property value.
      Parameters:
      qName - the qualified name of the property (composed using getQSeparator()).
      value - the new property value
      Throws:
      IOException - in case that the access fails or setting properties is not implemented (see MachineConnector.supportsModelProperties() is false)

    • setMultiValue

      default void setMultiValue(String name, boolean enumerated, Object elements) throws IOException
      Sets a multi-value represented by multiple entities.
      Parameters:
      name - the (basic, generic) name of the property
      enumerated - whether the name used for identifying multi-values in a sequence or whether their qualifiers shall be used
      elements - the elements/values to be set
      Throws:
      IOException - an exception if accessing a relevant property/value fails (always, see MachineConnector.supportsMultiValued())

    • setMultiValue

      default void setMultiValue(String name, boolean enumerated, List<de.iip_ecosphere.platform.transport.serialization.QualifiedElement<?>> elements) throws IOException
      Sets a multi-value represented by multiple entities.
      Parameters:
      name - the (basic, generic) name of the property
      enumerated - whether the name used for identifying multi-values in a sequence or whether their qualifiers shall be used
      elements - the elements/values to be set
      Throws:
      IOException - an exception if accessing a relevant property/value fails (always, see MachineConnector.supportsMultiValued())

    • getStruct

      <T> T getStruct(String qName, Class<T> type) throws IOException
      Returns the "struct" value of a property. We assume that there is a type definition for the struct realized as class which also represents the actual values. Usually, such custom datatypes must be registered through registerCustomType(Class). Details shall be documented by the implementing connector. [struct]
      Type Parameters:
      T - the type of the struct
      Parameters:
      qName - the qualified name of the property
      type - the expected type
      Returns:
      the value of the slot
      Throws:
      IOException - in case that the access fails or structs are not supported (see MachineConnector.supportsModelStructs() is false)
      See Also:

    • setStruct

      void setStruct(String qName, Object value) throws IOException
      Changes the "struct" value of a property. We assume that there is a type definition for the struct realized as class which also represents the actual values. Usually, such custom datatypes must be registered through registerCustomType(Class). Details shall be documented by the implementing connector. [struct]
      Parameters:
      qName - the qualified name of the slot in the struct
      value - the slot value
      Throws:
      IOException - in case that the access fails or structs are not supported (see MachineConnector.supportsModelStructs() is false)
      See Also:

    • registerCustomType

      void registerCustomType(Class<?> cls) throws IOException
      Registers cls as a custom type, e.g., for structs.
      Parameters:
      cls - the class representing the custom type
      Throws:
      IOException - in case that accessing relevant information on cls for performing the registration fails or structs are not supported (see MachineConnector.supportsModelStructs() is false)

    • monitor

      void monitor(String... qNames) throws IOException
      Monitors the given qName element in the server namespace and upon changes, triggers a reception in the connector. Intended to be used in ConnectorOutputTypeTranslator.initializeModelAccess(). ConnectorParameter.getNotificationInterval() shall be used as default value if applicable. [monitoring]
      Parameters:
      qNames - the qualified names of the elements to monitor
      Throws:
      IOException - if creating the monitor fails

    • monitor

      void monitor(int notificationInterval, String... qNames) throws IOException
      Monitors the given qName element in the server namespace and upon changes, triggers a reception in the connector. Intended to be used in ConnectorOutputTypeTranslator.initializeModelAccess(). [monitoring]
      Parameters:
      notificationInterval - explicit time interval between two notifications (if applicable)
      qNames - the qualified names of the elements to monitor
      Throws:
      IOException - if creating the monitor fails

    • monitorModelChanges

      void monitorModelChanges() throws IOException
      Monitors generic model changes, in particular those not covered by monitor(String...). Triggers a reception in the connector. Intended to be used in ConnectorOutputTypeTranslator.initializeModelAccess(). ConnectorParameter.getNotificationInterval() shall be used as default value if applicable. [monitoring]
      Throws:
      IOException - if creating the monitor fails

    • monitorModelChanges

      void monitorModelChanges(int notificationInterval) throws IOException
      Monitors generic model changes, in particular those not covered by monitor(String...). Triggers a reception in the connector. Intended to be used in ConnectorOutputTypeTranslator.initializeModelAccess(). [monitoring]
      Parameters:
      notificationInterval - explicit time interval between two notifications (if applicable)
      Throws:
      IOException - if creating the monitor fails

    • setDetailNotifiedItem

      void setDetailNotifiedItem(boolean detail)
      Whether the connector shall send detailed information about monitored changes. Intended to be used in ConnectorOutputTypeTranslator.initializeModelAccess(). [monitoring]
      Parameters:
      detail - true for details, false for null (default)

    • useNotifications

      void useNotifications(boolean notifications)
      Use notifications or polling. This is required here, as the related translator code monitor(String...) depends on that. [monitoring]
      Parameters:
      notifications - true for notifications, false for polling

    • getInputConverter

      default ModelInputConverter getInputConverter()
      Returns the input converter instance.
      Returns:
      the input converter

    • getOutputConverter

      default ModelOutputConverter getOutputConverter()
      Returns the output converter instance.
      Returns:
      the output converter

    • stepInto

      ModelAccess stepInto(String name) throws IOException
      Sets the hierarchical substructure denoted by name as current scope for further resolution. When overriding, declare the actual type as result type.
      Parameters:
      name - non-hierarchical name of contained substructure
      Returns:
      the sub parse-result taking name as context, use #stepOut() to leave that context
      Throws:
      IOException - if stepping into fails for some reason

    • stepOut

      ModelAccess stepOut()
      Steps out of the actual context set by stepInto(String). When overriding, declare the actual type as result type.
      Returns:
      the actual (parent) context, may be null if this step out was illegal in a non-nested context

    • dispose

      default void dispose()
      Called when this instance is explicitly not needed anymore. May not be called in single-threaded connectors.