ONOS-885: Group store interface definition and in-memory store implementation

Change-Id: I1125fbc23f1e58bcb8aaf5f67c02da610fa7ef25

ONOS-885: Group store interface definition and in-memory store implementation

Change-Id: Id3794bed63785e10ed86c0b5d90bf875d127224c

+/*
+ * Copyright 2015 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.net.group;
+
+import static org.slf4j.LoggerFactory.getLogger;
+
+import org.onosproject.core.GroupId;
+import org.slf4j.Logger;
+
+/**
+ * ONOS implementation of default group that is stored in the system.
+ */
+public class DefaultGroup extends DefaultGroupDescription
+    implements Group, StoredGroupEntry {
+
+    private final Logger log = getLogger(getClass());
+
+    private GroupState state;
+    private long life;
+    private long packets;
+    private long bytes;
+    private GroupId id;
+
+    /**
+     * Default group object constructor with the parameters.
+     *
+     * @param id group identifier
+     * @param groupDesc group description parameters
+     */
+    public DefaultGroup(GroupId id, GroupDescription groupDesc) {
+        super(groupDesc);
+        this.id = id;
+        this.state = GroupState.PENDING_ADD;
+        this.life = 0;
+        this.packets = 0;
+        this.bytes = 0;
+    }
+
+    /**
+     * Returns group identifier associated with a group object.
+     *
+     * @return GroupId Group Identifier
+     */
+    @Override
+    public GroupId id() {
+        return this.id;
+    }
+
+    /**
+     * Returns current state of a group object.
+     *
+     * @return GroupState Group State
+     */
+    @Override
+    public GroupState state() {
+        return this.state;
+    }
+
+    /**
+     * Returns the number of milliseconds this group has been alive.
+     *
+     * @return number of millis
+     */
+    @Override
+    public long life() {
+        return this.life;
+    }
+
+    /**
+     * Returns the number of packets processed by this group.
+     *
+     * @return number of packets
+     */
+    @Override
+    public long packets() {
+        return this.packets;
+    }
+
+    /**
+     * Returns the number of bytes processed by this group.
+     *
+     * @return number of bytes
+     */
+    @Override
+    public long bytes() {
+        return this.bytes;
+    }
+
+    /**
+     * Sets the new state for this entry.
+     *
+     * @param newState new group entry state.
+     */
+    @Override
+    public void setState(Group.GroupState newState) {
+        this.state = newState;
+    }
+
+    /**
+     * Sets how long this entry has been entered in the system.
+     *
+     * @param life epoch time
+     */
+    @Override
+    public void setLife(long life) {
+        this.life = life;
+    }
+
+    /**
+     * Sets number of packets processed by this group entry.
+     *
+     * @param packets a long value
+     */
+    @Override
+    public void setPackets(long packets) {
+        this.packets = packets;
+    }
+
+    /**
+     * Sets number of bytes processed by this group entry.
+     *
+     * @param bytes a long value
+     */
+    @Override
+    public void setBytes(long bytes) {
+        this.bytes = bytes;
+    }
+
+}

@@ -15,12 +15,12 @@
  */
  */
 package org.onosproject.net.group;
 package org.onosproject.net.group;
 
 
-import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
 
 
+import org.onosproject.core.GroupId;
 import org.onosproject.net.PortNumber;
 import org.onosproject.net.PortNumber;
 import org.onosproject.net.flow.TrafficTreatment;
 import org.onosproject.net.flow.TrafficTreatment;
-import org.onosproject.core.GroupId;
 
 
 /**
 /**
  * Group bucket implementation. A group bucket is collection of
  * Group bucket implementation. A group bucket is collection of
@@ -65,7 +65,6 @@ public final class DefaultGroupBucket implements GroupBucket {
      * Creates indirect group bucket.
      * Creates indirect group bucket.
      *
      *
      * @param treatment traffic treatment associated with group bucket
      * @param treatment traffic treatment associated with group bucket
-     *
      * @return indirect group bucket object
      * @return indirect group bucket object
      */
      */
     public static GroupBucket createIndirectGroupBucket(
     public static GroupBucket createIndirectGroupBucket(
@@ -81,7 +80,6 @@ public final class DefaultGroupBucket implements GroupBucket {
      * Creates select group bucket with weight as 1.
      * Creates select group bucket with weight as 1.
      *
      *
      * @param treatment traffic treatment associated with group bucket
      * @param treatment traffic treatment associated with group bucket
-     *
      * @return select group bucket object
      * @return select group bucket object
      */
      */
     public static GroupBucket createSelectGroupBucket(
     public static GroupBucket createSelectGroupBucket(
@@ -98,7 +96,6 @@ public final class DefaultGroupBucket implements GroupBucket {
      *
      *
      * @param treatment traffic treatment associated with group bucket
      * @param treatment traffic treatment associated with group bucket
      * @param weight weight associated with group bucket
      * @param weight weight associated with group bucket
-     *
      * @return select group bucket object
      * @return select group bucket object
      */
      */
     public static GroupBucket createSelectGroupBucket(
     public static GroupBucket createSelectGroupBucket(
@@ -121,7 +118,6 @@ public final class DefaultGroupBucket implements GroupBucket {
      * @param treatment traffic treatment associated with group bucket
      * @param treatment traffic treatment associated with group bucket
      * @param watchPort port that determines the liveness of group bucket
      * @param watchPort port that determines the liveness of group bucket
      * @param watchGroup group that determines the liveness of group bucket
      * @param watchGroup group that determines the liveness of group bucket
-     *
      * @return failover group bucket object
      * @return failover group bucket object
      */
      */
     public static GroupBucket createFailoverGroupBucket(
     public static GroupBucket createFailoverGroupBucket(
@@ -142,7 +138,7 @@ public final class DefaultGroupBucket implements GroupBucket {
     }
     }
 
 
     /**
     /**
-     * Return list of Traffic instructions that are part of the bucket.
+     * Returns list of Traffic instructions that are part of the bucket.
      *
      *
      * @return TrafficTreatment Traffic instruction list
      * @return TrafficTreatment Traffic instruction list
      */
      */
@@ -152,7 +148,7 @@ public final class DefaultGroupBucket implements GroupBucket {
     }
     }
 
 
     /**
     /**
-     * Return weight of select group bucket.
+     * Returns weight of select group bucket.
      *
      *
      * @return short weight associated with a bucket
      * @return short weight associated with a bucket
      */
      */
@@ -162,7 +158,7 @@ public final class DefaultGroupBucket implements GroupBucket {
     }
     }
 
 
     /**
     /**
-     * Return port number used for liveness detection for a
+     * Returns port number used for liveness detection for a
      * failover bucket.
      * failover bucket.
      *
      *
      * @return PortNumber port number used for liveness detection
      * @return PortNumber port number used for liveness detection
@@ -173,7 +169,7 @@ public final class DefaultGroupBucket implements GroupBucket {
     }
     }
 
 
     /**
     /**
-     * Return group identifier used for liveness detection for a
+     * Returns group identifier used for liveness detection for a
      * failover bucket.
      * failover bucket.
      *
      *
      * @return GroupId group identifier to be used for liveness detection
      * @return GroupId group identifier to be used for liveness detection

@@ -20,6 +20,9 @@ import static com.google.common.base.Preconditions.checkNotNull;
 import org.onosproject.core.ApplicationId;
 import org.onosproject.core.ApplicationId;
 import org.onosproject.net.DeviceId;
 import org.onosproject.net.DeviceId;
 
 
+/**
+ * Default implementation of group description interface.
+ */
 public class DefaultGroupDescription implements GroupDescription {
 public class DefaultGroupDescription implements GroupDescription {
     private final GroupDescription.Type type;
     private final GroupDescription.Type type;
     private final GroupBuckets buckets;
     private final GroupBuckets buckets;
@@ -28,15 +31,15 @@ public class DefaultGroupDescription implements GroupDescription {
     private final DeviceId deviceId;
     private final DeviceId deviceId;
 
 
     /**
     /**
+     * Constructor to be used by north bound applications.
+     * NOTE: The caller of this subsystem MUST ensure the appCookie
+     * provided in this API is immutable
      *
      *
      * @param deviceId device identifier
      * @param deviceId device identifier
      * @param type type of the group
      * @param type type of the group
      * @param buckets immutable list of group bucket
      * @param buckets immutable list of group bucket
      * @param appCookie immutable application cookie to be associated with the group
      * @param appCookie immutable application cookie to be associated with the group
      * @param appId application id
      * @param appId application id
-     *
-     * NOTE: The caller of this subsystem MUST ensure the appCookie
-     * provided in this API is immutable
      */
      */
     public DefaultGroupDescription(DeviceId deviceId,
     public DefaultGroupDescription(DeviceId deviceId,
                                    GroupDescription.Type type,
                                    GroupDescription.Type type,
@@ -51,7 +54,22 @@ public class DefaultGroupDescription implements GroupDescription {
     }
     }
 
 
     /**
     /**
-     * Return type of a group object.
+     * Constructor to be used by group subsystem internal components.
+     * Creates group description object from another object of same type.
+     *
+     * @param groupDesc group description object
+     *
+     */
+    public DefaultGroupDescription(GroupDescription groupDesc) {
+        this.type = checkNotNull(groupDesc.type());
+        this.deviceId = checkNotNull(groupDesc.deviceId());
+        this.buckets = checkNotNull(groupDesc.buckets());
+        this.appCookie = checkNotNull(groupDesc.appCookie());
+        this.appId = checkNotNull(groupDesc.appId());
+    }
+
+    /**
+     * Returns type of a group object.
      *
      *
      * @return GroupType group type
      * @return GroupType group type
      */
      */
@@ -61,7 +79,7 @@ public class DefaultGroupDescription implements GroupDescription {
     }
     }
 
 
     /**
     /**
-     * Return device identifier on which this group object is created.
+     * Returns device identifier on which this group object is created.
      *
      *
      * @return DeviceId device identifier
      * @return DeviceId device identifier
      */
      */
@@ -71,7 +89,7 @@ public class DefaultGroupDescription implements GroupDescription {
     }
     }
 
 
     /**
     /**
-     * Return application identifier that has created this group object.
+     * Returns application identifier that has created this group object.
      *
      *
      * @return ApplicationId application identifier
      * @return ApplicationId application identifier
      */
      */
@@ -81,7 +99,7 @@ public class DefaultGroupDescription implements GroupDescription {
     }
     }
 
 
     /**
     /**
-     * Return application cookie associated with a group object.
+     * Returns application cookie associated with a group object.
      *
      *
      * @return GroupKey application cookie
      * @return GroupKey application cookie
      */
      */
@@ -91,7 +109,7 @@ public class DefaultGroupDescription implements GroupDescription {
     }
     }
 
 
     /**
     /**
-     * Return group buckets of a group.
+     * Returns group buckets of a group.
      *
      *
      * @return GroupBuckets immutable list of group bucket
      * @return GroupBuckets immutable list of group bucket
      */
      */

@@ -23,35 +23,43 @@ import org.onosproject.core.GroupId;
 public interface Group extends GroupDescription {
 public interface Group extends GroupDescription {
     /**
     /**
      * State of the group object in ONOS.
      * State of the group object in ONOS.
-     * PENDING_ADD: group create request is processed by ONOS and
-     * not yet received the confirmation from data plane
-     * ADDED: group is created in the data plane
-     * PENDING_UPDATE: group update request is processed by ONOS and
-     * not received the confirmation from data plane post which state
-     * moves to ADDED state
-     * PENDING_DELETE: group delete request is processed by ONOS and
-     * not received the confirmation from data plane
      */
      */
     public enum GroupState {
     public enum GroupState {
+        /**
+         * Group create request is processed by ONOS and not yet
+         * received the confirmation from data plane.
+         */
         PENDING_ADD,
         PENDING_ADD,
+        /**
+         * Group is created in the data plane.
+         */
         ADDED,
         ADDED,
+        /**
+         * Group update request is processed by ONOS and not
+         * received the confirmation from data plane post which
+         * state moves to ADDED state.
+         */
         PENDING_UPDATE,
         PENDING_UPDATE,
+        /**
+         * Group delete request is processed by ONOS and not
+         * received the confirmation from data plane.
+         */
         PENDING_DELETE
         PENDING_DELETE
     }
     }
 
 
     /**
     /**
-     * Return group identifier associated with a group object.
+     * Returns group identifier associated with a group object.
      *
      *
      * @return GroupId Group Identifier
      * @return GroupId Group Identifier
      */
      */
-    public GroupId id();
+    GroupId id();
 
 
     /**
     /**
-     * Return current state of a group object.
+     * Returns current state of a group object.
      *
      *
      * @return GroupState Group State
      * @return GroupState Group State
      */
      */
-    public GroupState state();
+    GroupState state();
 
 
     /**
     /**
      * Returns the number of milliseconds this group has been alive.
      * Returns the number of milliseconds this group has been alive.

@@ -15,11 +15,12 @@
  */
  */
 package org.onosproject.net.group;
 package org.onosproject.net.group;
 
 
+import org.onosproject.core.GroupId;
 import org.onosproject.net.PortNumber;
 import org.onosproject.net.PortNumber;
 import org.onosproject.net.flow.TrafficTreatment;
 import org.onosproject.net.flow.TrafficTreatment;
-import org.onosproject.core.GroupId;
 
 
-/* Group Bucket definition. A default group Bucket is collection of
+/**
+ * Group Bucket definition. A default group Bucket is collection of
  * Instructions that can be performed on a traffic flow. A failover
  * Instructions that can be performed on a traffic flow. A failover
  * group bucket is associated with a specific port or group that
  * group bucket is associated with a specific port or group that
  * controls its liveness. A select group bucket contains optional
  * controls its liveness. A select group bucket contains optional
@@ -27,28 +28,28 @@ import org.onosproject.core.GroupId;
  */
  */
 public interface GroupBucket {
 public interface GroupBucket {
     /**
     /**
-     * Return group type of the bucket.
+     * Returns group type of the bucket.
      *
      *
      * @return GroupType group type
      * @return GroupType group type
      */
      */
     public GroupDescription.Type type();
     public GroupDescription.Type type();
 
 
     /**
     /**
-     * Return list of Traffic instructions that are part of the bucket.
+     * Returns list of Traffic instructions that are part of the bucket.
      *
      *
      * @return TrafficTreatment traffic instruction list
      * @return TrafficTreatment traffic instruction list
      */
      */
     public TrafficTreatment treatment();
     public TrafficTreatment treatment();
 
 
     /**
     /**
-     * Return weight of select group bucket.
+     * Returns weight of select group bucket.
      *
      *
      * @return short weight associated with a bucket
      * @return short weight associated with a bucket
      */
      */
     public short weight();
     public short weight();
 
 
     /**
     /**
-     * Return port number used for liveness detection for a
+     * Returns port number used for liveness detection for a
      * failover bucket.
      * failover bucket.
      *
      *
      * @return PortNumber port number used for liveness detection
      * @return PortNumber port number used for liveness detection
@@ -56,7 +57,7 @@ public interface GroupBucket {
     public PortNumber watchPort();
     public PortNumber watchPort();
 
 
     /**
     /**
-     * Return group identifier used for liveness detection for a
+     * Returns group identifier used for liveness detection for a
      * failover bucket.
      * failover bucket.
      *
      *
      * @return GroupId group identifier to be used for liveness detection
      * @return GroupId group identifier to be used for liveness detection

@@ -15,20 +15,21 @@
  */
  */
 package org.onosproject.net.group;
 package org.onosproject.net.group;
 
 
-/* Generic group bucket entry representation that is stored in a
+/**
+ * Generic group bucket entry representation that is stored in a
  * group object. A group bucket entry provides additional info of
  * group object. A group bucket entry provides additional info of
  * group bucket like statistics...etc
  * group bucket like statistics...etc
  */
  */
 public interface GroupBucketEntry extends GroupBucket {
 public interface GroupBucketEntry extends GroupBucket {
     /**
     /**
-     * Return Number of packets processed by bucket.
+     * Returns Number of packets processed by bucket.
      *
      *
      * @return long
      * @return long
      */
      */
     public long packets();
     public long packets();
 
 
     /**
     /**
-     * Return Number of bytes processed by bucket.
+     * Returns Number of bytes processed by bucket.
      *
      *
      * @return long
      * @return long
      */
      */

@@ -19,9 +19,11 @@ import static com.google.common.base.Preconditions.checkNotNull;
 
 
 import java.util.List;
 import java.util.List;
 
 
-
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableList;
 
 
+/**
+ * Immutable collection of group bucket.
+ */
 public final class GroupBuckets {
 public final class GroupBuckets {
     private final List<GroupBucket> buckets;
     private final List<GroupBucket> buckets;
 
 
@@ -35,7 +37,7 @@ public final class GroupBuckets {
     }
     }
 
 
     /**
     /**
-     * Immutable list of group buckets.
+     * Returns immutable list of group buckets.
      *
      *
      * @return list of group bucket
      * @return list of group bucket
      */
      */

@@ -47,35 +47,35 @@ public interface GroupDescription {
     }
     }
 
 
     /**
     /**
-     * Return type of a group object.
+     * Returns type of a group object.
      *
      *
      * @return GroupType group type
      * @return GroupType group type
      */
      */
     public Type type();
     public Type type();
 
 
     /**
     /**
-     * Return device identifier on which this group object is created.
+     * Returns device identifier on which this group object is created.
      *
      *
      * @return DeviceId device identifier
      * @return DeviceId device identifier
      */
      */
     public DeviceId deviceId();
     public DeviceId deviceId();
 
 
     /**
     /**
-     * Return application identifier that has created this group object.
+     * Returns application identifier that has created this group object.
      *
      *
      * @return ApplicationId application identifier
      * @return ApplicationId application identifier
      */
      */
     public ApplicationId appId();
     public ApplicationId appId();
 
 
     /**
     /**
-     * Return application cookie associated with a group object.
+     * Returns application cookie associated with a group object.
      *
      *
      * @return GroupKey application cookie
      * @return GroupKey application cookie
      */
      */
     public GroupKey appCookie();
     public GroupKey appCookie();
 
 
     /**
     /**
-     * Return group buckets of a group.
+     * Returns group buckets of a group.
      *
      *
      * @return GroupBuckets immutable list of group bucket
      * @return GroupBuckets immutable list of group bucket
      */
      */

@@ -18,7 +18,7 @@ package org.onosproject.net.group;
 import org.onosproject.event.AbstractEvent;
 import org.onosproject.event.AbstractEvent;
 
 
 /**
 /**
- * Describes flow rule event.
+ * Describes group events.
  */
  */
 public class GroupEvent extends AbstractEvent<GroupEvent.Type, Group> {
 public class GroupEvent extends AbstractEvent<GroupEvent.Type, Group> {
 
 
@@ -48,6 +48,10 @@ public class GroupEvent extends AbstractEvent<GroupEvent.Type, Group> {
          */
          */
         GROUP_ADD_REQUESTED,
         GROUP_ADD_REQUESTED,
         /*
         /*
+         * Signifies that a request to update Group has been added to the store.
+         */
+        GROUP_UPDATE_REQUESTED,
+        /*
          * Signifies that a request to delete Group has been added to the store.
          * Signifies that a request to delete Group has been added to the store.
          */
          */
         GROUP_REMOVE_REQUESTED,
         GROUP_REMOVE_REQUESTED,

@@ -15,8 +15,9 @@
  */
  */
 package org.onosproject.net.group;
 package org.onosproject.net.group;
 
 
-/* Representation of generalized Key that would be used to store
- * groups in <Key, Value> store. Implementation of this interface
+/**
+ * Representation of generalized Key that would be used to store
+ * groups in &lt; Key, Value &gt; store. Implementation of this interface
  * MUST override "equals()" and "hashcode()" methods.
  * MUST override "equals()" and "hashcode()" methods.
  */
  */
 public interface GroupKey  {
 public interface GroupKey  {

@@ -19,6 +19,11 @@ import static com.google.common.base.Preconditions.checkNotNull;
 
 
 import org.onosproject.core.GroupId;
 import org.onosproject.core.GroupId;
 
 
+/**
+ * Group operation definition to be used between core and provider
+ * layers of group subsystem.
+ *
+ */
 public final class GroupOperation {
 public final class GroupOperation {
     private final Type opType;
     private final Type opType;
     private final GroupId groupId;
     private final GroupId groupId;
@@ -64,7 +69,6 @@ public final class GroupOperation {
      * @param groupId group Identifier
      * @param groupId group Identifier
      * @param groupType type of the group
      * @param groupType type of the group
      * @param buckets immutable list of group buckets to be part of group
      * @param buckets immutable list of group buckets to be part of group
-     *
      * @return add group operation object
      * @return add group operation object
      */
      */
     public static GroupOperation createAddGroupOperation(GroupId groupId,
     public static GroupOperation createAddGroupOperation(GroupId groupId,
@@ -80,7 +84,6 @@ public final class GroupOperation {
      * @param groupId group Identifier
      * @param groupId group Identifier
      * @param groupType type of the group
      * @param groupType type of the group
      * @param buckets immutable list of group buckets to be part of group
      * @param buckets immutable list of group buckets to be part of group
-     *
      * @return modify group operation object
      * @return modify group operation object
      */
      */
     public static GroupOperation createModifyGroupOperation(GroupId groupId,
     public static GroupOperation createModifyGroupOperation(GroupId groupId,
@@ -96,7 +99,6 @@ public final class GroupOperation {
      *
      *
      * @param groupId group Identifier
      * @param groupId group Identifier
      * @param groupType type of the group
      * @param groupType type of the group
-     *
      * @return delete group operation object
      * @return delete group operation object
      */
      */
     public static GroupOperation createDeleteGroupOperation(GroupId groupId,
     public static GroupOperation createDeleteGroupOperation(GroupId groupId,
@@ -106,7 +108,7 @@ public final class GroupOperation {
     }
     }
 
 
     /**
     /**
-     * Return group operation type.
+     * Returns group operation type.
      *
      *
      * @return GroupOpType group operation type
      * @return GroupOpType group operation type
      */
      */
@@ -115,7 +117,7 @@ public final class GroupOperation {
     }
     }
 
 
     /**
     /**
-     * Return group identifier attribute of the operation.
+     * Returns group identifier attribute of the operation.
      *
      *
      * @return GroupId group identifier
      * @return GroupId group identifier
      */
      */
@@ -124,7 +126,7 @@ public final class GroupOperation {
     }
     }
 
 
     /**
     /**
-     * Return group type attribute of the operation.
+     * Returns group type attribute of the operation.
      *
      *
      * @return GroupType group type
      * @return GroupType group type
      */
      */
@@ -133,7 +135,7 @@ public final class GroupOperation {
     }
     }
 
 
     /**
     /**
-     * Return group buckets associated with the operation.
+     * Returns group buckets associated with the operation.
      *
      *
      * @return GroupBuckets group buckets
      * @return GroupBuckets group buckets
      */
      */

@@ -19,9 +19,13 @@ import static com.google.common.base.Preconditions.checkNotNull;
 
 
 import java.util.List;
 import java.util.List;
 
 
-
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableList;
 
 
+/**
+ * Immutable collection of group operation to be used between
+ * core and provider layers of group subsystem.
+ *
+ */
 public final class GroupOperations {
 public final class GroupOperations {
     private final List<GroupOperation> operations;
     private final List<GroupOperation> operations;
 
 
@@ -35,7 +39,7 @@ public final class GroupOperations {
     }
     }
 
 
     /**
     /**
-     * Immutable list of group operation.
+     * Returns immutable list of group operation.
      *
      *
      * @return list of group operation
      * @return list of group operation
      */
      */

@@ -19,12 +19,12 @@ import org.onosproject.net.DeviceId;
 import org.onosproject.net.provider.Provider;
 import org.onosproject.net.provider.Provider;
 
 
 /**
 /**
- * Abstraction of a flow rule provider.
+ * Abstraction of group provider.
  */
  */
 public interface GroupProvider extends Provider {
 public interface GroupProvider extends Provider {
 
 
     /**
     /**
-     * Perform a group operation in the specified device with the
+     * Performs a batch of group operation in the specified device with the
      * specified parameters.
      * specified parameters.
      *
      *
      * @param deviceId device identifier on which the batch of group
      * @param deviceId device identifier on which the batch of group

@@ -26,6 +26,11 @@ import org.onosproject.net.provider.ProviderService;
  */
  */
 public interface GroupProviderService extends ProviderService<GroupProvider> {
 public interface GroupProviderService extends ProviderService<GroupProvider> {
 
 
+    /**
+     * Notifies core if any failure from data plane during group operations.
+     *
+     * @param operation offended group operation
+     */
     void groupOperationFailed(GroupOperation operation);
     void groupOperationFailed(GroupOperation operation);
 
 
     /**
     /**

@@ -36,7 +36,7 @@ import org.onosproject.net.DeviceId;
 public interface GroupService {
 public interface GroupService {
 
 
     /**
     /**
-     * Create a group in the specified device with the provided buckets.
+     * Creates a group in the specified device with the provided buckets.
      * This API provides an option for application to associate a cookie
      * This API provides an option for application to associate a cookie
      * while creating a group, so that applications can look-up the
      * while creating a group, so that applications can look-up the
      * groups based on the cookies. These Groups will be retained by
      * groups based on the cookies. These Groups will be retained by
@@ -55,7 +55,7 @@ public interface GroupService {
     void addGroup(GroupDescription groupDesc);
     void addGroup(GroupDescription groupDesc);
 
 
     /**
     /**
-     * Return a group object associated to an application cookie.
+     * Returns a group object associated to an application cookie.
      *
      *
      * NOTE1: The presence of group object in the system does not
      * NOTE1: The presence of group object in the system does not
      * guarantee that the "group" is actually created in device.
      * guarantee that the "group" is actually created in device.
@@ -64,14 +64,13 @@ public interface GroupService {
      *
      *
      * @param deviceId device identifier
      * @param deviceId device identifier
      * @param appCookie application cookie to be used for lookup
      * @param appCookie application cookie to be used for lookup
-     *
      * @return group associated with the application cookie or
      * @return group associated with the application cookie or
      *               NULL if Group is not found for the provided cookie
      *               NULL if Group is not found for the provided cookie
      */
      */
     Group getGroup(DeviceId deviceId, GroupKey appCookie);
     Group getGroup(DeviceId deviceId, GroupKey appCookie);
 
 
     /**
     /**
-     * Append buckets to existing group. The caller can optionally
+     * Appends buckets to existing group. The caller can optionally
      * associate a new cookie during this updation. GROUP_UPDATED or
      * associate a new cookie during this updation. GROUP_UPDATED or
      * GROUP_UPDATE_FAILED notifications would be provided along with
      * GROUP_UPDATE_FAILED notifications would be provided along with
      * cookie depending on the result of the operation on the device
      * cookie depending on the result of the operation on the device
@@ -89,7 +88,7 @@ public interface GroupService {
                            ApplicationId appId);
                            ApplicationId appId);
 
 
     /**
     /**
-     * Remove buckets from existing group. The caller can optionally
+     * Removes buckets from existing group. The caller can optionally
      * associate a new cookie during this updation. GROUP_UPDATED or
      * associate a new cookie during this updation. GROUP_UPDATED or
      * GROUP_UPDATE_FAILED notifications would be provided along with
      * GROUP_UPDATE_FAILED notifications would be provided along with
      * cookie depending on the result of the operation on the device
      * cookie depending on the result of the operation on the device
@@ -107,7 +106,7 @@ public interface GroupService {
                                 ApplicationId appId);
                                 ApplicationId appId);
 
 
     /**
     /**
-     * Delete a group associated to an application cookie.
+     * Deletes a group associated to an application cookie.
      * GROUP_DELETED or GROUP_DELETE_FAILED notifications would be
      * GROUP_DELETED or GROUP_DELETE_FAILED notifications would be
      * provided along with cookie depending on the result of the
      * provided along with cookie depending on the result of the
      * operation on the device
      * operation on the device
@@ -119,12 +118,11 @@ public interface GroupService {
     void removeGroup(Device deviceId, GroupKey appCookie, ApplicationId appId);
     void removeGroup(Device deviceId, GroupKey appCookie, ApplicationId appId);
 
 
     /**
     /**
-     * Retrieve all groups created by an application in the specified device
+     * Retrieves all groups created by an application in the specified device
      * as seen by current controller instance.
      * as seen by current controller instance.
      *
      *
      * @param deviceId device identifier
      * @param deviceId device identifier
      * @param appId application id
      * @param appId application id
-     *
      * @return collection of immutable group objects created by the application
      * @return collection of immutable group objects created by the application
      */
      */
     Iterable<Group> getGroups(Device deviceId, ApplicationId appId);
     Iterable<Group> getGroups(Device deviceId, ApplicationId appId);

+/*
+ * Copyright 2015 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.net.group;
+
+import org.onosproject.net.DeviceId;
+import org.onosproject.store.Store;
+
+/**
+ * Manages inventory of groups per device; not intended for direct use.
+ */
+public interface GroupStore extends Store<GroupEvent, GroupStoreDelegate> {
+
+    public enum UpdateType {
+        /**
+         * Modify existing group entry by adding provided information.
+         */
+        ADD,
+        /**
+         * Modify existing group by removing provided information from it.
+         */
+        REMOVE
+    }
+
+    /**
+     * Returns the number of groups for the specified device in the store.
+     *
+     * @param deviceId the device ID
+     * @return number of groups for the specified device
+     */
+    int getGroupCount(DeviceId deviceId);
+
+    /**
+     * Returns the groups associated with a device.
+     *
+     * @param deviceId the device ID
+     * @return the group entries
+     */
+    Iterable<Group> getGroups(DeviceId deviceId);
+
+    /**
+     * Returns the stored group entry.
+     *
+     * @param deviceId the device ID
+     * @param appCookie the group key
+     * @return a group associated with the key
+     */
+    Group getGroup(DeviceId deviceId, GroupKey appCookie);
+
+    /**
+     * Stores a new group entry using the information from group description.
+     *
+     * @param groupDesc group description to be used to store group entry
+     */
+    void storeGroupDescription(GroupDescription groupDesc);
+
+    /**
+     * Updates the existing group entry with the information
+     * from group description.
+     *
+     * @param deviceId the device ID
+     * @param oldAppCookie the current group key
+     * @param type update type
+     * @param newGroupDesc group description with updates
+     */
+    void updateGroupDescription(DeviceId deviceId,
+                                GroupKey oldAppCookie,
+                                UpdateType type,
+                                GroupDescription newGroupDesc);
+
+    /**
+     * Triggers deleting the existing group entry.
+     *
+     * @param deviceId the device ID
+     * @param appCookie the group key
+     */
+    void deleteGroupDescription(DeviceId deviceId,
+                                GroupKey appCookie);
+
+    /**
+     * Stores a new group entry, or updates an existing entry.
+     *
+     * @param group group entry
+     */
+    void addOrUpdateGroupEntry(Group group);
+
+    /**
+     * Removes the group entry from store.
+     *
+     * @param group group entry
+     */
+    void removeGroupEntry(Group group);
+}

+/*
+ * Copyright 2015 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.net.group;
+
+import org.onosproject.store.StoreDelegate;
+
+/**
+ * Group store delegate abstraction.
+ */
+public interface GroupStoreDelegate extends StoreDelegate<GroupEvent> {
+}

+/*
+ * Copyright 2015 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.net.group;
+
+/**
+ * Interface that defines set methods for a group entry
+ * that is stored in the system.
+ */
+public interface StoredGroupEntry extends Group {
+
+    /**
+     * Sets the new state for this entry.
+     *
+     * @param newState new group entry state.
+     */
+    void setState(Group.GroupState newState);
+
+    /**
+     * Sets how long this entry has been entered in the system.
+     *
+     * @param life epoch time
+     */
+    void setLife(long life);
+
+    /**
+     * Sets number of packets processed by this group entry.
+     *
+     * @param packets a long value
+     */
+    void setPackets(long packets);
+
+    /**
+     * Sets number of bytes processed by this group entry.
+     *
+     * @param bytes a long value
+     */
+    void setBytes(long bytes);
+
+}

+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Implementation of the group store.
+ */
+package org.onosproject.store.group.impl;
\ No newline at end of file