Package de.iip_ecosphere.platform.connectors

Class AbstractConnector<O,I,CO,CI>

java.lang.Object
de.iip_ecosphere.platform.connectors.AbstractConnector<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 Implemented Interfaces:
Connector<O,I,CO,CI>, EventHandlingConnector, AbstractModelAccess.NotificationChangedListener
Direct Known Subclasses:
AbstractChannelConnector, AbstractThreadedConnector
public abstract class AbstractConnector<O,I,CO,CI> extends Object implements Connector<O,I,CO,CI>, AbstractModelAccess.NotificationChangedListener
Provides a reusable base of a Connector implementation using the ProtocolAdapter. Call initializeModelAccess() on connect(ConnectorParameter) as soon as the connector is connected. Handles interactions with ConnectorRegistry.
Author:
Holger Eichelberger, SSE

  • Field Details

  • Constructor Details

    • AbstractConnector

      @SafeVarargs protected AbstractConnector(ProtocolAdapter<O,I,CO,CI>... adapter)
      Creates an instance and installs the protocol adapter(s) with a default selector for the first adapter. For integration compatibility, connector constructors are supposed to accept a var-arg parameter for adapters.
      Parameters:
      adapter - the protocol adapter(s)
      Throws:
      IllegalArgumentException - if adapter is null or empty or adapters are null

    • AbstractConnector

      @SafeVarargs protected AbstractConnector(AdapterSelector<O,I,CO,CI> selector, ProtocolAdapter<O,I,CO,CI>... adapter)
      Creates an instance and installs the protocol adapter(s). For integration compatibility, connector constructors are supposed to accept a var-arg parameter for adapters.
      Parameters:
      selector - the adapter selector (null leads to a default selector for the first adapter)
      adapter - the protocol adapter(s)
      Throws:
      IllegalArgumentException - if adapter is null or empty or adapters are null

  • Method Details

    • initSelector

      protected void initSelector(AdapterSelector<O,I,CO,CI> selector)
      Calls AdapterSelector.init(de.iip_ecosphere.platform.connectors.AdapterSelector.AdapterProvider) with a provider instance pointing to the adapters in this instance.
      Parameters:
      selector - the selector to initialize

    • useTls

      public static boolean useTls(ConnectorParameter params)
      Returns whether the connector shall use TLS.
      Parameters:
      params - the transport parameters
      Returns:
      true for TLS enabled, false else

    • createTlsContext

      protected SSLContext createTlsContext(ConnectorParameter params) throws IOException
      Helper method to determine a SSL/TLS context. Apply only if useTls(ConnectorParameter) returns true. Relies on IdentityStore#createTlsContext(String, String, String...) if TransportParameter.getKeystoreKey() is given, else on SslUtils.createTlsContext(java.io.File, String, String).
      Parameters:
      params - the connector parameters
      Returns:
      the TLS context
      Throws:
      IOException - if creating the context or obtaining key information fails

    • configureModelAccess

      protected void configureModelAccess(ModelAccess access)
      Configures the model access on all protocol adapters.
      Parameters:
      access - the model access

    • getSelector

      protected AdapterSelector<O,I,CO,CI> getSelector()
      Returns the adapter selector.
      Returns:
      the selector

    • connect

      public void connect(ConnectorParameter params) throws IOException
      Connects the connector to the underlying machine/platform. Calls connectImpl(ConnectorParameter) and if successful (no exception thrown) initializeModelAccess(). Calls ConnectorRegistry.registerConnector(Connector).
      Specified by:
      connect in interface Connector<O,I,CO,CI>
      Parameters:
      params - connection parameter
      Throws:
      IOException - in case that connecting fails

    • connectImpl

      protected abstract void connectImpl(ConnectorParameter params) throws IOException
      Implements the connect(ConnectorParameter) method assuming that everything is ok if no exception have been thrown.
      Parameters:
      params - connection parameter
      Throws:
      IOException - in case that connecting fails

    • getConnectorParameter

      protected ConnectorParameter getConnectorParameter()
      Returns the connector parameters after the last connect(ConnectorParameter).
      Returns:
      the connector params

    • installPollTask

      protected void installPollTask()
      Install poll task. No task will be installed if ConnectorParameter.getNotificationInterval() is less than 1. Call only after connect(ConnectorParameter) and before disconnect().

    • enablePolling

      public void enablePolling(boolean enablePolling)
      Description copied from interface: EventHandlingConnector
      Enable/disable polling (does not influence the polling timer).
      Specified by:
      enablePolling in interface EventHandlingConnector
      Parameters:
      enablePolling - whether polling shall enabled
      See Also:

    • doPolling

      protected void doPolling()
      Does the default polling on DEFAULT_CHANNEL.

    • isPolling

      protected boolean isPolling()
      Returns whether we are polling or waiting for events.
      Returns:
      true for polling, false for events

    • uninstallPollTask

      protected void uninstallPollTask()
      Uninstall poll task.

    • disconnect

      public final void disconnect() throws IOException
      Disconnects the connector from the underlying machine/platform. Calls disconnectImpl(), uninstallPollTask() and ConnectorRegistry.unregisterConnector(Connector).
      Specified by:
      disconnect in interface Connector<O,I,CO,CI>
      Throws:
      IOException - in case that connecting fails

    • disconnectImpl

      protected abstract void disconnectImpl() throws IOException
      Called by disconnect().
      Throws:
      IOException - if problems occur while disconnecting

    • write

      public void write(CI data) throws IOException
      Description copied from interface: Connector
      Writes the given data to the underlying machine/platform.
      Specified by:
      write in interface Connector<O,I,CO,CI>
      Parameters:
      data - the data to send to stream
      Throws:
      IOException - in case that problems during the connection happens

    • writeImpl

      protected abstract void writeImpl(I data) throws IOException
      Does the actual writing to the underlying machine/platform. Can be left empty if MachineConnector.hasModel().
      Parameters:
      data - the data to be send
      Throws:
      IOException - if sending fails

    • received

      protected CO received(String channel, O data) throws IOException
      Call this if data was received.
      Parameters:
      channel - the channel data was received on, may be DEFAULT_CHANNEL.
      data - the received data, further processed if callback is not null
      Returns:
      returns the translated received data
      Throws:
      IOException - if receiving/translation fails

    • received

      protected CO received(String channel, O data, boolean notifyCallback) throws IOException
      Call this if data was received.
      Parameters:
      channel - the channel data was received on, may be DEFAULT_CHANNEL
      data - the received data, further processed if callback is not null
      notifyCallback - whether the callback shall be notified
      Returns:
      returns the translated received data
      Throws:
      IOException - if receiving/translation fails

    • notifyDataTimeDifference

      protected void notifyDataTimeDifference(int difference)
      Notifies this connector about a determined/changed time difference between the actual data received and the next data to be received. Not considered if not overridden!
      Parameters:
      difference - the time difference in ms

    • configureAdapter

      protected ProtocolAdapter<O,I,CO,CI> configureAdapter(ProtocolAdapter<O,I,CO,CI> adapter)
      Configures the adapter if needed.
      Parameters:
      adapter - the adapter
      Returns:
      adapter

    • getCachingStrategyCls

      public Class<? extends CachingStrategy> getCachingStrategyCls()
      Description copied from interface: Connector
      Returns the actual caching strategy class.
      Specified by:
      getCachingStrategyCls in interface Connector<O,I,CO,CI>
      Returns:
      the strategy class

    • getCachingStrategy

      protected CachingStrategy getCachingStrategy()
      Returns the actual caching strategy.
      Returns:
      the strategy

    • getInitCachingStrategyCls

      protected Class<? extends CachingStrategy> getInitCachingStrategyCls()
      Returns the initial caching strategy class.
      Returns:
      the caching strategy class, may be null for default

    • checkCache

      protected boolean checkCache(Object data)
      Checks the cache if configured. Override with true if not needed.
      Parameters:
      data - the data to send
      Returns:
      true for sending data, false for not sending data

    • setReceptionCallback

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

    • request

      public CO request(boolean notifyCallback) throws IOException
      Description copied from interface: Connector
      Explicitly requests reading data from the source. This is typically done by polling or events, but, in seldom cases, may be needed manually.
      Specified by:
      request in interface Connector<O,I,CO,CI>
      Parameters:
      notifyCallback - 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

    • request

      protected CO request(String channel, boolean notifyCallback) 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:
      channel - the channel to assign the received data to, may be DEFAULT_CHANNEL.
      notifyCallback - 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

    • trigger

      public void trigger()
      Description copied from interface: EventHandlingConnector
      Trigger the ingestion of a next data item.
      Specified by:
      trigger in interface EventHandlingConnector

    • trigger

      public void trigger(ConnectorTriggerQuery query)
      Description copied from interface: EventHandlingConnector
      Trigger the ingestion of a next data item.
      Specified by:
      trigger in interface EventHandlingConnector
      Parameters:
      query - specification what to ingest; capabilities depend on connector

    • read

      protected abstract O read() throws IOException
      Reads data from the underlying machine. Used for polling, but shall then be implemented by returning at least a dummy object so that the polling task can initiate a translation request and forward it to the callback. In particular, can be a dummy object or the actual changes in the model if MachineConnector.hasModel().
      Returns:
      the data from the machine, null for none, i.e., also no call to callback
      Throws:
      IOException - in case that reading fails

    • error

      protected abstract void error(String message, Throwable th)
      Logs an error.
      Parameters:
      message - the message to log
      th - information about the error

    • initializeModelAccess

      protected void initializeModelAccess() throws IOException
      Called to initialize the model access, e.g., to setup notifications. Shall be called only, when the connector is connected.
      Throws:
      IOException - in case the initialization fails, e.g., monitors cannot be set up

    • enableNotifications

      public void enableNotifications(boolean enableNotifications)
      Description copied from interface: Connector
      Enables/disables notifications/polling at all.
      Specified by:
      enableNotifications in interface Connector<O,I,CO,CI>
      Parameters:
      enableNotifications - enable or disable notifications

    • notificationsChanged

      public void notificationsChanged(boolean useNotifications)
      Called when the notifications setting has been changed in AbstractModelAccess.useNotifications(boolean).
      Specified by:
      notificationsChanged in interface AbstractModelAccess.NotificationChangedListener
      Parameters:
      useNotifications - the new value after changing

    • getProtocolInputType

      public Class<? extends I> getProtocolInputType()
      Description copied from interface: Connector
      Returns the input type to the protocol.
      Specified by:
      getProtocolInputType in interface Connector<O,I,CO,CI>
      Returns:
      the input type (may be null in case of generic types, but shall not be null)

    • getConnectorInputType

      public Class<? extends CI> getConnectorInputType()
      Description copied from interface: Connector
      Returns the input type from the IIP-Ecosphere platform.
      Specified by:
      getConnectorInputType in interface Connector<O,I,CO,CI>
      Returns:
      the input type (may be null in case of generic types, but shall not be null)

    • getProtocolOutputType

      public Class<? extends O> getProtocolOutputType()
      Description copied from interface: Connector
      Returns the output type of the protocol.
      Specified by:
      getProtocolOutputType in interface Connector<O,I,CO,CI>
      Returns:
      the output type (may be null in case of generic types, but shall not be null)

    • getConnectorOutputType

      public Class<? extends CO> getConnectorOutputType()
      Description copied from interface: Connector
      Returns the output type to the IIP-Ecosphere platform.
      Specified by:
      getConnectorOutputType in interface Connector<O,I,CO,CI>
      Returns:
      the output type (may be null in case of generic types, but shall not be null)

    • notifyReconfigured

      public void notifyReconfigured(String parameterName, String value)
      Description copied from interface: Connector
      Called when parameters of the containing service are changed.
      Specified by:
      notifyReconfigured in interface Connector<O,I,CO,CI>
      Parameters:
      parameterName - the parameter name
      value - the new value

    • setStorageValue

      public void setStorageValue(String key, Object value)
      Description copied from interface: EventHandlingConnector
      Sets intermediate information that can be read out by while transforming results by configured transformation functions.
      Specified by:
      setStorageValue in interface EventHandlingConnector
      Parameters:
      key - the key of the value to set
      value - the actual value

    • getStorageValue

      public Object getStorageValue(String key)
      Description copied from interface: EventHandlingConnector
      Returns intermediate information that may be useful while transforming the results by configured transformation functions.
      Specified by:
      getStorageValue in interface EventHandlingConnector
      Parameters:
      key - the key of the value to set
      Returns:
      the value, may be null

    • setDataTimeDifferenceProvider

      public void setDataTimeDifferenceProvider(DataTimeDifferenceProvider<CO> provider)
      Description copied from interface: Connector
      Defines the time difference provider. Depends on the connector implementation.
      Specified by:
      setDataTimeDifferenceProvider in interface Connector<O,I,CO,CI>
      Parameters:
      provider - the provider, may be null for none

    • setDataTimeDifference

      public void setDataTimeDifference(int difference)
      Description copied from interface: EventHandlingConnector
      Adjusts the simulated data time difference.
      Specified by:
      setDataTimeDifference in interface EventHandlingConnector
      Parameters:
      difference - the difference, negative for configured fixed default, 0 for none (handle with care)

    • setInstanceIdentification

      public void setInstanceIdentification(String identification)
      Description copied from interface: Connector
      Sets an instance identification for connector extensions.
      Specified by:
      setInstanceIdentification in interface Connector<O,I,CO,CI>
      Parameters:
      identification - the identification

    • getInstanceIdentification

      public String getInstanceIdentification()
      Description copied from interface: Connector
      Returns the instance identification for connector extensions.
      Specified by:
      getInstanceIdentification in interface Connector<O,I,CO,CI>
      Returns:
      the identification, set before by Connector.setInstanceIdentification(String)

    • dispose

      public void dispose()
      Description copied from interface: Connector
      Final cleanup when platform shuts down, e.g., for shared resources.
      Specified by:
      dispose in interface Connector<O,I,CO,CI>