gerrit.onap Code Review - portal/sdk.git/blob

   1 /*-
   2  * ================================================================================
   3  * ECOMP Portal SDK
   4  * ================================================================================
   5  * Copyright (C) 2017 AT&T Intellectual Property
   6  * ================================================================================
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  * ================================================================================
  19  */
  20 package org.openecomp.portalsdk.core.onboarding.crossapi;
  21
  22 import java.util.List;
  23
  24 import javax.servlet.http.HttpServletRequest;
  25
  26 import org.openecomp.portalsdk.core.onboarding.exception.PortalAPIException;
  27 import org.openecomp.portalsdk.core.restful.domain.EcompRole;
  28 import org.openecomp.portalsdk.core.restful.domain.EcompUser;
  29
  30 /**
  31  * Defines the REST API Interface that an on-boarding application must implement
  32  * to answer queries and accept updates from the ECOMP Portal about the
  33  * application's users, roles and user-role assignments.
  34  */
  35 public interface IPortalRestAPIService {
  36
  37         // EcompUser Interface
  38
  39         /**
  40          * Creates a user with the specified details. If any error occurs, for
  41          * example the user exists, the method should throw PortalApiException with
  42          * an appropriate message. The FW library will catch the exception and send
  43          * an appropriate response to Portal.
  44          *
  45          * @param user
  46          *            Model object with attributes of user to be created.
  47          * @throws PortalAPIException
  48          *             If any error occurs while processing the request; for
  49          *             example, user exists.
  50          */
  51         public void pushUser(EcompUser user) throws PortalAPIException;
  52
  53         /**
  54          * Updates details about the user with the specified loginId. For example,
  55          * mark user as inactive. If any error occurs, the method should throw
  56          * PortalApiException with an appropriate message. The FW library will catch
  57          * the exception and send an appropriate response to Portal.
  58          *
  59          * @param loginId
  60          *            EcompUser ID to be updated.
  61          * @param user
  62          *            Model object with attributes of user to be updated.
  63          * @throws PortalAPIException
  64          *             If any error occurs while processing the request; for
  65          *             example, unknown user.
  66          */
  67         public void editUser(String loginId, EcompUser user) throws PortalAPIException;
  68
  69         /**
  70          * Gets and returns the user object with the specified loginId. If any error
  71          * occurs, the method should throw PortalApiException with an appropriate
  72          * message. The FW library will catch the exception and send an appropriate
  73          * response to Portal
  74          *
  75          * @param loginId
  76          *            EcompUser ID to be fetched
  77          * @return Model object with user attributes.
  78          * @throws PortalAPIException
  79          *             If any error occurs while processing the request; for
  80          *             example, unknown user.
  81          */
  82         public EcompUser getUser(String loginId) throws PortalAPIException;
  83
  84         /**
  85          * Gets and returns a list of active users. If any error occurs, the method
  86          * should throw PortalApiException with an appropriate message. The FW
  87          * library will catch the exception and send an appropriate response to
  88          * Portal.
  89          *
  90          * @return List of user attribute model objects; empty list if none are
  91          *         found.
  92          * @throws PortalAPIException
  93          *             If any error occurs while processing the request.
  94          */
  95         public List<EcompUser> getUsers() throws PortalAPIException;
  96
  97         // Roles Interface
  98
  99         /**
 100          * Gets and returns a list of active roles. If any error occurs, the method
 101          * should throw PortalApiException with an appropriate message. The FW
 102          * library will catch the exception and send an appropriate response to
 103          * Portal.
 104          *
 105          * @return List of role attribute objects; empty list if none are found.
 106          * @throws PortalAPIException
 107          *             If an unexpected error occurs while processing the request.
 108          */
 109         public List<EcompRole> getAvailableRoles() throws PortalAPIException;
 110
 111         /**
 112          * Updates roles for the user with the specified loginId to the list of
 113          * roles provided as the second argument. After this operation, the should
 114          * have ONLY the roles provided in the list above. For example, if user had
 115          * roles r1, r2 and r3; and a call was made to pushUserRole with a list
 116          * containing only roles r3 and r4, this method should leave the user with
 117          * roles r3 and r4 since those were the ONLY roles provided in second
 118          * argument. If any error occurs, the method should throw PortalApiException
 119          * with an appropriate message. The FW library will catch the exception and
 120          * send an appropriate response to Portal.
 121          *
 122          * @param loginId
 123          *            EcompUser ID to be updated.
 124          * @param roles
 125          *            List of role attribute objects
 126          * @throws PortalAPIException
 127          *             If any error occurs while processing the request.
 128          */
 129         public void pushUserRole(String loginId, List<EcompRole> roles) throws PortalAPIException;
 130
 131         /**
 132          * Gets and returns a list of roles for the user with the specified loginId.
 133          * If any error occurs, the method should throw PortalApiException with an
 134          * appropriate message. The FW library will catch the exception and send an
 135          * appropriate response to Portal.
 136          *
 137          * @param loginId
 138          * @return List of model objects; empty if no roles are found.
 139          * @throws PortalAPIException
 140          *             If any error occurs while processing the request; e.g., user
 141          *             not found.
 142          */
 143         public List<EcompRole> getUserRoles(String loginId) throws PortalAPIException;
 144
 145         // Security Interface
 146
 147         /**
 148          * Should return true if the call should be allowed and false if not.
 149          * Currently Portal sends two headers of username and password in each
 150          * request which the app should check. If match, return true; else return
 151          * false. If any error occurs, the method should throw PortalApiException
 152          * with an appropriate message. The FW library will catch the exception and
 153          * send an appropriate response to Portal.
 154          *
 155          * @param request
 156          * @return true if the request contains appropriate credentials, else false.
 157          * @throws PortalAPIException
 158          *             If an unexpected error occurs while processing the request.
 159          */
 160         public boolean isAppAuthenticated(HttpServletRequest request) throws PortalAPIException;
 161
 162         /**
 163          * Gets and returns the userId for the logged-in user based on the request.
 164          * If any error occurs, the method should throw PortalApiException with an
 165          * appropriate message. The FW library will catch the exception and send an
 166          * appropriate response to Portal.
 167          *
 168          * @param request
 169          * @return true if the request contains appropriate credentials, else false.
 170          * @throws PortalAPIException
 171          *             If an unexpected error occurs while processing the request.
 172          */
 173         public String getUserId(HttpServletRequest request) throws PortalAPIException;
 174
 175 }