Initial opendaylight infrastructure commit!!

[controller.git] / opendaylight / sal / api / src / main / java / org / opendaylight / controller / sal / packet / IListenDataPacket.java

diff --git a/opendaylight/sal/api/src/main/java/org/opendaylight/controller/sal/packet/IListenDataPacket.java b/opendaylight/sal/api/src/main/java/org/opendaylight/controller/sal/packet/IListenDataPacket.java
new file mode 100644 (file)
index 0000000..76e2a6f
--- /dev/null
+++ b/opendaylight/sal/api/src/main/java/org/opendaylight/controller/sal/packet/IListenDataPacket.java
@@ -0,0 +1,70 @@
+
+/*
+ * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+
+/**
+ * @file   IListenDataPacket.java
+ *
+ * @brief  Interface a component will need to implement and export as
+ * implemented interface in order to get data packet
+ *
+ * Interface a component will need to implement and export as
+ * implemented interface in order to get data packet
+ */
+
+package org.opendaylight.controller.sal.packet;
+
+/**
+ * Interface that all the components that want to receive a dataPacket
+ * need to implement. The interface by itself doesn't specify any
+ * filtering or sequencing mechanism, but the model supported by Data
+ * Packet Service is such that the packets can be processed in two
+ * ways:
+ * - Serial: When a Data Packet Listener gets a packet after another,
+ * this case is necessary when the subsequent handler needs some extra
+ * information that can only be provided by another Data Packet
+ * Service Handler. If the dependent service is missing, then the one
+ * with dependencies will not be invoked. In a serial
+ * processing, a plugin has the the power to prevent the packet to be
+ * seen but other in the chain, if the return result is CONSUMED, else
+ * the packet will go through all the elements in the chain.
+ * - Parallel: When a Data Packet Listener doesn't express any
+ * dependency then it will get a copy of the packet as anybody
+ * else. Practical example, let say we have 2 handlers, both didn't
+ * express any dependency then both will get a copy of any incoming
+ * packet and they cannot step over each other feet.
+ * The Processing model is choosen by the properties with which the
+ * service is registered in the OSGi service registry.
+ * The properties that will be looked at are:
+ * salListenerName: Unique identifier of the SAL Data Packet
+ * Listener
+ * salListenerDependency: A String containing the
+ * salListenerName that consitute a dependency for this Listener, for
+ * now ONLY a SINGLE dependency is supported
+ * salListenerFilter: A Match class to be used to match a DataPacket,
+ * processing either parallel or serial will ONLY continue if the
+ * incoming DataPacket match the filter. If no filter is provided, the
+ * handler is called for EVERY packet i.e. match All is implied!
+ */
+public interface IListenDataPacket {
+    /**
+     * Handler for receiving the packet. The application can signal
+     * back to SAL if the packet has been consumed or no. In case of
+     * packet consumed SAL will prevent to keep passing to subsequent
+     * listener in the serial chain, but for handlers without
+     * dependency things will keep going .
+     * The packet will received will have the IncomingNodeConnector
+     * set to understand where the packet is coming from
+     *
+     * @param inPkt Packet received
+     *
+     * @return An indication if the packet should still be processed
+     * or we should stop it.
+     */
+    PacketResult receiveDataPacket(RawPacket inPkt);
+}