git.opendaylight Code Review - vtn.git/blob

   1 /*
   2  * Copyright (c) 2014-2015 NEC Corporation
   3  * All rights reserved.
   4  *
   5  * This program and the accompanying materials are made available under the
   6  * terms of the Eclipse Public License v1.0 which accompanies this
   7  * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html
   8  */
   9
  10 package org.opendaylight.vtn.manager.northbound;
  11
  12 import static java.net.HttpURLConnection.HTTP_BAD_REQUEST;
  13 import static java.net.HttpURLConnection.HTTP_CREATED;
  14 import static java.net.HttpURLConnection.HTTP_INTERNAL_ERROR;
  15 import static java.net.HttpURLConnection.HTTP_NOT_FOUND;
  16 import static java.net.HttpURLConnection.HTTP_NO_CONTENT;
  17 import static java.net.HttpURLConnection.HTTP_OK;
  18 import static java.net.HttpURLConnection.HTTP_UNAUTHORIZED;
  19 import static java.net.HttpURLConnection.HTTP_UNAVAILABLE;
  20 import static java.net.HttpURLConnection.HTTP_UNSUPPORTED_TYPE;
  21
  22 import javax.ws.rs.Consumes;
  23 import javax.ws.rs.DELETE;
  24 import javax.ws.rs.GET;
  25 import javax.ws.rs.PUT;
  26 import javax.ws.rs.Path;
  27 import javax.ws.rs.PathParam;
  28 import javax.ws.rs.Produces;
  29 import javax.ws.rs.core.Context;
  30 import javax.ws.rs.core.MediaType;
  31 import javax.ws.rs.core.Response;
  32 import javax.ws.rs.core.UriInfo;
  33
  34 import org.codehaus.enunciate.jaxrs.ResponseCode;
  35 import org.codehaus.enunciate.jaxrs.ResponseHeader;
  36 import org.codehaus.enunciate.jaxrs.ResponseHeaders;
  37 import org.codehaus.enunciate.jaxrs.StatusCodes;
  38 import org.codehaus.enunciate.jaxrs.TypeHint;
  39
  40 import org.opendaylight.vtn.manager.VTenantPath;
  41 import org.opendaylight.vtn.manager.flow.filter.FlowFilter;
  42 import org.opendaylight.vtn.manager.flow.filter.FlowFilterId;
  43
  44 /**
  45  * This class provides Northbound REST APIs to handle flow filter in the
  46  * VTN.
  47  *
  48  * <p>
  49  *   Each VTN has a list of flow filters. Flow filters in the VTN flow filter
  50  *   list are evaluated when an incoming packet is mapped to the VTN.
  51  *   Note that the VTN flow filter list is evaluated only once before other
  52  *   flow filter lists are evaluated.
  53  * </p>
  54  *
  55  * @since Helium
  56  */
  57 @Path("/default/vtns/{tenantName}/flowfilters")
  58 public class VTenantFlowFilterNorthbound extends VTNNorthBoundBase {
  59     /**
  60      * Return information about flow filters configured in the specified VTN.
  61      *
  62      * @param tenantName  The name of the VTN.
  63      * @return
  64      *   <strong>flowfilters</strong> element contains information about the
  65      *   VTN flow filter list specified by the requested URI.
  66      */
  67     @GET
  68     @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
  69     @TypeHint(FlowFilterList.class)
  70     @StatusCodes({
  71         @ResponseCode(code = HTTP_OK,
  72                       condition = "Operation completed successfully."),
  73         @ResponseCode(code = HTTP_UNAUTHORIZED,
  74                       condition = "User is not authorized to perform this " +
  75                       "operation."),
  76         @ResponseCode(code = HTTP_NOT_FOUND,
  77                       condition = "The specified VTN does not exist."),
  78         @ResponseCode(code = HTTP_INTERNAL_ERROR,
  79                       condition = "Fatal internal error occurred in the " +
  80                       "VTN Manager."),
  81         @ResponseCode(code = HTTP_UNAVAILABLE,
  82                       condition = "One or more of mandatory controller " +
  83                       "services, such as the VTN Manager, are unavailable.")})
  84     public FlowFilterList getFlowFilters(
  85             @PathParam("tenantName") String tenantName) {
  86         return getFlowFilters(createFlowFilterId(tenantName));
  87     }
  88
  89     /**
  90      * Delete all flow filters in the VTN flow filter list.
  91      *
  92      * @param tenantName  The name of the VTN.
  93      * @return Response as dictated by the HTTP Response Status code.
  94      */
  95     @DELETE
  96     @TypeHint(TypeHint.NO_CONTENT.class)
  97     @StatusCodes({
  98         @ResponseCode(code = HTTP_OK,
  99                       condition = "Flow filters were deleted successfully."),
 100         @ResponseCode(code = HTTP_NO_CONTENT,
 101                       condition = "No flow filter was configured in the " +
 102                       "specified VTN."),
 103         @ResponseCode(code = HTTP_UNAUTHORIZED,
 104                       condition = "User is not authorized to perform this " +
 105                       "operation."),
 106         @ResponseCode(code = HTTP_NOT_FOUND,
 107                       condition = "The specified VTN does not exist."),
 108         @ResponseCode(code = HTTP_INTERNAL_ERROR,
 109                       condition = "Fatal internal error occurred in the " +
 110                       "VTN Manager."),
 111         @ResponseCode(code = HTTP_UNAVAILABLE,
 112                       condition = "One or more of mandatory controller " +
 113                       "services, such as the VTN Manager, are unavailable.")})
 114     public Response deleteFlowFilters(
 115             @PathParam("tenantName") String tenantName) {
 116         return deleteFlowFilters(createFlowFilterId(tenantName));
 117     }
 118
 119     /**
 120      * Return information about the flow filter specified by the
 121      * flow filter index in the VTN flow filter list.
 122      *
 123      * @param tenantName  The name of the VTN.
 124      * @param index
 125      *   The index value which specifies the flow filter in the VTN flow filter
 126      *   list. A string representation of an integer value must be specified.
 127      * @return
 128      *   <strong>flowfilter</strong> element contains information about the
 129      *   flow filter specified by the requested URI.
 130      */
 131     @Path("{index}")
 132     @GET
 133     @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 134     @TypeHint(FlowFilter.class)
 135     @StatusCodes({
 136         @ResponseCode(code = HTTP_OK,
 137                       condition = "Operation completed successfully."),
 138         @ResponseCode(code = HTTP_NO_CONTENT,
 139                       condition = "The specified flow filter does not exist " +
 140                       "in the specified VTN."),
 141         @ResponseCode(code = HTTP_UNAUTHORIZED,
 142                       condition = "User is not authorized to perform this " +
 143                       "operation."),
 144         @ResponseCode(code = HTTP_NOT_FOUND,
 145                       condition = "<ul>" +
 146                       "<li>The specified VTN does not exist.</li>" +
 147                       "<li>A string passed to <u>{index}</u> can not be " +
 148                       "converted into an integer.</li>" +
 149                       "</ul>"),
 150         @ResponseCode(code = HTTP_INTERNAL_ERROR,
 151                       condition = "Fatal internal error occurred in the " +
 152                       "VTN Manager."),
 153         @ResponseCode(code = HTTP_UNAVAILABLE,
 154                       condition = "One or more of mandatory controller " +
 155                       "services, such as the VTN Manager, are unavailable.")})
 156     public FlowFilter getFlowFilter(
 157             @PathParam("tenantName") String tenantName,
 158             @PathParam("index") int index) {
 159         return getFlowFilter(createFlowFilterId(tenantName), index);
 160     }
 161
 162     /**
 163      * Create or modify the flow filter specified by the index number in the
 164      * VTN flow filter list.
 165      *
 166      * <ul>
 167      *   <li>
 168      *     If the flow filter specified by
 169      *     <span style="text-decoration: underline;">{index}</span> does not
 170      *     exist, a new flow filter will be associated with
 171      *     <span style="text-decoration: underline;">{index}</span> in the
 172      *     VTN flow filter list.
 173      *   </li>
 174      *   <li>
 175      *     If the flow filter specified by
 176      *     <span style="text-decoration: underline;">{index}</span> already
 177      *     exists, it will be modified as specified by
 178      *     <strong>flowfilter</strong> element.
 179      *   </li>
 180      * </ul>
 181      *
 182      * @param uriInfo     Requested URI information.
 183      * @param tenantName  The name of the VTN.
 184      * @param index
 185      *   The index value which specifies the flow filter in the VTN flow filter
 186      *   list.
 187      *   <ul>
 188      *     <li>
 189      *       A string representation of an integer value must be specified.
 190      *     </li>
 191      *     <li>
 192      *       The range of value that can be specified is from
 193      *       <strong>1</strong> to <strong>65535</strong>.
 194      *     </li>
 195      *     <li>
 196      *       This value is also used to determine the order of flow filter
 197      *       evaluation. Flow filters in the list are evaluated in ascending
 198      *       order of indices, and only the first matched flow filter is
 199      *       applied to the packet.
 200      *     </li>
 201      *   </ul>
 202      * @param ff
 203      *   <strong>flowfilter</strong> element specifies the configuration of the
 204      *   flow filter.
 205      *   <ul>
 206      *     <li>
 207      *       The <strong>index</strong> attribute in the
 208      *       <strong>flowfilter</strong> element is always ignored.
 209      *       The index number is determined by the
 210      *       <span style="text-decoration: underline;">{index}</span>
 211      *       parameter.
 212      *     </li>
 213      *     <li>
 214      *       Note that this API does not check whether the flow condition
 215      *       specified by the <strong>condition</strong> attribute in
 216      *       the <strong>flowfilter</strong> element actually exists or not.
 217      *       The flow filter will be invalidated if the specified
 218      *       flow condition does not exist.
 219      *     </li>
 220      *     <li>
 221      *       Note that this API does not check whether the destination
 222      *       virtual interface of the packet redirection, which is configured
 223      *       in the <strong>redirect</strong> element in the
 224      *       <strong>flowfilter</strong> element, actually exists or not.
 225      *       The packet will be discarded if the destination virtual interface
 226      *       is not found when the packet is going to be redirected by the
 227      *       flow filter.
 228      *     </li>
 229      *   </ul>
 230      * @return Response as dictated by the HTTP Response Status code.
 231      */
 232     @Path("{index}")
 233     @PUT
 234     @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 235     @TypeHint(TypeHint.NO_CONTENT.class)
 236     @ResponseHeaders({
 237         @ResponseHeader(name = "Location",
 238                         description = "URI corresponding to the newly " +
 239                         "created flow filter, which is the same URI " +
 240                         "specified in request. This header is set only if " +
 241                         "CREATED(201) is returned as response code.")})
 242     @StatusCodes({
 243         @ResponseCode(code = HTTP_OK,
 244                       condition = "Existing flow filter was modified " +
 245                       "successfully."),
 246         @ResponseCode(code = HTTP_CREATED,
 247                       condition = "Flow filter was newly created " +
 248                       "successfully."),
 249         @ResponseCode(code = HTTP_NO_CONTENT,
 250                       condition = "Flow filter was not changed."),
 251         @ResponseCode(code = HTTP_BAD_REQUEST,
 252                       condition = "<ul>" +
 253                       "<li>Incorrect XML or JSON data is specified " +
 254                       "in Request body.</li>" +
 255                       "<li>Index number specified by <u>{index}</u> " +
 256                       "parameter is out of valid range.</li>" +
 257                       "<li>Incorrect value is configured in " +
 258                       "<strong>flowfilter</strong>.</li>" +
 259                       "</ul>"),
 260         @ResponseCode(code = HTTP_UNAUTHORIZED,
 261                       condition = "User is not authorized to perform this " +
 262                       "operation."),
 263         @ResponseCode(code = HTTP_NOT_FOUND,
 264                       condition = "<ul>" +
 265                       "<li>The specified VTN does not exist.</li>" +
 266                       "<li>A string passed to <u>{index}</u> can not be " +
 267                       "converted into an integer.</li>" +
 268                       "</ul>"),
 269         @ResponseCode(code = HTTP_UNSUPPORTED_TYPE,
 270                       condition = "Unsupported data type is specified in " +
 271                       "<strong>Content-Type</strong> header."),
 272         @ResponseCode(code = HTTP_INTERNAL_ERROR,
 273                       condition = "Fatal internal error occurred in the " +
 274                       "VTN Manager."),
 275         @ResponseCode(code = HTTP_UNAVAILABLE,
 276                       condition = "One or more of mandatory controller " +
 277                       "services, such as the VTN Manager, are unavailable.")})
 278     public Response putFlowFilter(
 279             @Context UriInfo uriInfo,
 280             @PathParam("tenantName") String tenantName,
 281             @PathParam("index") int index,
 282             @TypeHint(FlowFilter.class) FlowFilter ff) {
 283         return putFlowFilter(uriInfo, createFlowFilterId(tenantName), index,
 284                              ff);
 285     }
 286
 287     /**
 288      * Delete the flow filter specified by the index number in the VTN
 289      * flow filter list.
 290      *
 291      * @param tenantName  The name of the VTN.
 292      * @param index
 293      *   The index value which specifies the flow filter in the VTN flow filter
 294      *   list. A string representation of an integer value must be specified.
 295      * @return Response as dictated by the HTTP Response Status code.
 296      */
 297     @Path("{index}")
 298     @DELETE
 299     @TypeHint(TypeHint.NO_CONTENT.class)
 300     @StatusCodes({
 301         @ResponseCode(code = HTTP_OK,
 302                       condition = "Flow filter was deleted successfully."),
 303         @ResponseCode(code = HTTP_NO_CONTENT,
 304                       condition = "The specified flow filter does not exist " +
 305                       "in the specified VTN."),
 306         @ResponseCode(code = HTTP_UNAUTHORIZED,
 307                       condition = "User is not authorized to perform this " +
 308                       "operation."),
 309         @ResponseCode(code = HTTP_NOT_FOUND,
 310                       condition = "<ul>" +
 311                       "<li>The specified VTN does not exist.</li>" +
 312                       "<li>A string passed to <u>{index}</u> can not be " +
 313                       "converted into an integer.</li>" +
 314                       "</ul>"),
 315         @ResponseCode(code = HTTP_INTERNAL_ERROR,
 316                       condition = "Fatal internal error occurred in the " +
 317                       "VTN Manager."),
 318         @ResponseCode(code = HTTP_UNAVAILABLE,
 319                       condition = "One or more of mandatory controller " +
 320                       "services, such as the VTN Manager, are unavailable.")})
 321     public Response deleteFlowFilter(
 322             @PathParam("tenantName") String tenantName,
 323             @PathParam("index") int index) {
 324         return deleteFlowFilter(createFlowFilterId(tenantName), index);
 325     }
 326
 327     /**
 328      * Create a flow filter identifier that specifies the flow filter list
 329      * in the VTN.
 330      *
 331      * @param tenant  The name of the tenant.
 332      * @return  A {@link FlowFilterId} instance.
 333      */
 334     private FlowFilterId createFlowFilterId(String tenant) {
 335         VTenantPath path = new VTenantPath(tenant);
 336         return new FlowFilterId(path);
 337     }
 338 }