SDN Controller Programming Guide

36
 A DIRECTOR may contribute to the formation of the associated PACKET_OUT message by
adding actions to it; DIRECTORs may also determine that the PACKET_OUT message is ready
to be sent back to the datapath, and can instruct the Sequencer to send it on its way.
 An OBSERVER passively monitors the PACKET_IN/PACKET_OUT interactions.
 Within each role, SPLs are processed in order of decreasing “altitude”. The altitude is specified
when the SPL registers with the controller. Between them, the role and altitude provide a
deterministic ordering of the “processing chain”.
 When a PACKET_IN message event occurs, the PACKET_IN is wrapped in a MessageContext
which provides the context for the packet being processed. The packet is also decoded to the
extent where the network protocols present in the packet are identified; this information is attached
to the context.
 The message context is passed from SPL to SPL (via the event() callback) in the predetermined
order, but only to those SPLs where at least one of the network protocols present in the packet is
also defined in the SPL’s “interest” set:
 The return value from an ADVISOR’s event() callback is ignored (but should be false to be
polite).
 The return value from a DIRECTOR’s event() callback should be true if it is determined that the
packet has been “handled” (i.e. the PACKET_OUT message is ready to send); false
otherwise.
 The return value from DIRECTORs and OBSERVERs downstream of the DIRECTOR that
“handled” the packet is ignored. (OBSERVERs should return false to be polite).
 Once a DIRECTOR returns true from their callback, the Sequencer will convert the mutable
PACKET_OUT message to its immutable form and attempt to send it back to the datapath. If an
error occurs during the send, this fact is recorded in the message context, and the DIRECTOR’s
errorEvent() callback is invoked.
 Note that every SPL that registers with the Sequencer is guaranteed to see every MessageContext
(subject to their ProtocolId “interest” set).
 Here is some sample code that shows how to register as an observer of DNS packets sent to the
controller in PACKET_IN messages:
private static final int OBS_ALTITUDE = 25;
private static final Set<ProtocolId>
OBS_INTEREST = EnumSet.of(ProtocolId.DNS);
private final MyObserver myObserver = new MyObserver();
private void register() {
cs.addPacketListener(myObserver, PacketListenerRole.OBSERVER,
OBS_ALTITUDE, OBS_INTEREST);
}
private static class MyObserver implements SequencedPacketListener {
@Override
public boolean event(MessageContext context) {
Dns dns = context.decodedPacket().get(ProtocolId.DNS);