[ONOS-4016] Implement Region administration REST API

- Impelent Region management REST API
- Add unit test for Region management REST API
- Add swagger docs for Region management REST API
- Add SCR Component and Service annotation for RegionManager

Change-Id: I042e92ed7144d596659b779a59239afba832ca62

@@ -17,9 +17,11 @@
 package org.onosproject.net.region.impl;
 
 import org.apache.felix.scr.annotations.Activate;
+import org.apache.felix.scr.annotations.Component;
 import org.apache.felix.scr.annotations.Deactivate;
 import org.apache.felix.scr.annotations.Reference;
 import org.apache.felix.scr.annotations.ReferenceCardinality;
+import org.apache.felix.scr.annotations.Service;
 import org.onosproject.cluster.NodeId;
 import org.onosproject.event.AbstractListenerManager;
 import org.onosproject.net.DeviceId;
@@ -45,6 +47,8 @@ import static org.slf4j.LoggerFactory.getLogger;
 /**
  * Provides implementation of the region service APIs.
  */
+@Component(immediate = true)
+@Service
 public class RegionManager extends AbstractListenerManager<RegionEvent, RegionListener>
         implements RegionAdminService, RegionService {
 

@@ -46,7 +46,8 @@ public class CoreWebApplication extends AbstractWebApplication {
                 MetricsWebResource.class,
                 FlowObjectiveWebResource.class,
                 MulticastRouteWebResource.class,
-                DeviceKeyWebResource.class
+                DeviceKeyWebResource.class,
+                RegionsWebResource.class
         );
     }
 }

+/*
+ * Copyright 2016 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.rest.resources;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.google.common.collect.Sets;
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.region.Region;
+import org.onosproject.net.region.RegionAdminService;
+import org.onosproject.net.region.RegionId;
+import org.onosproject.net.region.RegionService;
+import org.onosproject.rest.AbstractWebResource;
+
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.util.Set;
+
+import static org.onlab.util.Tools.nullIsNotFound;
+
+/**
+ * Manages region and device membership.
+ */
+@Path("regions")
+public class RegionsWebResource extends AbstractWebResource {
+    private final RegionService regionService = get(RegionService.class);
+    private final RegionAdminService regionAdminService = get(RegionAdminService.class);
+
+    private static final String REGION_NOT_FOUND = "Region is not found for ";
+    private static final String REGION_INVALID = "Invalid regionId in region update request";
+    private static final String DEVICE_IDS_INVALID = "Invalid device identifiers";
+
+    /**
+     * Returns set of all regions.
+     *
+     * @return 200 OK
+     * @onos.rsModel Regions
+     */
+    @GET
+    @Produces(MediaType.APPLICATION_JSON)
+    public Response getRegions() {
+        final Iterable<Region> regions = regionService.getRegions();
+        return ok(encodeArray(Region.class, "regions", regions)).build();
+    }
+
+    /**
+     * Returns the region with the specified identifier.
+     *
+     * @param regionId region identifier
+     * @return 200 OK, 404 not found
+     * @onos.rsModel Region
+     */
+    @GET
+    @Produces(MediaType.APPLICATION_JSON)
+    @Path("{regionId}")
+    public Response getRegionById(@PathParam("regionId") String regionId) {
+        final RegionId rid = RegionId.regionId(regionId);
+        final Region region = nullIsNotFound(regionService.getRegion(rid),
+                REGION_NOT_FOUND + rid.toString());
+        return ok(codec(Region.class).encode(region, this)).build();
+    }
+
+    /**
+     * Returns the set of devices that belong to the specified region.
+     *
+     * @param regionId region identifier
+     * @return 200 OK
+     * @onos.rsModel RegionDeviceIds
+     */
+    @GET
+    @Produces(MediaType.APPLICATION_JSON)
+    @Path("{regionId}/devices")
+    public Response getRegionDevices(@PathParam("regionId") String regionId) {
+        final RegionId rid = RegionId.regionId(regionId);
+        final Iterable<DeviceId> deviceIds = regionService.getRegionDevices(rid);
+        final ObjectNode root = mapper().createObjectNode();
+        final ArrayNode deviceIdsNode = root.putArray("deviceIds");
+        deviceIds.forEach(did -> deviceIdsNode.add(did.toString()));
+        return ok(root).build();
+    }
+
+    /**
+     * Creates a new region using the supplied JSON input stream.
+     *
+     * @param stream region JSON stream
+     * @return status of the request - CREATED if the JSON is correct,
+     * BAD_REQUEST if the JSON is invalid
+     * @onos.rsModel RegionPost
+     */
+    @POST
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    public Response createRegion(InputStream stream) {
+        URI location;
+        try {
+            ObjectNode jsonTree = (ObjectNode) mapper().readTree(stream);
+            final Region region = codec(Region.class).decode(jsonTree, this);
+            final Region resultRegion = regionAdminService.createRegion(region.id(),
+                                region.name(), region.type(), region.masters());
+            location = new URI(resultRegion.id().id());
+        } catch (IOException | URISyntaxException e) {
+            throw new IllegalArgumentException(e);
+        }
+
+        return Response.created(location).build();
+    }
+
+    /**
+     * Updates the specified region using the supplied JSON input stream.
+     *
+     * @param regionId region identifier
+     * @param stream region JSON stream
+     * @return status of the request - UPDATED if the JSON is correct,
+     * BAD_REQUEST if the JSON is invalid
+     * @onos.rsModel RegionPost
+     */
+    @PUT
+    @Path("{regionId}")
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    public Response updateRegion(@PathParam("regionId") String regionId,
+                                 InputStream stream) {
+        try {
+            ObjectNode jsonTree = (ObjectNode) mapper().readTree(stream);
+            JsonNode specifiedRegionId = jsonTree.get("id");
+
+            if (specifiedRegionId != null &&
+                    !specifiedRegionId.asText().equals(regionId)) {
+                throw new IllegalArgumentException(REGION_INVALID);
+            }
+
+            final Region region = codec(Region.class).decode(jsonTree, this);
+            regionAdminService.updateRegion(region.id(),
+                                region.name(), region.type(), region.masters());
+        } catch (IOException e) {
+            throw new IllegalArgumentException(e);
+        }
+
+        return Response.ok().build();
+    }
+
+    /**
+     * Removes the specified region using the given region identifier.
+     *
+     * @param regionId region identifier
+     * @return 200 OK, 404 not found
+     */
+    @DELETE
+    @Path("{regionId}")
+    @Produces(MediaType.APPLICATION_JSON)
+    public Response removeRegion(@PathParam("regionId") String regionId) {
+        final RegionId rid = RegionId.regionId(regionId);
+        regionAdminService.removeRegion(rid);
+        return Response.ok().build();
+    }
+
+    /**
+     * Adds the specified collection of devices to the region.
+     *
+     * @param regionId region identifier
+     * @param stream deviceIds JSON stream
+     * @return status of the request - CREATED if the JSON is correct,
+     * BAD_REQUEST if the JSON is invalid
+     * @onos.rsModel RegionDeviceIds
+     */
+    @POST
+    @Path("{regionId}/devices")
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    public Response addDevices(@PathParam("regionId") String regionId,
+                               InputStream stream) {
+        final RegionId rid = RegionId.regionId(regionId);
+
+        URI location;
+        try {
+            regionAdminService.addDevices(rid, extractDeviceIds(stream));
+            location = new URI(rid.id());
+        } catch (IOException | URISyntaxException e) {
+            throw new IllegalArgumentException(e);
+        }
+
+        return Response.created(location).build();
+    }
+
+    /**
+     * Removes the specified collection of devices from the region.
+     *
+     * @param regionId region identifier
+     * @param stream deviceIds JSON stream
+     * @return 200 OK, 404 not found
+     * @onos.rsModel RegionDeviceIds
+     */
+    @DELETE
+    @Path("{regionId}/devices")
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    public Response removeDevices(@PathParam("regionId") String regionId,
+                                  InputStream stream) {
+        final RegionId rid = RegionId.regionId(regionId);
+
+        try {
+            regionAdminService.removeDevices(rid, extractDeviceIds(stream));
+        } catch (IOException e) {
+            throw new IllegalArgumentException(e);
+        }
+
+        return Response.ok().build();
+    }
+
+    /**
+     * Extracts device ids from a given JSON string.
+     *
+     * @param stream deviceIds JSON stream
+     * @return a set of device identifiers
+     * @throws IOException
+     */
+    private Set<DeviceId> extractDeviceIds(InputStream stream) throws IOException {
+        ObjectNode jsonTree = (ObjectNode) mapper().readTree(stream);
+        JsonNode deviceIdsJson = jsonTree.get("deviceIds");
+
+        if (deviceIdsJson == null || deviceIdsJson.size() == 0) {
+            throw new IllegalArgumentException(DEVICE_IDS_INVALID);
+        }
+
+        Set<DeviceId> deviceIds = Sets.newHashSet();
+        deviceIdsJson.forEach(did -> deviceIds.add(DeviceId.deviceId(did.asText())));
+
+        return deviceIds;
+    }
+}

+{
+  "type": "object",
+  "title": "region",
+  "required": [
+    "id",
+    "name",
+    "type",
+    "masters"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "example": "1"
+    },
+    "name": {
+      "type": "string",
+      "example": "region"
+    },
+    "type": {
+      "type": "string",
+      "example": "ROOM"
+    },
+    "masters": {
+      "type": "array",
+      "xml": {
+        "name": "masters",
+        "wrapped": true
+      },
+      "items": {
+        "type": "array",
+        "xml": {
+          "name": "masters",
+          "wrapped": true
+        },
+        "items": {
+          "type": "string",
+          "example": "1"
+        }
+      }
+    }
+  }
+}
\ No newline at end of file

+{
+  "type": "object",
+  "title": "deviceIds",
+  "required": [
+    "deviceIds"
+  ],
+  "properties": {
+    "deviceIds": {
+      "type": "array",
+      "xml": {
+        "name": "deviceIds",
+        "wrapped": true
+      },
+      "items": {
+        "type": "string",
+        "example": "of:0000000000000001"
+      }
+    }
+  }
+}
\ No newline at end of file

+{
+  "type": "object",
+  "title": "region",
+  "required": [
+    "id",
+    "name",
+    "type",
+    "masters"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "example": "1"
+    },
+    "name": {
+      "type": "string",
+      "example": "region"
+    },
+    "type": {
+      "type": "string",
+      "example": "ROOM"
+    },
+    "masters": {
+      "type": "array",
+      "xml": {
+        "name": "masters",
+        "wrapped": true
+      },
+      "items": {
+        "type": "array",
+        "xml": {
+          "name": "masters",
+          "wrapped": true
+        },
+        "items": {
+          "type": "string",
+          "example": "1"
+        }
+      }
+    }
+  }
+}

+{
+  "type": "object",
+  "title": "regions",
+  "required": [
+    "regions"
+  ],
+  "properties": {
+    "regions": {
+      "type": "array",
+      "xml": {
+        "name": "regions",
+        "wrapped": true
+      },
+      "items": {
+        "type": "object",
+        "title": "region",
+        "required": [
+          "id",
+          "name",
+          "type",
+          "masters"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "example": "1"
+          },
+          "name": {
+            "type": "string",
+            "example": "region"
+          },
+          "type": {
+            "type": "string",
+            "example": "ROOM"
+          },
+          "masters": {
+            "type": "array",
+            "xml": {
+              "name": "masters",
+              "wrapped": true
+            },
+            "items": {
+              "type": "array",
+              "xml": {
+                "name": "masters",
+                "wrapped": true
+              },
+              "items": {
+                "type": "string",
+                "example": "1"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
\ No newline at end of file

+{
+  "id": 1,
+  "type": "ROOM",
+  "name": "foo",
+  "masters": [
+    [
+      "1"
+    ],
+    [
+      "1", "2"
+    ]
+  ]
+}
\ No newline at end of file

+{
+  "deviceIds": [
+    "of:0000000000000001",
+    "of:0000000000000002",
+    "of:0000000000000003"
+  ]
+}
\ No newline at end of file