initial stab at javadoc for objectives

Change-Id: Ib36b50b6e9dd8c4a11aa9f06318ad567b28ae0f2

@@ -22,10 +22,24 @@ import org.onosproject.net.flow.criteria.Criterion;
 import java.util.Collection;
 
 /**
- * Represents a filtering flow objective. Each filter is mapping
- * from a criterion to a collection of criteria. The mapping will
- * be used by a device driver to construct the actual flow rules to
- * be installed on the device.
+ * Represents a filtering flow objective. Each filtering flow objective
+ * is made up of a key (criterion) to a set of criteria. Using this information
+ * a pipeline aware driver will decide how this objective should be mapped
+ * to the specific device pipeline. For example, consider the following
+ * filtering objective:
+ *
+ * portX -> {MAC1, IP1, MAC2}
+ *
+ * The driver could decide to pass L3 packet to the L3 table and L2 packets to
+ * the L2 table for packets arriving on portX.
+ *
+ * Filtering objectives do not only represent what should be permitted into the
+ * pipeline but can also be used to deny or drop unwanted packets by specifying
+ * the appropriate type of filtering objective. It is also important to note
+ * that submitting a filtering objective does not necessarily result in rules
+ * programmed at the switch, the driver is free to decide when these rules are
+ * programmed. For example, a filtering rule may only be programmed once a
+ * corresponding forwarding objective has been received.
  */
 @Beta
 public interface FilteringObjective extends Objective {

@@ -22,7 +22,20 @@ import org.onosproject.net.flow.TrafficTreatment;
 /**
  * Represents a description of which types of traffic need to
  * be forwarded through the device. A forwarding objective may
- * in multiple rules at the device.
+ * result in multiple rules at the device. There are two main types
+ * of forwarding objectives:
+ *
+ *  - Versatile
+ *  - Specific
+ *
+ * A versatile forwarding objective represents a composite rule that matches
+ * two or more header fields. The use of versatile usually indicates that this
+ * rule should be inserted in its entirety into the ACL table. Although,
+ * drivers for some devices are free to implement this differently.
+ *
+ * A specific forwarding objective represents a specific rule matching one or
+ * more header fields. The installation of this rule may result in several rules
+ * at the device. For example, one per table type.
  */
 @Beta
 public interface ForwardingObjective extends Objective {

@@ -24,7 +24,21 @@ import java.util.Collection;
 /**
  * Represents a nexthop which will be translated by a driver
  * into the appropriate group or actions needed to implement
- * the function.
+ * the egress function.
+ *
+ * A next objective is made up of a collection of traffic treatements
+ * associated with a type. These types are:
+ *
+ * - Hashed
+ * - Broadcast
+ * - Failover
+ * - Simple
+ *
+ * These types will indicate to the driver what the intended behaviour is.
+ * For example, a broadcast next objective with a collection of output
+ * treatments will indicate to a driver that all output actions are expected
+ * to be executed simultaneously. The driver is then free to implement this
+ * as a group or a simple action list.
  */
 @Beta
 public interface NextObjective extends Objective {