org.onosproject.net.device

Interface DeviceHandshaker

All Superinterfaces:

Behaviour, DeviceConnect, HandlerBehaviour

@Beta
public interface DeviceHandshaker
extends DeviceConnect

Behavior to test device's reachability and change the mastership role on that device.

Method Summary

Modifier and Type	Method and Description
default void	addDeviceAgentListener(ProviderId providerId, DeviceAgentListener listener) Adds a device agent listener for the given provider ID.
MastershipRole	getRole() Returns the last known mastership role agreed by the device for this node.
boolean	isAvailable() Checks the availability of the device.
boolean	isReachable() Returns true if this node is presumed to be able to send messages and receive replies from the device.
CompletableFuture<Boolean>	probeAvailability() Similar to isAvailable() but allows probing the device over the network.
CompletableFuture<Boolean>	probeReachability() Similar to isReachable(), but performs probing of the device over the network.
default void	removeDeviceAgentListener(ProviderId providerId) Removes a device agent listener previously registered for the given provider ID.
default void	roleChanged(int preference, long term) Notifies the device of a mastership role change as decided by the core.
void	roleChanged(MastershipRole newRole) Notifies the device a mastership role change as decided by the core.

Methods inherited from interface org.onosproject.net.driver.DeviceConnect

connect, disconnect, hasConnection

Methods inherited from interface org.onosproject.net.driver.HandlerBehaviour

handler, setHandler

Methods inherited from interface org.onosproject.net.driver.Behaviour

data, setData

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

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

UnsupportedOperationException - if this method is not supported and probeAvailability() should be used instead.

probeAvailability

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

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:

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