org.onosproject.net.group

Interface GroupService

All Superinterfaces:

ListenerService<GroupEvent,GroupListener>

public interface GroupService
extends ListenerService<GroupEvent,GroupListener>

Service for create/update/delete "group" in the devices. Flow entries can point to a "group" defined in the devices that enables to represent additional methods of forwarding like load-balancing or failover among different group of ports or multicast to all ports specified in a group. "group" can also be used for grouping common actions of different flows, so that in some scenarios only one group entry required to be modified for all the referencing flow entries instead of modifying all of them. This implements semantics of a distributed authoritative group store where the master copy of the groups lies with the controller and the devices hold only the 'cached' copy.

Method Summary

Modifier and Type	Method and Description
void	addBucketsToGroup(DeviceId deviceId, GroupKey oldCookie, GroupBuckets buckets, GroupKey newCookie, ApplicationId appId) Appends buckets to existing group.
void	addGroup(GroupDescription groupDesc) Creates a group in the specified device with the provided buckets.
Group	getGroup(DeviceId deviceId, GroupKey appCookie) Returns a group object associated to an application cookie.
Iterable<Group>	getGroups(DeviceId deviceId) Returns all groups associated with the given device.
Iterable<Group>	getGroups(DeviceId deviceId, ApplicationId appId) Retrieves all groups created by an application in the specified device as seen by current controller instance.
default void	purgeGroupEntries() Purges all group entries.
void	purgeGroupEntries(DeviceId deviceId) Purges all the group entries on the specified device.
void	removeBucketsFromGroup(DeviceId deviceId, GroupKey oldCookie, GroupBuckets buckets, GroupKey newCookie, ApplicationId appId) Removes buckets from existing group.
void	removeGroup(DeviceId deviceId, GroupKey appCookie, ApplicationId appId) Deletes a group associated to an application cookie.
default void	setBucketsForGroup(DeviceId deviceId, GroupKey oldCookie, GroupBuckets buckets, GroupKey newCookie, ApplicationId appId) Set buckets for an existing group.

Methods inherited from interface org.onosproject.event.ListenerService

addListener, removeListener

Method Detail

addGroup

void addGroup(GroupDescription groupDesc)

Creates a group in the specified device with the provided buckets. This API provides an option for application to associate a cookie while creating a group, so that applications can look-up the groups based on the cookies. These Groups will be retained by the core system and re-applied if any groups found missing in the device when it reconnects. This API would immediately return after submitting the request locally or to a remote Master controller instance. As a response to this API invocation, GROUP_ADDED or GROUP_ADD_FAILED notifications would be provided along with cookie depending on the result of the operation on the device in the data plane. The caller may also use "getGroup" API to get the Group object created as part of this request.

Parameters:

groupDesc - group creation parameters

getGroup

Group getGroup(DeviceId deviceId,
               GroupKey appCookie)

Returns a group object associated to an application cookie. NOTE1: The presence of group object in the system does not guarantee that the "group" is actually created in device. GROUP_ADDED notification would confirm the creation of this group in data plane.

Parameters:

deviceId - device identifier

appCookie - application cookie to be used for lookup

Returns:

group associated with the application cookie or NULL if Group is not found for the provided cookie

addBucketsToGroup

void addBucketsToGroup(DeviceId deviceId,
                       GroupKey oldCookie,
                       GroupBuckets buckets,
                       GroupKey newCookie,
                       ApplicationId appId)

Appends buckets to existing group. The caller can optionally associate a new cookie during this updation. GROUP_UPDATED or GROUP_UPDATE_FAILED notifications would be provided along with cookie depending on the result of the operation on the device.

Parameters:

deviceId - device identifier

oldCookie - cookie to be used to retrieve the existing group

buckets - immutable list of group bucket to be added

newCookie - immutable cookie to be used post update operation

appId - Application Id

removeBucketsFromGroup

void removeBucketsFromGroup(DeviceId deviceId,
                            GroupKey oldCookie,
                            GroupBuckets buckets,
                            GroupKey newCookie,
                            ApplicationId appId)

Removes buckets from existing group. The caller can optionally associate a new cookie during this updation. GROUP_UPDATED or GROUP_UPDATE_FAILED notifications would be provided along with cookie depending on the result of the operation on the device.

Parameters:

deviceId - device identifier

oldCookie - cookie to be used to retrieve the existing group

buckets - immutable list of group bucket to be removed

newCookie - immutable cookie to be used post update operation

appId - Application Id

setBucketsForGroup

default void setBucketsForGroup(DeviceId deviceId,
                                GroupKey oldCookie,
                                GroupBuckets buckets,
                                GroupKey newCookie,
                                ApplicationId appId)

Set buckets for an existing group. The caller can optionally associate a new cookie during this updation. GROUP_UPDATED or GROUP_UPDATE_FAILED notifications would be provided along with cookie depending on the result of the operation on the device. This operation overwrites the previous group buckets entirely.

Parameters:

deviceId - device identifier

oldCookie - cookie to be used to retrieve the existing group

buckets - immutable list of group buckets to be set

newCookie - immutable cookie to be used post update operation

appId - Application Id

purgeGroupEntries

void purgeGroupEntries(DeviceId deviceId)

Purges all the group entries on the specified device.

Parameters:

deviceId - device identifier

purgeGroupEntries

default void purgeGroupEntries()

Purges all group entries.

removeGroup

void removeGroup(DeviceId deviceId,
                 GroupKey appCookie,
                 ApplicationId appId)

Deletes a group associated to an application cookie. GROUP_DELETED or GROUP_DELETE_FAILED notifications would be provided along with cookie depending on the result of the operation on the device.

Parameters:

deviceId - device identifier

appCookie - application cookie to be used for lookup

appId - Application Id

getGroups

Iterable<Group> getGroups(DeviceId deviceId,
                          ApplicationId appId)

Retrieves all groups created by an application in the specified device as seen by current controller instance.

Parameters:

deviceId - device identifier

appId - application id

Returns:

collection of immutable group objects created by the application

getGroups

Iterable<Group> getGroups(DeviceId deviceId)

Returns all groups associated with the given device.

Parameters:

deviceId - device ID to get groups for

Returns:

iterable of device's groups