Package de.iip_ecosphere.platform.connectors.model

Interface ModelAccess

  • All Known Implementing Classes:
    AbstractModelAccess
    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 Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      java.lang.Object call​(java.lang.String qName, java.lang.Object... args)
      Calls an operation on the model.
      java.lang.Object get​(java.lang.String qName)
      Returns a property value.
      default java.lang.Object get​(java.lang.String qName, int lifetime)
      Returns a property value.
      default boolean getBoolean​(java.lang.String qName)
      Returns a byte property value.
      default byte getByte​(java.lang.String qName)
      Returns a byte property value.
      default double getDouble​(java.lang.String qName)
      Returns a double property value.
      default float getFloat​(java.lang.String qName)
      Returns a float property value.
      default ModelInputConverter getInputConverter()
      Returns the input converter instance.
      default int getInt​(java.lang.String qName)
      Returns an int property value.
      default long getLong​(java.lang.String qName)
      Returns a double property value.
      default ModelOutputConverter getOutputConverter()
      Returns the output converter instance.
      java.lang.String getQSeparator()
      Returns the qualified name separator.
      default short getShort​(java.lang.String qName)
      Returns a short property value.
      default java.lang.String getString​(java.lang.String qName)
      Returns a byte property value.
      <T> T getStruct​(java.lang.String qName, java.lang.Class<T> type)
      Returns the "struct" value of a property.
      java.lang.String iqName​(java.lang.String... names)
      Composes multiple names to a qualified instance name starting with topInstancesQName() using getQSeparator().
      void monitor​(int notificationInterval, java.lang.String... qNames)
      Monitors the given qName element in the server namespace and upon changes, triggers a reception in the connector.
      void monitor​(java.lang.String... qNames)
      Monitors the given qName element in the server namespace and upon changes, triggers a reception in the connector.
      void monitorModelChanges()
      Monitors generic model changes, in particular those not covered by monitor(String...).
      void monitorModelChanges​(int notificationInterval)
      Monitors generic model changes, in particular those not covered by monitor(String...).
      java.lang.String qName​(java.lang.String... names)
      Composes multiple names to a qualified name using getQSeparator().
      void registerCustomType​(java.lang.Class<?> cls)
      Registers cls as a custom type, e.g., for structs.
      void set​(java.lang.String qName, java.lang.Object value)
      Changes a property value.
      default void setBoolean​(java.lang.String qName, boolean value)
      Changes a boolean property value.
      default void setByte​(java.lang.String qName, byte value)
      Changes a byte property value.
      void setDetailNotifiedItem​(boolean detail)
      Whether the connector shall send detailed information about monitored changes.
      default void setDouble​(java.lang.String qName, double value)
      Changes a double property value.
      default void setFloat​(java.lang.String qName, float value)
      Changes a float property value.
      default void setInt​(java.lang.String qName, int value)
      Changes an int property value.
      default void setLong​(java.lang.String qName, long value)
      Changes a long property value.
      default void setShort​(java.lang.String qName, short value)
      Changes a short property value.
      default void setString​(java.lang.String qName, java.lang.String value)
      Changes a string property value.
      void setStruct​(java.lang.String qName, java.lang.Object value)
      Changes the "struct" value of a property.
      ModelAccess stepInto​(java.lang.String name)
      Sets the hierarchical substructure denoted by name as current scope for further resolution.
      ModelAccess stepOut()
      Steps out of the actual context set by stepInto(String).
      java.lang.String topInstancesQName()
      Returns the prefix to be used to access the instances within this model.
      void useNotifications​(boolean notifications)
      Use notifications or polling.

    • Method Detail

      • topInstancesQName

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

      • qName

        java.lang.String qName​(java.lang.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

        java.lang.String iqName​(java.lang.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

        java.lang.Object call​(java.lang.String qName,
                      java.lang.Object... args)
               throws java.io.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:
        java.io.IOException - in case that the call fails or calls are not implemented (see MachineConnector.supportsModelCalls() is false)

      • get

        java.lang.Object get​(java.lang.String qName)
              throws java.io.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:
        java.io.IOException - in case that the access fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

      • get

        default java.lang.Object get​(java.lang.String qName,
                             int lifetime)
                      throws java.io.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:
        java.io.IOException - in case that the access fails or reading properties is not implemented (see MachineConnector.supportsModelProperties() is false)

      • getInt

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

      • getFloat

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

      • getDouble

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

      • getLong

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

      • getShort

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

      • getByte

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

      • getBoolean

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

      • getString

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

      • set

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

      • setInt

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

      • setLong

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

      • setByte

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

      • setShort

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

      • setBoolean

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

      • setDouble

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

      • setFloat

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

      • setString

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

      • getStruct

        <T> T getStruct​(java.lang.String qName,
                java.lang.Class<T> type)
         throws java.io.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:
        java.io.IOException - in case that the access fails or structs are not supported (see MachineConnector.supportsModelStructs() is false)
        See Also:
        registerCustomType(Class)

      • setStruct

        void setStruct​(java.lang.String qName,
               java.lang.Object value)
        throws java.io.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:
        java.io.IOException - in case that the access fails or structs are not supported (see MachineConnector.supportsModelStructs() is false)
        See Also:
        registerCustomType(Class)

      • registerCustomType

        void registerCustomType​(java.lang.Class<?> cls)
                 throws java.io.IOException
        Registers cls as a custom type, e.g., for structs.
        Parameters:
        cls - the class representing the custom type
        Throws:
        java.io.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​(java.lang.String... qNames)
      throws java.io.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:
        java.io.IOException - if creating the monitor fails

      • monitor

        void monitor​(int notificationInterval,
             java.lang.String... qNames)
      throws java.io.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:
        qNames - the qualified names of the elements to monitor
        notificationInterval - explicit time interval between two notifications (if applicable)
        Throws:
        java.io.IOException - if creating the monitor fails

      • monitorModelChanges

        void monitorModelChanges​(int notificationInterval)
                  throws java.io.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:
        java.io.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​(java.lang.String name)
              throws java.io.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:
        java.io.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