Package 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 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​(DeviceId deviceId,
                               ApplicationId appId)
        Purges all the group entries on the specified device and application.
        Parameters:
        deviceId - device identifier
        appId - application 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