gerrit.onap Code Review - policy/clamp.git/blob

   1 /*-
   2  * ============LICENSE_START=======================================================
   3  *  Copyright (C) 2021 Nordix Foundation.
   4  * ================================================================================
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *      http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  * SPDX-License-Identifier: Apache-2.0
  18  * ============LICENSE_END=========================================================
  19  */
  20
  21 package org.onap.policy.clamp.controlloop.runtime.instantiation.rest;
  22
  23 import io.swagger.annotations.ApiOperation;
  24 import io.swagger.annotations.ApiParam;
  25 import io.swagger.annotations.ApiResponse;
  26 import io.swagger.annotations.ApiResponses;
  27 import io.swagger.annotations.Authorization;
  28 import io.swagger.annotations.Extension;
  29 import io.swagger.annotations.ExtensionProperty;
  30 import io.swagger.annotations.ResponseHeader;
  31 import java.util.UUID;
  32 import javax.ws.rs.DELETE;
  33 import javax.ws.rs.GET;
  34 import javax.ws.rs.HeaderParam;
  35 import javax.ws.rs.POST;
  36 import javax.ws.rs.PUT;
  37 import javax.ws.rs.Path;
  38 import javax.ws.rs.QueryParam;
  39 import javax.ws.rs.core.Response;
  40 import javax.ws.rs.core.Response.Status;
  41 import org.onap.policy.clamp.controlloop.common.exception.ControlLoopException;
  42 import org.onap.policy.clamp.controlloop.models.controlloop.concepts.ControlLoops;
  43 import org.onap.policy.clamp.controlloop.models.messages.rest.instantiation.InstantiationCommand;
  44 import org.onap.policy.clamp.controlloop.models.messages.rest.instantiation.InstantiationResponse;
  45 import org.onap.policy.clamp.controlloop.runtime.instantiation.ControlLoopInstantiationProvider;
  46 import org.onap.policy.clamp.controlloop.runtime.instantiation.InstantiationHandler;
  47 import org.onap.policy.clamp.controlloop.runtime.main.rest.RestController;
  48 import org.onap.policy.models.base.PfModelException;
  49 import org.onap.policy.models.base.PfModelRuntimeException;
  50 import org.onap.policy.models.errors.concepts.ErrorResponseInfo;
  51 import org.slf4j.Logger;
  52 import org.slf4j.LoggerFactory;
  53
  54 /**
  55  * Class to provide REST end points for creating, deleting, query and commanding a control loop definition.
  56  */
  57 public class InstantiationController extends RestController {
  58
  59     private static final Logger LOGGER = LoggerFactory.getLogger(InstantiationController.class);
  60
  61     // The CL provider for instantiation requests
  62     private final ControlLoopInstantiationProvider provider;
  63
  64     /**
  65      * create Instantiation Controller.
  66      */
  67     public InstantiationController() {
  68         this.provider = InstantiationHandler.getInstance().getControlLoopInstantiationProvider();
  69     }
  70
  71     /**
  72      * Creates a control loop.
  73      *
  74      * @param requestId request ID used in ONAP logging
  75      * @param controlLoops the control loops
  76      * @return a response
  77      */
  78     // @formatter:off
  79     @POST
  80     @Path("/instantiation")
  81     @ApiOperation(
  82             value = "Commissions control loop definitions",
  83             notes = "Commissions control loop definitions, returning the control loop IDs",
  84             response = InstantiationResponse.class,
  85             tags = {"Control Loop Instantiation API"},
  86             authorizations = @Authorization(value = AUTHORIZATION_TYPE),
  87             responseHeaders = {
  88                 @ResponseHeader(
  89                     name = VERSION_MINOR_NAME,
  90                     description = VERSION_MINOR_DESCRIPTION,
  91                     response = String.class),
  92                 @ResponseHeader(
  93                     name = VERSION_PATCH_NAME,
  94                     description = VERSION_PATCH_DESCRIPTION,
  95                     response = String.class),
  96                 @ResponseHeader(
  97                     name = VERSION_LATEST_NAME,
  98                     description = VERSION_LATEST_DESCRIPTION,
  99                     response = String.class),
 100                 @ResponseHeader(
 101                     name = REQUEST_ID_NAME,
 102                     description = REQUEST_ID_HDR_DESCRIPTION,
 103                     response = UUID.class)
 104                 },
 105             extensions = {
 106                 @Extension
 107                     (
 108                         name = EXTENSION_NAME,
 109                         properties = {
 110                             @ExtensionProperty(name = API_VERSION_NAME, value = API_VERSION),
 111                             @ExtensionProperty(name = LAST_MOD_NAME, value = LAST_MOD_RELEASE)
 112                         }
 113                     )
 114             }
 115         )
 116     @ApiResponses(
 117             value = {
 118                 @ApiResponse(code = AUTHENTICATION_ERROR_CODE, message = AUTHENTICATION_ERROR_MESSAGE),
 119                 @ApiResponse(code = AUTHORIZATION_ERROR_CODE, message = AUTHORIZATION_ERROR_MESSAGE),
 120                 @ApiResponse(code = SERVER_ERROR_CODE, message = SERVER_ERROR_MESSAGE)
 121             }
 122         )
 123     // @formatter:on
 124     public Response create(
 125             @HeaderParam(REQUEST_ID_NAME) @ApiParam(REQUEST_ID_PARAM_DESCRIPTION) UUID requestId,
 126             @ApiParam(value = "Entity Body of Control Loop", required = true) ControlLoops controlLoops) {
 127
 128         try {
 129             InstantiationResponse response = provider.createControlLoops(controlLoops);
 130             return addLoggingHeaders(addVersionControlHeaders(Response.status(Status.OK)), requestId).entity(response)
 131                     .build();
 132
 133         } catch (PfModelRuntimeException | PfModelException e) {
 134             LOGGER.warn("creation of control loop failed", e);
 135             return createInstantiationErrorResponse(e, requestId);
 136         }
 137     }
 138
 139     /**
 140      * Queries details of all control loops.
 141      *
 142      * @param requestId request ID used in ONAP logging
 143      * @param name the name of the control loop to get, null for all control loops
 144      * @param version the version of the control loop to get, null for all control loops
 145      * @return the control loops
 146      */
 147     // @formatter:off
 148     @GET
 149     @Path("/instantiation")
 150     @ApiOperation(value = "Query details of the requested control loops",
 151             notes = "Queries details of the requested control loops, returning all control loop details",
 152             response = ControlLoops.class,
 153             tags = {
 154                 "Clamp control loop Instantiation API"
 155             },
 156             authorizations = @Authorization(value = AUTHORIZATION_TYPE),
 157             responseHeaders = {
 158                 @ResponseHeader(
 159                     name = VERSION_MINOR_NAME, description = VERSION_MINOR_DESCRIPTION,
 160                     response = String.class),
 161                 @ResponseHeader(name = VERSION_PATCH_NAME, description = VERSION_PATCH_DESCRIPTION,
 162                     response = String.class),
 163                 @ResponseHeader(name = VERSION_LATEST_NAME, description = VERSION_LATEST_DESCRIPTION,
 164                     response = String.class),
 165                 @ResponseHeader(name = REQUEST_ID_NAME, description = REQUEST_ID_HDR_DESCRIPTION,
 166                     response = UUID.class)},
 167             extensions = {
 168                 @Extension
 169                      (
 170                          name = EXTENSION_NAME,
 171                          properties = {
 172                              @ExtensionProperty(name = API_VERSION_NAME, value = API_VERSION),
 173                              @ExtensionProperty(name = LAST_MOD_NAME, value = LAST_MOD_RELEASE)
 174                          }
 175                     )
 176                 }
 177         )
 178     @ApiResponses(
 179             value = {
 180                 @ApiResponse(code = AUTHENTICATION_ERROR_CODE, message = AUTHENTICATION_ERROR_MESSAGE),
 181                 @ApiResponse(code = AUTHORIZATION_ERROR_CODE, message = AUTHORIZATION_ERROR_MESSAGE),
 182                 @ApiResponse(code = SERVER_ERROR_CODE, message = SERVER_ERROR_MESSAGE)
 183             }
 184         )
 185     // @formatter:on
 186     public Response query(
 187             @HeaderParam(REQUEST_ID_NAME) @ApiParam(REQUEST_ID_PARAM_DESCRIPTION) UUID requestId,
 188             @ApiParam(value = "Control Loop definition name", required = true) @QueryParam("name") String name,
 189             @ApiParam(value = "Control Loop definition version",
 190                     required = true) @QueryParam("version") String version) {
 191
 192         try {
 193             var response = provider.getControlLoops(name, version);
 194             return addLoggingHeaders(addVersionControlHeaders(Response.status(Status.OK)), requestId).entity(response)
 195                     .build();
 196
 197         } catch (PfModelRuntimeException | PfModelException e) {
 198             LOGGER.warn("commisssioning of control loop failed", e);
 199             return createInstantiationErrorResponse(e, requestId);
 200         }
 201
 202     }
 203
 204     /**
 205      * Updates a control loop.
 206      *
 207      * @param requestId request ID used in ONAP logging
 208      * @param controlLoops the control loops
 209      * @return a response
 210      */
 211     // @formatter:off
 212     @PUT
 213     @Path("/instantiation")
 214     @ApiOperation(
 215             value = "Updates control loop definitions",
 216             notes = "Updates control loop definitions, returning the updated control loop definition IDs",
 217             response = InstantiationResponse.class,
 218             tags = {
 219                 "Control Loop Instantiation API"
 220                 },
 221             authorizations = @Authorization(value = AUTHORIZATION_TYPE),
 222             responseHeaders = {
 223                 @ResponseHeader(
 224                     name = VERSION_MINOR_NAME,
 225                     description = VERSION_MINOR_DESCRIPTION,
 226                     response = String.class),
 227                 @ResponseHeader(
 228                     name = VERSION_PATCH_NAME,
 229                     description = VERSION_PATCH_DESCRIPTION,
 230                     response = String.class),
 231                 @ResponseHeader(
 232                     name = VERSION_LATEST_NAME,
 233                     description = VERSION_LATEST_DESCRIPTION,
 234                     response = String.class),
 235                 @ResponseHeader(
 236                     name = REQUEST_ID_NAME,
 237                     description = REQUEST_ID_HDR_DESCRIPTION,
 238                     response = UUID.class)
 239             },
 240             extensions = {
 241                 @Extension
 242                     (
 243                         name = EXTENSION_NAME,
 244                         properties = {
 245                             @ExtensionProperty(name = API_VERSION_NAME, value = API_VERSION),
 246                             @ExtensionProperty(name = LAST_MOD_NAME, value = LAST_MOD_RELEASE)
 247                         }
 248                     )
 249             }
 250         )
 251     @ApiResponses(
 252             value = {
 253                 @ApiResponse(code = AUTHENTICATION_ERROR_CODE, message = AUTHENTICATION_ERROR_MESSAGE),
 254                 @ApiResponse(code = AUTHORIZATION_ERROR_CODE, message = AUTHORIZATION_ERROR_MESSAGE),
 255                 @ApiResponse(code = SERVER_ERROR_CODE, message = SERVER_ERROR_MESSAGE)
 256             }
 257         )
 258     // @formatter:on
 259     public Response update(
 260             @HeaderParam(REQUEST_ID_NAME) @ApiParam(REQUEST_ID_PARAM_DESCRIPTION) UUID requestId,
 261             @ApiParam(value = "Entity Body of Control Loop", required = true) ControlLoops controlLoops) {
 262
 263         try {
 264             InstantiationResponse response = provider.updateControlLoops(controlLoops);
 265             return addLoggingHeaders(addVersionControlHeaders(Response.status(Status.OK)), requestId).entity(response)
 266                     .build();
 267
 268         } catch (PfModelRuntimeException | PfModelException e) {
 269             LOGGER.warn("update of control loops failed", e);
 270             return createInstantiationErrorResponse(e, requestId);
 271         }
 272     }
 273
 274     /**
 275      * Deletes a control loop definition.
 276      *
 277      * @param requestId request ID used in ONAP logging
 278      * @param name the name of the control loop to delete
 279      * @param version the version of the control loop to delete
 280      * @return a response
 281      */
 282     // @formatter:off
 283     @DELETE
 284     @Path("/instantiation")
 285     @ApiOperation(value = "Delete a control loop",
 286             notes = "Deletes a control loop, returning optional error details",
 287             response = InstantiationResponse.class,
 288             tags = {
 289                 "Clamp Control Loop Instantiation API"
 290                 },
 291             authorizations = @Authorization(value = AUTHORIZATION_TYPE),
 292             responseHeaders = {
 293                 @ResponseHeader(
 294                     name = VERSION_MINOR_NAME,
 295                     description = VERSION_MINOR_DESCRIPTION,
 296                     response = String.class),
 297                 @ResponseHeader(
 298                     name = VERSION_PATCH_NAME,
 299                     description = VERSION_PATCH_DESCRIPTION,
 300                     response = String.class),
 301                 @ResponseHeader(
 302                     name = VERSION_LATEST_NAME,
 303                     description = VERSION_LATEST_DESCRIPTION,
 304                     response = String.class),
 305                 @ResponseHeader(
 306                     name = REQUEST_ID_NAME,
 307                     description = REQUEST_ID_HDR_DESCRIPTION,
 308                     response = UUID.class)},
 309             extensions = {
 310                 @Extension
 311                     (
 312                         name = EXTENSION_NAME,
 313                         properties = {
 314                             @ExtensionProperty(name = API_VERSION_NAME, value = API_VERSION),
 315                             @ExtensionProperty(name = LAST_MOD_NAME, value = LAST_MOD_RELEASE)
 316                         }
 317                     )
 318                 }
 319         )
 320     @ApiResponses(
 321         value = {
 322             @ApiResponse(code = AUTHENTICATION_ERROR_CODE, message = AUTHENTICATION_ERROR_MESSAGE),
 323             @ApiResponse(code = AUTHORIZATION_ERROR_CODE, message = AUTHORIZATION_ERROR_MESSAGE),
 324             @ApiResponse(code = SERVER_ERROR_CODE, message = SERVER_ERROR_MESSAGE)
 325         }
 326     )
 327     // @formatter:on
 328
 329     public Response delete(
 330             @HeaderParam(REQUEST_ID_NAME) @ApiParam(REQUEST_ID_PARAM_DESCRIPTION) UUID requestId,
 331             @ApiParam(value = "Control Loop definition name", required = true) @QueryParam("name") String name,
 332             @ApiParam(value = "Control Loop definition version", required = true)
 333                     @QueryParam("version") String version) {
 334
 335         try {
 336             InstantiationResponse response = provider.deleteControlLoop(name, version);
 337             return addLoggingHeaders(addVersionControlHeaders(Response.status(Status.OK)), requestId).entity(response)
 338                     .build();
 339
 340         } catch (PfModelRuntimeException | PfModelException e) {
 341             LOGGER.warn("delete of control loop failed", e);
 342             return createInstantiationErrorResponse(e, requestId);
 343         }
 344     }
 345
 346     /**
 347      * Issues control loop commands to control loops.
 348      *
 349      * @param requestId request ID used in ONAP logging
 350      * @param command the command to issue to control loops
 351      * @return the control loop definitions
 352      */
 353     // @formatter:off
 354     @PUT
 355     @Path("/instantiation/command")
 356     @ApiOperation(value = "Issue a command to the requested control loops",
 357             notes = "Issues a command to a control loop, ordering a state change on the control loop",
 358             response = InstantiationResponse.class,
 359             tags = {
 360                 "Clamp Control Loop Instantiation API"
 361             },
 362             authorizations = @Authorization(value = AUTHORIZATION_TYPE),
 363             responseHeaders = {
 364                 @ResponseHeader(
 365                     name = VERSION_MINOR_NAME, description = VERSION_MINOR_DESCRIPTION,
 366                     response = String.class),
 367                 @ResponseHeader(name = VERSION_PATCH_NAME, description = VERSION_PATCH_DESCRIPTION,
 368                     response = String.class),
 369                 @ResponseHeader(name = VERSION_LATEST_NAME, description = VERSION_LATEST_DESCRIPTION,
 370                     response = String.class),
 371                 @ResponseHeader(name = REQUEST_ID_NAME, description = REQUEST_ID_HDR_DESCRIPTION,
 372                     response = UUID.class)},
 373             extensions = {
 374                 @Extension
 375                     (
 376                         name = EXTENSION_NAME,
 377                         properties = {
 378                             @ExtensionProperty(name = API_VERSION_NAME, value = API_VERSION),
 379                             @ExtensionProperty(name = LAST_MOD_NAME, value = LAST_MOD_RELEASE)
 380                         }
 381                     )
 382                 }
 383         )
 384     @ApiResponses(
 385             value = {
 386                 @ApiResponse(code = AUTHENTICATION_ERROR_CODE, message = AUTHENTICATION_ERROR_MESSAGE),
 387                 @ApiResponse(code = AUTHORIZATION_ERROR_CODE, message = AUTHORIZATION_ERROR_MESSAGE),
 388                 @ApiResponse(code = SERVER_ERROR_CODE, message = SERVER_ERROR_MESSAGE)
 389             }
 390         )
 391     // @formatter:on
 392     public Response issueControlLoopCommand(
 393             @HeaderParam(REQUEST_ID_NAME) @ApiParam(REQUEST_ID_PARAM_DESCRIPTION) UUID requestId,
 394             @ApiParam(value = "Entity Body of control loop command", required = true) InstantiationCommand command) {
 395
 396         try {
 397             InstantiationResponse response = provider.issueControlLoopCommand(command);
 398             return addLoggingHeaders(addVersionControlHeaders(Response.status(Status.ACCEPTED)), requestId)
 399                     .entity(response).build();
 400
 401         } catch (PfModelRuntimeException | PfModelException | ControlLoopException e) {
 402             LOGGER.warn("creation of control loop failed", e);
 403             return createInstantiationErrorResponse(e, requestId);
 404         }
 405     }
 406
 407     /**
 408      * create a Instantiation Response from an exception.
 409      * @param e the error
 410      * @param requestId request ID used in ONAP logging
 411      * @return the Instantiation Response
 412      */
 413     private Response createInstantiationErrorResponse(ErrorResponseInfo e, UUID requestId) {
 414         var resp = new InstantiationResponse();
 415         resp.setErrorDetails(e.getErrorResponse().getErrorMessage());
 416         return addLoggingHeaders(addVersionControlHeaders(Response.status(e.getErrorResponse().getResponseCode())),
 417             requestId).entity(resp).build();
 418     }
 419 }
 420