Package de.iip_ecosphere.platform.connectors

Class AbstractConnector<O,​I,​CO,​CI>

    • Constructor Detail

      • 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:
        java.lang.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:
        java.lang.IllegalArgumentException - if adapter is null or empty or adapters are null

    • Method Detail

      • 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 javax.net.ssl.SSLContext createTlsContext​(ConnectorParameter params)
                                             throws java.io.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:
        java.io.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

      • connectImpl

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

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

      • disconnectImpl

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

      • write

        public void write​(CI data)
           throws java.io.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:
        java.io.IOException - in case that problems during the connection happens

      • writeImpl

        protected abstract void writeImpl​(I data)
                           throws java.io.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:
        java.io.IOException - if sending fails

      • received

        protected CO received​(java.lang.String channel,
                      O data)
               throws java.io.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:
        java.io.IOException - if receiving/translation fails

      • received

        protected CO received​(java.lang.String channel,
                      O data,
                      boolean notifyCallback)
               throws java.io.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:
        java.io.IOException - if receiving/translation fails

      • getCachingStrategy

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

      • getInitCachingStrategyCls

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

      • checkCache

        protected boolean checkCache​(java.lang.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 java.io.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:
        java.io.IOException - in case that problems during registering the callback (e.g., during subscription) happens

      • request

        public CO request​(boolean notifyCallback)
           throws java.io.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:
        java.io.IOException - in case that reading fails

      • request

        protected CO request​(java.lang.String channel,
                     boolean notifyCallback)
              throws java.io.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:
        java.io.IOException - in case that reading fails

      • read

        protected abstract O read()
                   throws java.io.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:
        java.io.IOException - in case that reading fails

      • error

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

      • initializeModelAccess

        protected void initializeModelAccess()
                              throws java.io.IOException
        Called to initialize the model access, e.g., to setup notifications. Shall be called only, when the connector is connected.
        Throws:
        java.io.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

      • getProtocolInputType

        public java.lang.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 java.lang.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 java.lang.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 java.lang.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​(java.lang.String parameterName,
                               java.lang.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