Package de.iip_ecosphere.platform.connectors

Interface Connector<O,I,CO,CI>

Type Parameters:
O - the output type from the underlying machine/platform
I - the input type to the underlying machine/platform
CO - the output type of the connector
CI - the input type of the connector
All Superinterfaces:
EventHandlingConnector
All Known Implementing Classes:
AbstractChannelConnector, AbstractConnector, AbstractThreadedConnector, AbstractThreadedQueuingConnector
public interface Connector<O,I,CO,CI> extends EventHandlingConnector
The interface of a platform/machine connector. A connector shall define a ConnectorDescriptor as top-level inner class and register the descriptor as service. By default, polling shall be enabled but in certain cases this may not fit into the lifecycle of services in a service environment. Then it is possible to explicitly enable/disable polling.
Author:
Holger Eichelberger, SSE

  • Method Details

    • connect

      void connect(ConnectorParameter params) throws IOException
      Connects the connector to the underlying machine/platform.
      Parameters:
      params - connection parameter
      Throws:
      IOException - in case that connecting fails

    • request

      CO request(boolean sendToCallback) throws IOException
      Explicitly requests reading data from the source. This is typically done by polling or events, but, in seldom cases, may be needed manually.
      Parameters:
      sendToCallback - whether the reception callback shall be informed about new data
      Returns:
      the data from the machine, null for none, i.e., also no call to the reception callback
      Throws:
      IOException - in case that reading fails

    • write

      void write(CI data) throws IOException
      Writes the given data to the underlying machine/platform.
      Parameters:
      data - the data to send to stream
      Throws:
      IOException - in case that problems during the connection happens

    • setReceptionCallback

      void setReceptionCallback(de.iip_ecosphere.platform.transport.connectors.ReceptionCallback<CO> callback) throws IOException
      Attaches a reception callback to this connector. The callback is called upon a reception.
      Parameters:
      callback - the callback to attach
      Throws:
      IOException - in case that problems during registering the callback (e.g., during subscription) happens

    • setReceptionCallbackSafe

      default void setReceptionCallbackSafe(de.iip_ecosphere.platform.transport.connectors.ReceptionCallback<CO> callback)
      Attaches a reception callback to this connector. The callback is called upon a reception. Exceptions are not thrown rather than logged.
      Parameters:
      callback - the callback to attach

    • disconnect

      void disconnect() throws IOException
      Disconnects the connector from the underlying machine/platform.
      Throws:
      IOException - in case that connecting fails

    • disconnectSafe

      default void disconnectSafe()
      Disconnects the connector from the underlying machine/platform. Logs exceptions was warning.

    • dispose

      void dispose()
      Final cleanup when platform shuts down, e.g., for shared resources.

    • getProtocolInputType

      Class<? extends I> getProtocolInputType()
      Returns the input type to the protocol.
      Returns:
      the input type (may be null in case of generic types, but shall not be null)

    • getConnectorInputType

      Class<? extends CI> getConnectorInputType()
      Returns the input type from the IIP-Ecosphere platform.
      Returns:
      the input type (may be null in case of generic types, but shall not be null)

    • getProtocolOutputType

      Class<? extends O> getProtocolOutputType()
      Returns the output type of the protocol.
      Returns:
      the output type (may be null in case of generic types, but shall not be null)

    • getConnectorOutputType

      Class<? extends CO> getConnectorOutputType()
      Returns the output type to the IIP-Ecosphere platform.
      Returns:
      the output type (may be null in case of generic types, but shall not be null)

    • supportedEncryption

      String supportedEncryption()
      Returns the supported encryption mechanisms.
      Returns:
      the supported encryption mechanisms (comma-separated), may be null or empty

    • enabledEncryption

      String enabledEncryption()
      Returns the actually enabled encryption mechanisms on this instance. The result may change when connecting the connector.
      Returns:
      the enabled encryption mechanisms (comma-separated), may be null or empty

    • enableNotifications

      void enableNotifications(boolean enableNotifications)
      Enables/disables notifications/polling at all.
      Parameters:
      enableNotifications - enable or disable notifications

    • getCachingStrategyCls

      default Class<? extends CachingStrategy> getCachingStrategyCls()
      Returns the actual caching strategy class.
      Returns:
      the strategy class

    • notifyReconfigured

      default void notifyReconfigured(String parameterName, String value)
      Called when parameters of the containing service are changed.
      Parameters:
      parameterName - the parameter name
      value - the new value

    • setDataTimeDifferenceProvider

      default void setDataTimeDifferenceProvider(DataTimeDifferenceProvider<CO> provider)
      Defines the time difference provider. Depends on the connector implementation.
      Parameters:
      provider - the provider, may be null for none

    • setInstanceIdentification

      void setInstanceIdentification(String identification)
      Sets an instance identification for connector extensions.
      Parameters:
      identification - the identification

    • getInstanceIdentification

      String getInstanceIdentification()
      Returns the instance identification for connector extensions.
      Returns:
      the identification, set before by setInstanceIdentification(String)

    • createSharedSpace

      default SharedSpace createSharedSpace()
      Creates a shared space among connector instances of the same type. Shall be created before connect(ConnectorParameter).
      Returns:
      the shared space or null if no shared space is supported.

    • enableSharedSpace

      default boolean enableSharedSpace(SharedSpace space)
      Enables a shared space among connector instances of the same type (created by the first MIMO connector). Shall be enabled before connect(ConnectorParameter).
      Parameters:
      space - the shared space, may be null if a createSharedSpace() has returned null
      Returns:
      true if the space has been taken up/established, false else

    • notificationsChanged

      default void notificationsChanged(boolean useNotifications)
      Called when the notifications setting has been changed.
      Parameters:
      useNotifications - the new value after changing

    • enumerateFields

      default List<ConnectorField> enumerateFields()
      Returns all declared fields that the connector may access, i.e., enumerateFields(String) with an empty argument.
      See Also:

    • enumerateFields

      default List<ConnectorField> enumerateFields(String path)
      Returns the declared fields that the connector may access. A connector may or not implement this function.
      Parameters:
      path - the path
      Returns:
      the fields, shall be an empty list if the connector does not provide access to the fields

    • emitSomeData

      default boolean emitSomeData() throws IOException
      Emits arbitrary data accessible to the connector to the console. May not be implemented by the connector. For now, may render regular reception unusable, i.e., if not needed anymore, may require re-connect.
      Returns:
      true if this call affected regular connectivity, false else
      Throws:
      IOException - if not connected