Initial sketch of LabelResource APIs

LabelResource subsystem will be used to manage label resources such as
MPLS labels, ... (Part of ONOS-1223)

:)

Change-Id: Ib11eac84d81d7d86eaaf0222cf0bd7d3c64d2e51

+package org.onosproject.net.resource;
+
+import java.util.Objects;
+
+import org.onosproject.net.Annotations;
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.provider.ProviderId;
+import static com.google.common.base.MoreObjects.toStringHelper;
+
+/**
+ * the implementation of a label resource of a device.
+ */
+public final class DefaultLabelResource implements LabelResource {
+
+    private DeviceId deviceId;
+
+    private LabelResourceId labelResourceId;
+
+    /**
+     * Initialize a label resource object.
+     * @param deviceId device identifier
+     * @param labelResourceId label resource id
+     */
+    public DefaultLabelResource(String deviceId, long labelResourceId) {
+        this.deviceId = DeviceId.deviceId(deviceId);
+        this.labelResourceId = LabelResourceId.labelResourceId(labelResourceId);
+    }
+
+    /**
+     * Initialize a label resource object.
+     * @param deviceId device identifier
+     * @param labelResourceId label resource id
+     */
+    public DefaultLabelResource(DeviceId deviceId,
+                                LabelResourceId labelResourceId) {
+        this.deviceId = deviceId;
+        this.labelResourceId = labelResourceId;
+    }
+
+    @Override
+    public DeviceId deviceId() {
+        return deviceId;
+    }
+
+    @Override
+    public LabelResourceId labelResourceId() {
+        return labelResourceId;
+    }
+
+    @Override
+    public Annotations annotations() {
+        return null;
+    }
+
+    @Override
+    public ProviderId providerId() {
+        return null;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(deviceId, labelResourceId);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj instanceof DefaultLabelResource) {
+            DefaultLabelResource that = (DefaultLabelResource) obj;
+            return Objects.equals(this.deviceId, that.deviceId)
+                    && Objects.equals(this.labelResourceId,
+                                      that.labelResourceId);
+        }
+        return false;
+    }
+
+    @Override
+    public String toString() {
+        return toStringHelper(this).add("deviceId", deviceId)
+                .add("labelResourceId", labelResourceId).toString();
+    }
+}

+package org.onosproject.net.resource;
+
+import org.onosproject.net.Annotated;
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.NetworkResource;
+import org.onosproject.net.Provided;
+
+/**
+ * Representation of label resource.
+ */
+public interface LabelResource extends Annotated, Provided, NetworkResource {
+    /**
+     * Returns device id.
+     * @return DeviceId
+     */
+    public DeviceId deviceId();
+
+    /**
+     * Returns labelResource Id.
+     * @return LabelResourceId
+     */
+    public LabelResourceId labelResourceId();
+}

+package org.onosproject.net.resource;
+
+import org.onosproject.net.DeviceId;
+
+/**
+ * Service for managing label resource.
+ */
+public interface LabelResourceAdminService {
+    /**
+     * Creates the only label resource of some device id from begin label to end
+     * label.
+     *
+     * @param deviceId device identifier
+     * @param beginLabel represents for the first label id in the range of label
+     *            pool
+     * @param endLabel represents for the last label id in the range of label
+     *            pool
+     * @return success or fail
+     */
+    boolean createDevicePool(DeviceId deviceId, LabelResourceId beginLabel,
+                             LabelResourceId endLabel);
+
+    /**
+     * Creates the only global label resource pool.
+     *
+     * @param beginLabel represents for the first label id in the range of label
+     *            pool
+     * @param endLabel represents for the last label id in the range of label
+     *            pool
+     * @return success or fail
+     */
+    boolean createGlobalPool(LabelResourceId beginLabel,
+                             LabelResourceId endLabel);
+
+    /**
+     * Destroys a label resource pool of a specific device id.
+     *
+     * @param deviceId device identifier
+     * @return success or fail
+     */
+    boolean destroyDevicePool(DeviceId deviceId);
+
+    /**
+     * Destroys the global label resource pool.
+     *
+     * @return success or fail
+     */
+    boolean destroyGlobalPool();
+}

+package org.onosproject.net.resource;
+
+import org.onosproject.store.StoreDelegate;
+/**
+ * Label resource store delegate.
+ */
+public interface LabelResourceDelegate extends StoreDelegate<LabelResourceEvent> {
+
+}

+package org.onosproject.net.resource;
+
+import org.onosproject.event.AbstractEvent;
+
+/**
+ * Describes label resource event.
+ */
+public final class LabelResourceEvent
+        extends AbstractEvent<LabelResourceEvent.Type, LabelResourcePool> {
+
+    /**
+     * Type of label resource event.
+     */
+    public enum Type {
+        /**
+         * Signifies that a new pool has been administratively created.
+         */
+        POOL_CREATED,
+        /**
+         * Signifies that a new pool has been administratively destroyed.
+         */
+        POOL_DESTROYED,
+        /**
+         * Signifies that a new pool has been administratively changed.
+         */
+        POOL_CAPACITY_CHANGED
+    }
+
+    /**
+     * Creates an event of a given type and the given LabelResourcePool.
+     *
+     * @param type event type
+     * @param subject pool
+     */
+    public LabelResourceEvent(Type type, LabelResourcePool subject) {
+        super(type, subject);
+    }
+}

+package org.onosproject.net.resource;
+
+import java.util.Objects;
+
+/**
+ * Representation of a label.
+ */
+public final class LabelResourceId implements ResourceId {
+
+    private long labelId;
+
+    public static LabelResourceId labelResourceId(long labelResourceId) {
+        return new LabelResourceId(labelResourceId);
+    }
+
+    // Public construction is prohibited
+    private LabelResourceId(long labelId) {
+        this.labelId = labelId;
+    }
+
+    public long labelId() {
+        return labelId;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hashCode(labelId);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj instanceof LabelResourceId) {
+            LabelResourceId that = (LabelResourceId) obj;
+            return Objects.equals(this.labelId, that.labelId);
+        }
+        return false;
+    }
+
+    @Override
+    public String toString() {
+        return String.valueOf(this.labelId);
+    }
+
+}

+package org.onosproject.net.resource;
+
+import org.onosproject.event.EventListener;
+/**
+ * Entity capable of receiving label resource related events.
+ */
+public interface LabelResourceListener extends EventListener<LabelResourceEvent> {
+
+}

+package org.onosproject.net.resource;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import java.util.Collections;
+import java.util.Objects;
+import java.util.Set;
+
+import org.onosproject.net.DeviceId;
+
+import com.google.common.base.MoreObjects;
+import com.google.common.collect.ImmutableSet;
+
+/**
+ * Abstraction of the capacity of device label resource or global label
+ * resource. it's contiguous range of label resource.when a application apply
+ * some labels of some device,first catch from Set that store
+ * available labels,if the size of the Set less than the apply number,then get
+ * labels by calculating with three attributes, beginLabel,endLabel and
+ * currentUsedMaxLabelId
+ */
+public class LabelResourcePool {
+
+    private final DeviceId deviceId;
+    private final LabelResourceId beginLabel;
+    private final LabelResourceId endLabel;
+    private final long totalNum; // capacity of label resource pool
+    private final long usedNum; // have used label number
+    private final LabelResourceId currentUsedMaxLabelId; // the maximal label
+                                                        // number id
+    private ImmutableSet<LabelResource> releaseLabelId; // Set of released label
+
+    /**
+     * Creates a pool by device id,begin label id,end label id.
+     *
+     * @param deviceId device identifier
+     * @param beginLabel represents for the first label id in the range of label
+     *            resource pool
+     * @param endLabel represents for the last label id in the range of label
+     *            resource pool
+     */
+    public LabelResourcePool(String deviceId, long beginLabel, long endLabel) {
+        this(deviceId, beginLabel, endLabel, endLabel - beginLabel + 1, 0L,
+             beginLabel, ImmutableSet.copyOf(Collections.emptySet()));
+    }
+
+    /**
+     * Creates a pool by device id,begin label id,end label id.
+     * used to update a pool in the store.
+     * @param deviceId device identifier
+     * @param beginLabel represents for the first label id in the range of label
+     *            resource pool
+     * @param endLabel represents for the last label id in the range of label
+     *            resource pool
+     * @param totalNum capacity of label resource pool
+     * @param usedNum have used label number
+     * @param currentUsedMaxLabelId the maximal label number id
+     * @param releaseLabelId Set of released label
+     */
+    public LabelResourcePool(String deviceId, long beginLabel, long endLabel,
+                             long totalNum, long usedNum,
+                             long currentUsedMaxLabelId,
+                             ImmutableSet<LabelResource> releaseLabelId) {
+        checkArgument(endLabel >= beginLabel,
+                      "endLabel %s must be greater than or equal to beginLabel %s",
+                      endLabel, beginLabel);
+        this.deviceId = DeviceId.deviceId(deviceId);
+        this.beginLabel = LabelResourceId.labelResourceId(beginLabel);
+        this.endLabel = LabelResourceId.labelResourceId(endLabel);
+        this.totalNum = totalNum;
+        this.usedNum = usedNum;
+        this.currentUsedMaxLabelId = LabelResourceId
+                .labelResourceId(currentUsedMaxLabelId);
+        this.releaseLabelId = releaseLabelId;
+    }
+
+    /**
+     * Returns a device id.
+     *
+     * @return DeviceId
+     */
+    public DeviceId deviceId() {
+        return deviceId;
+    }
+
+    /**
+     * Returns a begin Label id.
+     *
+     * @return begin Label id
+     */
+    public LabelResourceId beginLabel() {
+        return beginLabel;
+    }
+
+    /**
+     * Returns a end Label id.
+     *
+     * @return end Label id
+     */
+    public LabelResourceId endLabel() {
+        return endLabel;
+    }
+
+    /**
+     * Returns a begin Label id.
+     *
+     * @return current Used Maximal Label Id
+     */
+    public LabelResourceId currentUsedMaxLabelId() {
+        return currentUsedMaxLabelId;
+    }
+
+    /**
+     * Returns total number.
+     *
+     * @return the total label number
+     */
+    public long totalNum() {
+        return totalNum;
+    }
+
+    /**
+     * Returns used number.
+     *
+     * @return the used label number
+     */
+    public long usedNum() {
+        return usedNum;
+    }
+
+    /**
+     * Returns the Set of released label before.
+     *
+     * @return the Set of LabelResource
+     */
+    public Set<LabelResource> releaseLabelId() {
+        return releaseLabelId;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.deviceId, this.beginLabel, this.endLabel,
+                            this.totalNum, this.usedNum,
+                            this.currentUsedMaxLabelId, this.releaseLabelId);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj instanceof LabelResourcePool) {
+            LabelResourcePool that = (LabelResourcePool) obj;
+            return Objects.equals(this.deviceId, that.deviceId)
+                    && Objects.equals(this.beginLabel, that.beginLabel)
+                    && Objects.equals(this.endLabel, that.endLabel)
+                    && Objects.equals(this.totalNum, that.totalNum)
+                    && Objects.equals(this.usedNum, that.usedNum)
+                    && Objects.equals(this.currentUsedMaxLabelId,
+                                      that.currentUsedMaxLabelId)
+                    && Objects.equals(this.releaseLabelId, that.releaseLabelId);
+        }
+        return false;
+    }
+
+    @Override
+    public String toString() {
+        // TODO Auto-generated method stub
+        return MoreObjects.toStringHelper(this).add("deviceId", this.deviceId)
+                .add("beginLabel", this.beginLabel)
+                .add("endLabel", this.endLabel).add("totalNum", this.totalNum)
+                .add("usedNum", this.usedNum)
+                .add("currentUsedMaxLabelId", this.currentUsedMaxLabelId)
+                .add("releaseLabelId", this.releaseLabelId).toString();
+    }
+}

+package org.onosproject.net.resource;
+
+import org.onosproject.net.provider.Provider;
+/**
+ * Abstraction of an entity providing information about label resource
+ * to the core.
+ */
+public interface LabelResourceProvider extends Provider {
+
+}

+package org.onosproject.net.resource;
+
+import org.onosproject.net.provider.ProviderRegistry;
+/**
+ * Abstraction of an label resource provider registry.
+ */
+public interface LabelResourceProviderRegistry
+        extends ProviderRegistry<LabelResourceProvider, LabelResourceProviderService> {
+
+}

+package org.onosproject.net.resource;
+
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.provider.ProviderService;
+
+/**
+ * Means for injecting label information into the core.
+ */
+public interface LabelResourceProviderService extends ProviderService<LabelResourceProvider> {
+
+    /**
+     * Signals that a device label resource pool has been detected.
+     * @param deviceId device identifier
+     * @param beginLabel the begin label number of resource
+     * @param endLabel the end label number of resource
+     */
+    void deviceLabelResourcePoolDetected(DeviceId deviceId,
+                                         LabelResourceId beginLabel,
+                                         LabelResourceId endLabel);
+
+    /**
+     * Signals that an label resource pool has been destroyed.
+     * @param deviceId device identifier
+     */
+    void deviceLabelResourcePoolDestroyed(DeviceId deviceId);
+}

+package org.onosproject.net.resource;
+
+import java.util.Collection;
+import java.util.Objects;
+
+import org.onosproject.net.DeviceId;
+
+import com.google.common.base.MoreObjects;
+import com.google.common.collect.ImmutableSet;
+/**
+ * Represents for a label request.
+ */
+public class LabelResourceRequest {
+
+    private final DeviceId deviceId;
+    private final Type type;
+    private final long applyNum;
+    private ImmutableSet<LabelResource> releaseCollection;
+
+    /**
+     * Creates LabelResourceRequest object.
+     * @param deviceId device identifier
+     * @param type request type
+     * @param applyNum apply the number of labels
+     * @param releaseCollection Set of released label
+     */
+    public LabelResourceRequest(DeviceId deviceId,
+                                Type type,
+                                long applyNum,
+                                ImmutableSet<LabelResource> releaseCollection) {
+        this.deviceId = deviceId;
+        this.type = type;
+        this.applyNum = applyNum;
+        this.releaseCollection = releaseCollection;
+    }
+    /**
+     * Returns a device id.
+     * @return DeviceId
+     */
+    public DeviceId deviceId() {
+        return deviceId;
+    }
+
+    /**
+     * Returns request type.
+     * @return Type
+     */
+    public Type type() {
+        return type;
+    }
+
+    /**
+     * Returns apply label number.
+     * @return label number
+     */
+    public long applyNum() {
+        return applyNum;
+    }
+
+    /**
+     * Returns the collection of release labels.
+     * @return Collection of DefaultLabelResource
+     */
+    public Collection<LabelResource> releaseCollection() {
+        return releaseCollection;
+    }
+
+    /**
+     * Request type.
+     */
+    public enum Type {
+        APPLY, //apple label request
+        RELEASE //release label request
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.deviceId, this.applyNum, this.type,
+                            this.releaseCollection);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj instanceof LabelResourceRequest) {
+            LabelResourceRequest that = (LabelResourceRequest) obj;
+            return Objects.equals(this.deviceId, that.deviceId)
+                    && Objects.equals(this.applyNum, that.applyNum)
+                    && Objects.equals(this.type, that.type)
+                    && Objects.equals(this.releaseCollection,
+                                      that.releaseCollection);
+        }
+        return false;
+    }
+
+    @Override
+    public String toString() {
+        return MoreObjects.toStringHelper(this).add("deviceId", this.deviceId)
+                .add("applyNum", this.applyNum).add("type", this.type)
+                .add("releaseCollection", this.releaseCollection).toString();
+    }
+}

+package org.onosproject.net.resource;
+
+import java.util.Collection;
+import java.util.Set;
+
+import org.onosproject.net.DeviceId;
+
+import com.google.common.collect.Multimap;
+
+/**
+ * Service for providing label resource allocation.
+ */
+public interface LabelResourceService {
+
+    /**
+     * Returns labels from resource pool by a specific device id.
+     *
+     * @param deviceId device identifier
+     * @param applyNum the applying number
+     * @return collection of applying labels
+     */
+    Collection<LabelResource> applyFromDevicePool(DeviceId deviceId,
+                                                  long applyNum);
+
+    /**
+     * Returns labels from the global label resource pool.
+     *
+     * @param applyNum the applying number
+     * @return collection of applying labels
+     */
+    Collection<LabelResource> applyFromGlobalPool(long applyNum);
+
+    /**
+     * Releases unused labels to device pools .
+     *
+     * @param release the collection of releasing labels
+     * @return success or fail
+     */
+    boolean releaseToDevicePool(Multimap<DeviceId, LabelResource> release);
+
+    /**
+     * Releases unused labels to the global resource pool.
+     *
+     * @param release release the collection of releasing labels
+     * @return success or fail
+     */
+    boolean releaseToGlobalPool(Set<LabelResourceId> release);
+
+    /**
+     * Judges if the pool of a specific device id is full.
+     *
+     * @param deviceId device identifier
+     * @return yes or no
+     */
+    boolean isDevicePoolFull(DeviceId deviceId);
+
+    /**
+     * Judges if the global resource pool is full.
+     *
+     * @return yes or no
+     */
+    boolean isGlobalPoolFull();
+
+    /**
+     * Returns the unused label number of a label resource pool by a specific device
+     * id.
+     *
+     * @param deviceId device identifier
+     * @return number of unused labels
+     */
+    long getFreeNumOfDevicePool(DeviceId deviceId);
+
+    /**
+     * Returns the unused label number of a global label resource pool.
+     *
+     * @return number of unused labels
+     */
+    long getFreeNumOfGlobalPool();
+
+    /**
+     * Returns the label resource pool of a label resource by a specific device
+     * id.
+     *
+     * @param deviceId device identifier
+     * @return the device label resource pool
+     */
+    LabelResourcePool getDeviceLabelResourcePool(DeviceId deviceId);
+
+    /**
+     * Returns the global label resource pool.
+     *
+     * @return the global label resource pool
+     */
+    LabelResourcePool getGlobalLabelResourcePool();
+
+    /**
+     * Adds the specified label resource listener.
+     *
+     * @param listener label resource listener
+     */
+    void addListener(LabelResourceListener listener);
+
+    /**
+     * Removes the specified label resource listener.
+     *
+     * @param listener label resource listener
+     */
+    void removeListener(LabelResourceListener listener);
+}

+package org.onosproject.net.resource;
+
+import java.util.Collection;
+import java.util.Set;
+
+import org.onosproject.net.DeviceId;
+import org.onosproject.store.Store;
+
+import com.google.common.collect.Multimap;
+
+/**
+ * Manages inventory of label; not intended for direct use.
+ *
+ */
+public interface LabelResourceStore
+        extends Store<LabelResourceEvent, LabelResourceDelegate> {
+
+    /**
+     * Creates a label resource of some device id from begin label to end label.
+     *
+     * @param deviceId device identifier
+     * @param beginLabel represents for the first label id in the range of label
+     *            pool
+     * @param endLabel represents for the last label id in the range of label
+     *            pool
+     * @return success or fail
+     */
+    boolean createDevicePool(DeviceId deviceId, LabelResourceId beginLabel,
+                             LabelResourceId endLabel);
+
+    /**
+     * Creates the global label resource pool.
+     *
+     * @param beginLabel represents for the first label id in the range of label
+     *            pool
+     * @param endLabel represents for the last label id in the range of label
+     *            pool
+     * @return success or fail
+     */
+    boolean createGlobalPool(LabelResourceId beginLabel,
+                             LabelResourceId endLabel);
+
+    /**
+     * Destroys a label resource pool of a specific device id.
+     *
+     * @param deviceId device identifier
+     * @return success or fail
+     */
+    boolean destroyDevicePool(DeviceId deviceId);
+
+    /**
+     * Destroys a the global label resource pool.
+     *
+     * @return success or fail
+     */
+    boolean destroyGlobalPool();
+
+    /**
+     * Returns labels from resource pool by a specific device id.
+     *
+     * @param deviceId device identifier
+     * @param applyNum the applying number
+     * @return collection of applying labels
+     */
+    Collection<LabelResource> applyFromDevicePool(DeviceId deviceId,
+                                                  long applyNum);
+
+    /**
+     * Returns labels from the global label resource pool.
+     *
+     * @param applyNum apply the number of labels
+     * @return collection of labels
+     */
+    Collection<LabelResource> applyFromGlobalPool(long applyNum);
+
+    /**
+     * Releases unused labels to device pools .
+     *
+     * @param release the collection of releasing labels
+     * @return success or fail
+     */
+    boolean releaseToDevicePool(Multimap<DeviceId, LabelResource> release);
+
+    /**
+     * Releases unused labels to the global resource pool.
+     *
+     * @param release release the collection of releasing labels
+     * @return success or fail
+     */
+    boolean releaseToGlobalPool(Set<LabelResourceId> release);
+
+    /**
+     * Judges if the pool of a specific device id is full.
+     *
+     * @param deviceId device identifier
+     * @return yes or no
+     */
+    boolean isDevicePoolFull(DeviceId deviceId);
+
+    /**
+     * Judges if the global resource pool is full.
+     *
+     * @return yes or no
+     */
+    boolean isGlobalPoolFull();
+
+    /**
+     * Returns the unused label number of a label resource pool by a specific device
+     * id.
+     *
+     * @param deviceId device identifier
+     * @return number of unused labels
+     */
+    long getFreeNumOfDevicePool(DeviceId deviceId);
+
+    /**
+     * Returns the unused number of a global label resource pool.
+     *
+     * @return number of unused labels
+     */
+    long getFreeNumOfGlobalPool();
+
+    /**
+     * Returns the label resource pool by a specific device id.
+     *
+     * @param deviceId device identifier
+     * @return the device label resource pool
+     */
+    LabelResourcePool getDeviceLabelResourcePool(DeviceId deviceId);
+
+    /**
+     * Returns the global label resource pool.
+     *
+     * @return the global label resource pool
+     */
+    LabelResourcePool getGlobalLabelResourcePool();
+}