Added a TrafficTreatment to the filtering objective to cover those

pipelines where the filtering action is accompanied by a corresponding
change to the permitted packet. Fixed Filtering Objective javadocs.

Change-Id: I7f3c1a1a3553c0fdbfe5e7e48c6426cde1602efd

@@ -18,6 +18,7 @@ package org.onosproject.net.flowobjective;
 import com.google.common.annotations.Beta;
 import com.google.common.collect.ImmutableList;
 import org.onosproject.core.ApplicationId;
+import org.onosproject.net.flow.TrafficTreatment;
 import org.onosproject.net.flow.criteria.Criteria;
 import org.onosproject.net.flow.criteria.Criterion;
 
@@ -46,6 +47,7 @@ public final class DefaultFilteringObjective implements FilteringObjective {
     private final int id;
     private final Operation op;
     private final Optional<ObjectiveContext> context;
+    private final TrafficTreatment meta;
 
     private DefaultFilteringObjective(Builder builder) {
         this.key = builder.key;
@@ -57,6 +59,7 @@ public final class DefaultFilteringObjective implements FilteringObjective {
         this.conditions = builder.conditions;
         this.op = builder.op;
         this.context = Optional.ofNullable(builder.context);
+        this.meta = builder.meta;
 
         this.id = Objects.hash(type, key, conditions, permanent,
                 timeout, appId, priority);
@@ -83,6 +86,12 @@ public final class DefaultFilteringObjective implements FilteringObjective {
     }
 
     @Override
+    public TrafficTreatment meta() {
+        return meta;
+    }
+
+
+    @Override
     public int priority() {
         return priority;
     }
@@ -135,6 +144,7 @@ public final class DefaultFilteringObjective implements FilteringObjective {
         private List<Criterion> conditions;
         private Operation op;
         private ObjectiveContext context;
+        private TrafficTreatment meta;
 
         @Override
         public Builder withKey(Criterion key) {
@@ -186,6 +196,12 @@ public final class DefaultFilteringObjective implements FilteringObjective {
         }
 
         @Override
+        public Builder setMeta(TrafficTreatment treatment) {
+            this.meta = treatment;
+            return this;
+        }
+
+        @Override
         public FilteringObjective add() {
             conditions = listBuilder.build();
             op = Operation.ADD;

@@ -17,49 +17,54 @@ package org.onosproject.net.flowobjective;
 
 import com.google.common.annotations.Beta;
 import org.onosproject.core.ApplicationId;
+import org.onosproject.net.flow.TrafficTreatment;
 import org.onosproject.net.flow.criteria.Criterion;
 
 import java.util.Collection;
 
 /**
  * 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.
+ * is made up of a key (typically a PortCriterion) mapped to a set of criteria.
+ * Using this information, a pipeline aware driver will decide how this objective
+ * should be mapped to the device specific pipeline-tables in order to satisfy the
+ * filtering condition. For example, consider the following PERMIT filtering
+ * objective:
+ * <p>
+ * portX -&gt; {MAC1, VLAN1}
+ * <p>
+ * The driver could decide to pass packets to the MAC table or VLAN or PORT
+ * tables to ensure that only those packets arriving with the correct dst MAC
+ * and VLAN ids from Port X are allowed into the pipeline.
+ * <p>
+ * Filtering objectives of type PERMIT allow packets that match the key:criteria
+ * to enter the pipeline. As a result, the implication is that packets that don't
+ * match are automatically denied (dropped).
+ * <p>
+ * Filtering objectives of type DENY, are used to deny packets that would
+ * otherwise be permitted and forwarded through the pipeline (ie. those packets
+ * that make it through the PERMIT filters).
  */
 @Beta
 public interface FilteringObjective extends Objective {
 
     enum Type {
         /**
-         * Enables the filtering condition.
+         * Permits packets that match the filtering condition to be processed
+         * by the rest of the pipeline. Automatically denies packets that don't
+         * match the criteria.
          */
         PERMIT,
 
         /**
-         * Disables the filtering condition.
+         * Denies packets that make it through the permit filters.
          */
         DENY
     }
 
     /**
-     * Obtain the key for this filter.
+     * Obtain the key for this filter. The filter may or may not require a key.
      *
-     * @return a criterion
+     * @return a criterion, which could be null if no key was provided.
      */
     Criterion key();
 
@@ -78,6 +83,16 @@ public interface FilteringObjective extends Objective {
     Collection<Criterion> conditions();
 
     /**
+     * Auxiliary optional information provided to the device-driver.Typically
+     * conveys information about changes (treatments) to packets that are
+     * permitted into the pipeline by the PERMIT filtering condition.
+     *
+     * @return a treatment on the packets that make it through the PERMIT filters.
+     *         Value may be null if no meta information is provided.
+     */
+    TrafficTreatment meta();
+
+    /**
      * Builder of Filtering objective entities.
      */
     interface Builder extends Objective.Builder {
@@ -113,11 +128,19 @@ public interface FilteringObjective extends Objective {
         Builder deny();
 
         /**
+         * Set meta information about this filtering condition set.
+         *
+         * @return a filtering builder
+         */
+        Builder setMeta(TrafficTreatment treatment);
+
+        /**
          * Assigns an application id.
          *
          * @param appId an application id
          * @return a filtering builder
          */
+        @Override
         Builder fromApp(ApplicationId appId);
 
         /**