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
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