1 /* 2 * Copyright 2007 The Kuali Foundation Licensed under the Educational Community 3 * License, Version 1.0 (the "License"); you may not use this file except in 4 * compliance with the License. You may obtain a copy of the License at 5 * http://www.opensource.org/licenses/ecl1.php Unless required by applicable law 6 * or agreed to in writing, software distributed under the License is 7 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 8 * KIND, either express or implied. See the License for the specific language 9 * governing permissions and limitations under the License. 10 */ 11 package org.kuali.student.enrollment.exam.service; 12 13 import org.kuali.rice.core.api.criteria.QueryByCriteria; 14 import org.kuali.student.enrollment.exam.dto.ExamInfo; 15 import org.kuali.student.r2.common.util.constants.ExamServiceConstants; 16 import org.kuali.student.r2.common.dto.ContextInfo; 17 import org.kuali.student.r2.common.dto.StatusInfo; 18 import org.kuali.student.r2.common.dto.ValidationResultInfo; 19 import org.kuali.student.r2.common.exceptions.*; 20 21 import javax.jws.WebParam; 22 import javax.jws.WebService; 23 import javax.jws.soap.SOAPBinding; 24 import java.util.List; 25 26 /** 27 * Created with IntelliJ IDEA. 28 * User: Mezba Mahtab (mezba.mahtab@utoronto.ca) 29 * Date: 1/17/13 30 * Time: 3:11 PM 31 * 32 * Represents a canonical exam service. 33 */ 34 @WebService(name = "ExamService", targetNamespace = ExamServiceConstants.NAMESPACE) 35 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) 36 public interface ExamService { 37 38 /** 39 * Validates an Exam. Depending on the value of validationType, 40 * this validation could be limited to tests on just the current 41 * exam and its directly contained sub-objects or expanded to 42 * perform all tests related to this exam. If an identifier is 43 * present for the exam and a record is found for that identifier, the validation 44 * checks if the exam can be updated to the new values. If an identifier is not 45 * present or a record does not exist, the validation checks if the object 46 * with the given data can be created. 47 * 48 * @param validationTypeKey the identifier for the validation Type 49 * @param examTypeKey the identifier for the exam type to be validated 50 * @param examInfo the exam to be validated 51 * @param contextInfo information containing the principalId and 52 * locale information about the caller of 53 * service operation 54 * @return a list of validation results or an empty list if validation 55 * succeeded 56 * @throws DoesNotExistException validationTypeKey or examTypeKey is not found 57 * @throws InvalidParameterException examInfo or contextInfo is not valid 58 * @throws MissingParameterException validationTypeKey, examTypeKey, examInfo, or 59 * contextInfo is missing or null 60 * @throws OperationFailedException unable to complete request 61 * @throws PermissionDeniedException authorization failure 62 */ 63 public List<ValidationResultInfo> validateExam(@WebParam(name = "validationTypeKey") String validationTypeKey, 64 @WebParam(name = "examTypeKey") String examTypeKey, 65 @WebParam(name = "examInfo") ExamInfo examInfo, 66 @WebParam(name = "contextInfo") ContextInfo contextInfo) 67 throws DoesNotExistException, 68 InvalidParameterException, 69 MissingParameterException, 70 OperationFailedException, 71 PermissionDeniedException; 72 73 /** 74 * Creates a new Exam. 75 * 76 * @param examTypeKey a unique identifier for the Type of the new exam 77 * @param examInfo the data with which to create the exam 78 * @param contextInfo information containing the principalId and locale 79 * information about the caller of service operation 80 * @return the new exam created 81 * @throws DataValidationErrorException supplied data is invalid 82 * @throws DoesNotExistException examTypeKey does not exist or is not supported 83 * @throws InvalidParameterException examInfo or contextInfo is not valid 84 * @throws MissingParameterException examTypeKey, examInfo, or 85 * contextInfo is missing or null 86 * @throws OperationFailedException unable to complete request 87 * @throws PermissionDeniedException an authorization failure occurred 88 * @throws ReadOnlyException an attempt at supplying information designated as read only 89 */ 90 public ExamInfo createExam(@WebParam(name = "examTypeKey") String examTypeKey, 91 @WebParam(name = "examInfo") ExamInfo examInfo, 92 @WebParam(name = "contextInfo") ContextInfo contextInfo) 93 throws DataValidationErrorException, 94 DoesNotExistException, 95 InvalidParameterException, 96 MissingParameterException, 97 OperationFailedException, 98 PermissionDeniedException, 99 ReadOnlyException; 100 101 /** 102 * Retrieves information about an exam. 103 * 104 * @param examId the id of the exam 105 * @param contextInfo Context information containing the principalId and locale 106 * information about the caller of service operation 107 * @return an exam whose id matches the given id 108 * @throws DoesNotExistException if the exam does not exist 109 * @throws InvalidParameterException contextInfo is invalid 110 * @throws MissingParameterException examId or contextInfo are absent (missing or null) 111 * @throws OperationFailedException unable to complete request 112 * @throws PermissionDeniedException an authorization failure occured 113 */ 114 public ExamInfo getExam(@WebParam(name = "examId") String examId, 115 @WebParam(name = "contextInfo") ContextInfo contextInfo) 116 throws DoesNotExistException, 117 InvalidParameterException, 118 MissingParameterException, 119 OperationFailedException, 120 PermissionDeniedException; 121 122 /** 123 * Updates an existing exam. 124 * 125 * @param examId the identifier for the exam to be updated 126 * @param examInfo the new data for the exam 127 * @param contextInfo information containing the principalId and locale 128 * information about the caller of service operation 129 * @return the updated object 130 * @throws DataValidationErrorException supplied data is invalid (xml) 131 * @throws DoesNotExistException examId is not found 132 * @throws InvalidParameterException examInfo or contextInfo is not valid 133 * @throws MissingParameterException examId, examInfo or 134 * contextInfo is missing or null 135 * @throws OperationFailedException unable to complete request 136 * @throws PermissionDeniedException an authorization failure occurred 137 * @throws ReadOnlyException an attempt was made to change information designated as read only 138 * @throws VersionMismatchException an optimistic locking failure or the action was attempted on an out 139 * of data version 140 */ 141 public ExamInfo updateExam (@WebParam(name = "examId") String examId, 142 @WebParam(name = "examInfo") ExamInfo examInfo, 143 @WebParam(name = "contextInfo") ContextInfo contextInfo) 144 throws DataValidationErrorException, 145 DoesNotExistException, 146 InvalidParameterException, 147 MissingParameterException, 148 OperationFailedException, 149 PermissionDeniedException, 150 ReadOnlyException, 151 VersionMismatchException; 152 153 /** 154 * Deletes an existing exam. 155 * 156 * @param examId the identifier for the exam to be deleted 157 * @param contextInfo information containing the principalId and locale 158 * information about the caller of service operation 159 * @return the status of the operation 160 161 * @throws DoesNotExistException examId is not found 162 * @throws InvalidParameterException contextInfo is not valid 163 * @throws MissingParameterException examId, or 164 * contextInfo is missing or null 165 * @throws OperationFailedException unable to complete request 166 * @throws PermissionDeniedException an authorization failure occurred 167 */ 168 public StatusInfo deleteExam(@WebParam(name = "examId") String examId, 169 @WebParam(name = "contextInfo") ContextInfo contextInfo) 170 throws DoesNotExistException, 171 InvalidParameterException, 172 MissingParameterException, 173 OperationFailedException, 174 PermissionDeniedException; 175 176 /** 177 * Retrieves the information for the specified list of Exams (that match the given Ids). 178 * 179 * @param examIds List of identifiers for exams 180 * @param contextInfo Context information containing the principalId and locale 181 * information about the caller of service operation 182 * @return List of exams matching the given ids 183 * @throws DoesNotExistException One or more exams not found 184 * @throws InvalidParameterException contextInfo is invalid 185 * @throws MissingParameterException examIds or contextInfo are absent (missing or null) 186 * @throws OperationFailedException unable to complete request 187 * @throws PermissionDeniedException authorization failure 188 */ 189 public List<ExamInfo> getExamsByIds (@WebParam(name = "examIds") List<String> examIds, 190 @WebParam(name = "contextInfo") ContextInfo contextInfo) 191 throws DoesNotExistException, 192 InvalidParameterException, 193 MissingParameterException, 194 OperationFailedException, 195 PermissionDeniedException; 196 197 /** 198 * Retrieve a list of Exam Ids by Exam Type. 199 * 200 * @param examTypeKey the identifier for an exam Type 201 * @param contextInfo information containing the principalId and 202 * locale information about the caller of 203 * service operation 204 * @return a list of exam identifiers matching 205 * examTypeKey or an empty list if none found 206 * @throws InvalidParameterException contextInfo is not valid 207 * @throws MissingParameterException examTypeKey or contextInfo is 208 * missing or null 209 * @throws OperationFailedException unable to complete request 210 * @throws PermissionDeniedException an authorization failure occurred 211 */ 212 public List<String> getExamIdsByType(@WebParam(name = "examTypeKey") String examTypeKey, 213 @WebParam(name = "contextInfo") ContextInfo contextInfo) 214 throws InvalidParameterException, 215 MissingParameterException, 216 OperationFailedException, 217 PermissionDeniedException; 218 219 /** 220 * Searches for Exams that meet the given search criteria. 221 * 222 * @param criteria the search criteria 223 * @param contextInfo information containing the principalId and locale 224 * information about the caller of service operation 225 * @return a list of Exam Ids matching the criteria 226 * @throws InvalidParameterException criteria or contextInfo is not valid 227 * @throws MissingParameterException criteria or contextInfo is missing or 228 * null 229 * @throws OperationFailedException unable to complete request 230 * @throws PermissionDeniedException an authorization failure occurred 231 */ 232 public List<String> searchForExamIds(@WebParam(name = "criteria") QueryByCriteria criteria, 233 @WebParam(name = "contextInfo") ContextInfo contextInfo) 234 throws InvalidParameterException, 235 MissingParameterException, 236 OperationFailedException, 237 PermissionDeniedException; 238 239 /** 240 * Searches for Exams that meet the given search criteria. 241 * 242 * @param criteria the search criteria 243 * @param contextInfo information containing the principalId and locale 244 * information about the caller of service operation 245 * @return a list of Exams matching the criteria 246 * @throws InvalidParameterException criteria or contextInfo is not valid 247 * @throws MissingParameterException criteria or contextInfo is missing or 248 * null 249 * @throws OperationFailedException unable to complete request 250 * @throws PermissionDeniedException an authorization failure occurred 251 */ 252 public List<ExamInfo> searchForExams (@WebParam(name = "criteria") QueryByCriteria criteria, 253 @WebParam(name = "contextInfo") ContextInfo contextInfo) 254 throws InvalidParameterException, 255 MissingParameterException, 256 OperationFailedException, 257 PermissionDeniedException; 258 259 260 }