Interface DeviceHandshaker

    • Method Detail

      • isReachable

        boolean isReachable()
        Returns true if this node is presumed to be able to send messages and receive replies from the device.

        The implementation should not make any attempt at actively probing the device over the network, as such it should not block execution. Instead, it should return a result based solely on internal state (e.g. socket state). If it returns true, then this node is expected to communicate with the server successfully. In other words, if any message would be sent to the device immediately after this method is called and returns true, then such message is expected, but NOT guaranteed, to reach the device. If false, it means communication with the device is unlikely to happen soon.

        Some implementations might require a connection to be created via DeviceConnect.connect() before checking for reachability. Similarly, after invoking DeviceConnect.disconnect(), this method might always return false.

        Returns:
        true if the device is deemed reachable, false otherwise
      • probeReachability

        java.util.concurrent.CompletableFuture<java.lang.Boolean> probeReachability()
        Similar to isReachable(), but performs probing of the device over the network. This method should be called if isReachable() returns false and the caller wants to be sure this is not a transient failure state by actively probing the device.
        Returns:
        completable future eventually true if device responded to probe, false otherwise
      • isAvailable

        boolean isAvailable()
        Checks the availability of the device. Availability denotes whether the device is reachable and able to perform its functions as expected (e.g., forward traffic). Similar to isReachable(), implementations are not allowed to probe the device over the network, but the result should be based solely on internal state.

        Implementation of this method is optional. If not supported, an exception should be thrown.

        Returns:
        true if the device is deemed available, false otherwise
        Throws:
        java.lang.UnsupportedOperationException - if this method is not supported and probeAvailability() should be used instead.
      • probeAvailability

        java.util.concurrent.CompletableFuture<java.lang.Boolean> probeAvailability()
        Similar to isAvailable() but allows probing the device over the network. Differently from isAvailable(), implementation of this method is mandatory.
        Returns:
        completable future eventually true if available, false otherwise
      • roleChanged

        void roleChanged​(MastershipRole newRole)
        Notifies the device a mastership role change as decided by the core. The implementation of this method should trigger a DeviceAgentEvent signaling the mastership role accepted by the device.
        Parameters:
        newRole - new mastership role
        Throws:
        java.lang.UnsupportedOperationException - if the device does not support mastership handling
      • roleChanged

        default void roleChanged​(int preference,
                                 long term)
        Notifies the device of a mastership role change as decided by the core. Differently from roleChanged(MastershipRole), the role is described by the given preference value, where preference = 0 signifies MastershipRole.MASTER role and preference > 0 signifies MastershipRole.STANDBY. Smaller preference values indicates higher mastership priority for different nodes.

        This method does not permit notifying role MastershipRole.NONE, in which case roleChanged(MastershipRole) should be used instead.

        Term is a monotonically increasing number, increased by one every time a new master is elected.

        The implementation of this method should trigger a DeviceAgentEvent signaling the mastership role accepted by the device.

        Parameters:
        preference - preference value, where 0 signifies MastershipRole.MASTER and all other values MastershipRole.STANDBY
        term - term number
        Throws:
        java.lang.UnsupportedOperationException - if the device does not support mastership handling, or if it does not support setting preference-based mastership, and roleChanged(MastershipRole) should be used instead
      • getRole

        MastershipRole getRole()
        Returns the last known mastership role agreed by the device for this node.
        Returns:
        mastership role
      • addDeviceAgentListener

        default void addDeviceAgentListener​(ProviderId providerId,
                                            DeviceAgentListener listener)
        Adds a device agent listener for the given provider ID.
        Parameters:
        providerId - provider ID
        listener - device agent listener
      • removeDeviceAgentListener

        default void removeDeviceAgentListener​(ProviderId providerId)
        Removes a device agent listener previously registered for the given provider ID.
        Parameters:
        providerId - provider ID