Implemented global packet-out functionality in the PacketModule.
Updated with javadoc for the interfaces, and fixes to bugs pointed out by
Pavlin and Yuta regarding the implementation of calculateOutPorts in
BroadcastPacketOutNotification.
Change-Id: I6174d27877972cf437955ef8d82e9a02b36d0b5f
diff --git a/src/main/java/net/onrc/onos/api/packet/IPacketService.java b/src/main/java/net/onrc/onos/api/packet/IPacketService.java
index eaa372d..4321a11 100644
--- a/src/main/java/net/onrc/onos/api/packet/IPacketService.java
+++ b/src/main/java/net/onrc/onos/api/packet/IPacketService.java
@@ -4,18 +4,64 @@
import net.floodlightcontroller.core.module.IFloodlightService;
import net.onrc.onos.core.packet.Ethernet;
-import net.onrc.onos.core.topology.Port;
+import net.onrc.onos.core.util.SwitchPort;
+/**
+ * Provides packet services to ONOS applications. This includes both the
+ * ability to receive packets from the network, and to send packets out
+ * ports in the network. The packet service provides a global context for
+ * packet operations; an application can send/receive packets to/from any
+ * port in the network.
+ * <p/>
+ * NOTE: Global packet-ins are currently not implemented. An application can
+ * subscribe to local packet-ins only at the moment.
+ */
public interface IPacketService extends IFloodlightService {
- // packet ins
+ /**
+ * Register to listen for packet-in events.
+ *
+ * @param listener the function to call when a packet-in event is received
+ */
public void registerPacketListener(IPacketListener listener);
- // packet outs
- public void sendPacket(Port port, Ethernet eth);
+ // TODO investigate using Port objects again when Ports can be safely
+ // passed around.
+ /**
+ * Send a packet out a specific port in the network.
+ *
+ * @param switchPort the port to send the packet out
+ * @param eth the packet to send
+ */
+ public void sendPacket(SwitchPort switchPort, Ethernet eth);
- public void sendPacket(List<Port> ports, Ethernet eth);
+ /**
+ * Send a packet out multiple ports in the network.
+ *
+ * @param switchPorts a list of ports to send the packet out
+ * @param eth the packet to send
+ */
+ public void sendPacket(List<SwitchPort> switchPorts, Ethernet eth);
+ /**
+ * Broadcast the packet out all edge ports in the network. An edge port is
+ * defined as any port that doesn't have a link to another switch.
+ *
+ * @param eth the packet to broadcast
+ */
public void broadcastPacket(Ethernet eth);
- public void broadcastPacket(Ethernet eth, Port inPort);
+ /**
+ * Broadcast the packet out all edge ports in the network, except for the
+ * specified excluded port. An edge port is defined as any port that
+ * doesn't have a link to another switch.
+ * <p/>
+ * This is useful for packets that are received from a host in the
+ * dataplane, where we want to broadcast the packet to everyone apart from
+ * the host that sent it.
+ *
+ * @param eth the packet to broadcast
+ * @param inSwitchPort the exception port that the packet is not
+ * broadcast out
+ */
+ public void broadcastPacket(Ethernet eth, SwitchPort inSwitchPort);
}