ONOS-2382: Define a new resource management API

Change-Id: I8abbb30967a7f99ea96b22613b40b2bc0a0ce73c

@@ -16,13 +16,14 @@
 package org.onosproject.net.intent;
 package org.onosproject.net.intent;
 
 
 import com.google.common.annotations.Beta;
 import com.google.common.annotations.Beta;
+import org.onosproject.net.newresource.ResourceConsumer;
 
 
 /**
 /**
  * Intent identifier suitable as an external key.
  * Intent identifier suitable as an external key.
  * <p>This class is immutable.</p>
  * <p>This class is immutable.</p>
  */
  */
 @Beta
 @Beta
-public final class IntentId {
+public final class IntentId implements ResourceConsumer {
 
 
     private final long value;
     private final long value;
 
 

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+
+import java.util.Objects;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+/**
+ * Base implementation of a class representing resource which belongs to a particular subject.
+ *
+ * @param <S> type of the subject
+ * @param <T> type of the resource
+ */
+@Beta
+public abstract class AbstractResource<S, T> implements Resource<S, T> {
+
+    private final S subject;
+    private final T resource;
+
+    /**
+     * Constructor expected to be called by constructors of the sub-classes.
+     *
+     * @param subject identifier which this resource belongs to
+     * @param resource resource of the subject
+     */
+    protected AbstractResource(S subject, T resource) {
+        this.subject = checkNotNull(subject);
+        this.resource = checkNotNull(resource);
+    }
+
+    @Override
+    public S subject() {
+        return subject;
+    }
+
+    @Override
+    public T resource() {
+        return resource;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(subject, resource);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (!(obj instanceof AbstractResource)) {
+            return false;
+        }
+        final AbstractResource that = (AbstractResource) obj;
+        return Objects.equals(this.subject, that.subject)
+                && Objects.equals(this.resource, that.resource);
+    }
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+
+import java.util.Objects;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+/**
+ * Base implementation of a class representing allocation of resource which belongs to a particular subject.
+ *
+ * @param <S> type of the subject
+ * @param <T> type of the resource
+ */
+@Beta
+public abstract class AbstractResourceAllocation<S, T> implements ResourceAllocation<S, T> {
+
+    private final S subject;
+    private final T resource;
+    private final ResourceConsumer consumer;
+
+    /**
+     * Constructor expected to be called by constructors of the sub-classes.
+     *
+     * @param subject identifier which this resource belongs to
+     * @param resource resource of the subject
+     * @param consumer consumer ot this resource
+     */
+    protected AbstractResourceAllocation(S subject, T resource, ResourceConsumer consumer) {
+        this.subject = checkNotNull(subject);
+        this.resource = checkNotNull(resource);
+        this.consumer = consumer;
+    }
+
+    @Override
+    public S subject() {
+        return subject;
+    }
+
+    @Override
+    public T resource() {
+        return resource;
+    }
+
+    @Override
+    public ResourceConsumer consumer() {
+        return consumer;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(subject, resource, consumer);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (!(obj instanceof AbstractResourceAllocation)) {
+            return false;
+        }
+        final AbstractResourceAllocation that = (AbstractResourceAllocation) obj;
+        return Objects.equals(this.subject, that.subject)
+                && Objects.equals(this.resource, that.resource)
+                && Objects.equals(this.consumer, that.consumer);
+    }
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.net.DeviceId;
+
+/**
+ * Represents resource which belongs to a particular device.
+ *
+ * @param <T> represents the type of the resource
+ */
+@Beta
+public final class DeviceResource<T> extends AbstractResource<DeviceId, T> {
+
+    /**
+     * Creates a new device resource from the specified device identifier and resource.
+     * (deviceId, resource) signifies a resource identifier which is globally unique.
+     *
+     * @param deviceId device identifier which this resource belongs to
+     * @param resource resource of the device
+     */
+    public DeviceResource(DeviceId deviceId, T resource) {
+        super(deviceId, resource);
+    }
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.net.DeviceId;
+
+/**
+ * Represents allocation of resource bound to device.
+ *
+ * @param <T> type of the resource
+ */
+@Beta
+public final class DeviceResourceAllocation<T> extends AbstractResourceAllocation<DeviceId, T> {
+
+    /**
+     * Creates a new allocation of resource bound to the specified device and consumed by the specified user.
+     *
+     * @param device device identifier which this resource belongs to
+     * @param resource resource of the device
+     * @param consumer consumer of this resource
+     */
+    public DeviceResourceAllocation(DeviceId device, T resource, ResourceConsumer consumer) {
+        super(device, resource, consumer);
+    }
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.net.LinkKey;
+
+/**
+ * Represents resource which belongs to a particular link.
+ *
+ * @param <T> represents the type of the resource
+ */
+@Beta
+public final class LinkResource<T> extends AbstractResource<LinkKey, T> {
+
+    /**
+     * Creates a new link resource from the specified link identifier and resource.
+     * (linkKey, resource) signifies a resource identifier which is globally unique.
+     *
+     * @param linkKey link identifier which this resource belongs to
+     * @param resource resource of the link
+     */
+    public LinkResource(LinkKey linkKey, T resource) {
+        super(linkKey, resource);
+    }
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.net.LinkKey;
+
+/**
+ * Represents allocation of resource bound to link.
+ *
+ * @param <T> type of the resource
+ */
+@Beta
+public final class LinkResourceAllocation<T> extends AbstractResourceAllocation<LinkKey, T> {
+
+    /**
+     * Creates a new allocation of resource bound to the specified device and consumed by the specified user.
+     *
+     * @param link device identifier which this resource belongs to
+     * @param resource resource of the device
+     * @param consumer consumer of this resource
+     */
+    public LinkResourceAllocation(LinkKey link, T resource, ResourceConsumer consumer) {
+        super(link, resource, consumer);
+    }
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+
+/**
+ * Represents resource which belongs to a particular subject.
+ *
+ * @param <S> type of the subject
+ * @param <T> type of the resource
+ */
+@Beta
+public interface Resource<S, T> {
+    /**
+     * Returns the subject of the resource.
+     * The value is the identifier which this resource belongs to.
+     *
+     * @return the subject of the resource
+     */
+    S subject();
+
+    /**
+     * Returns the resource of the subject.
+     *
+     * @return the resource of the subject
+     */
+    T resource();
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+
+/**
+ * Represents allocation of resource which belongs to a particular subject.
+ *
+ * @param <S> type of the subject
+ * @param <T> type of the resource
+ */
+@Beta
+public interface ResourceAllocation<S, T> {
+    /**
+     * Returns the subject of the resource.
+     * The value is the identifier which this resource belongs to.
+     *
+     * @return the subject of the resource
+     */
+    S subject();
+
+    /**
+     * Returns the resource which belongs to the subject.
+     *
+     * @return the resource which belongs to the subject
+     */
+    T resource();
+
+    /**
+     * Returns the consumer of this resource.
+     *
+     * @return the consumer of this resource
+     */
+    ResourceConsumer consumer();
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+
+/**
+ * Marker interface representing an entity using resource.
+ */
+@Beta
+public interface ResourceConsumer {
+}

+/*
+ * 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.newresource;
+
+import com.google.common.annotations.Beta;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Service for allocating/releasing resource(s) and retrieving allocation(s) and availability.
+ */
+@Beta
+public interface ResourceService {
+    /**
+     * Allocates the specified resource to the specified user.
+     *
+     * @param consumer resource user which the resource is allocated to
+     * @param resource resource to be allocated
+     * @param <S> type of the subject which this resource belongs to
+     * @param <T> type of the resource
+     * @return allocation information enclosed by Optional. If the allocation fails, the return value is empty
+     */
+    <S, T> Optional<ResourceAllocation<S, T>> allocate(ResourceConsumer consumer, Resource<S, T> resource);
+
+    /**
+     * Transactionally allocates the specified resources to the specified user.
+     * All allocations are made when this method succeeds, or no allocation is made when this method fails.
+     *
+     * @param consumer resource user which the resources are allocated to
+     * @param resources resources to be allocated
+     * @return non-empty list of allocation information if succeeded, otherwise empty list
+     */
+    List<ResourceAllocation<?, ?>> allocate(ResourceConsumer consumer, List<? extends Resource<?, ?>> resources);
+
+    /**
+     * Transactionally allocates the specified resources to the specified user.
+     * All allocations are made when this method succeeds, or no allocation is made when this method fails.
+     *
+     * @param consumer resource user which the resources are allocated to
+     * @param resources resources to be allocated
+     * @return non-empty list of allocation information if succeeded, otherwise empty list
+     */
+    List<ResourceAllocation<?, ?>> allocate(ResourceConsumer consumer, Resource<?, ?>... resources);
+
+    /**
+     * Releases the specified resource allocation.
+     *
+     * @param allocation resource allocation to be released
+     * @param <S> type of the subject which this resource belongs to
+     * @param <T> type of the device resource
+     * @return true if succeeded, otherwise false
+     */
+    <S, T> boolean release(ResourceAllocation<S, T> allocation);
+
+    /**
+     * Transactionally releases the specified resource allocations.
+     * All allocations are released when this method succeeded, or no allocation is released when this method fails.
+     *
+     * @param allocations resource allocations to be released
+     * @return true if succeeded, otherwise false
+     */
+    boolean release(List<? extends ResourceAllocation<?, ?>> allocations);
+
+    /**
+     * Transactionally releases the specified resource allocations.
+     * All allocations are released when this method succeeded, or no allocation is released when this method fails.
+     *
+     * @param allocations resource allocations to be released
+     * @return true if succeeded, otherwise false
+     */
+    boolean release(ResourceAllocation<?, ?>... allocations);
+
+    /**
+     * Transactionally releases the resources allocated to the specified consumer.
+     * All allocations are released when this method succeeded, or no allocation is released when this method fails.
+     *
+     * @param consumer consumer whose allocated resources are to be released
+     * @return true if succeeded, otherwise false
+     */
+    boolean release(ResourceConsumer consumer);
+
+    /**
+     * Returns allocated resources in the specified subject regarding the specified resource type.
+     *
+     * @param subject subject where resource allocations are obtained
+     * @param cls class to specify a type of resource
+     * @param <S> type of the subject
+     * @param <T> type of the resource
+     * @return non-empty collection of resource allocations if resources are allocated with the subject and type,
+     * empty collection if no resource is allocated with the subject and type
+     */
+    <S, T> Collection<ResourceAllocation<S, T>> getResourceAllocations(S subject, Class<T> cls);
+
+    /**
+     * Returns resources allocated to the specified consumer.
+     *
+     * @param consumer consumer whose allocated resources are to be returned
+     * @return resources allocated to the consumer
+     */
+    Collection<ResourceAllocation<?, ?>> getResourceAllocations(ResourceConsumer consumer);
+
+    /**
+     * Returns the availability of the specified device resource.
+     *
+     * @param resource resource to check the availability
+     * @param <S> type of the subject
+     * @param <T> type of the resource
+     * @return true if available, otherwise false
+     */
+    <S, T> boolean isAvailable(Resource<S, T> resource);
+
+    // TODO: listener and event mechanism need to be considered
+}