1 /** 2 * Copyright 2012 The Kuali Foundation 3 * 4 * Licensed under the Educational Community License, Version 2.0 (the 5 * "License"); you may not use this file except in compliance with the 6 * License. You may obtain a copy of the License at 7 * 8 * http://www.osedu.org/licenses/ECL-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 13 * implied. See the License for the specific language governing 14 * permissions and limitations under the License. 15 */ 16 17 package org.kuali.student.enrollment.bundledoffering.service; 18 19 import java.util.List; 20 21 import javax.jws.WebParam; 22 import javax.jws.WebService; 23 import javax.jws.soap.SOAPBinding; 24 25 import org.kuali.rice.core.api.criteria.QueryByCriteria; 26 27 import org.kuali.student.enrollment.bundledoffering.dto.BundledOfferingInfo; 28 29 import org.kuali.student.r2.common.dto.ContextInfo; 30 import org.kuali.student.r2.common.dto.StatusInfo; 31 import org.kuali.student.r2.common.dto.ValidationResultInfo; 32 33 import org.kuali.student.r2.common.exceptions.DataValidationErrorException; 34 import org.kuali.student.r2.common.exceptions.DependentObjectsExistException; 35 import org.kuali.student.r2.common.exceptions.DoesNotExistException; 36 import org.kuali.student.r2.common.exceptions.InvalidParameterException; 37 import org.kuali.student.r2.common.exceptions.MissingParameterException; 38 import org.kuali.student.r2.common.exceptions.OperationFailedException; 39 import org.kuali.student.r2.common.exceptions.PermissionDeniedException; 40 import org.kuali.student.r2.common.exceptions.ReadOnlyException; 41 import org.kuali.student.r2.common.exceptions.VersionMismatchException; 42 43 44 /** 45 * This service supports the management of Bundled Offerings. A 46 * Bundled Offering is a set of Registration Groups for which a 47 * student is registered together. A Bundled Offering is an offering 48 * of a canonical CourseBundle. 49 * 50 * @version 0.0.8 51 * @author Kuali Student Services 52 */ 53 54 @WebService(name = "BundledOfferingService", targetNamespace = BundledOfferingServiceNamespace.NAMESPACE) 55 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) 56 57 public interface BundledOfferingService { 58 59 60 /** 61 * Retrieves a single BundledOffering by BundledOffering Id. 62 * 63 * @param bundledOfferingId the identifier for the bundled 64 * offering to be retrieved 65 * @param contextInfo information containing the principalId and 66 * locale information about the caller of service operation 67 * @return the BundledOffering requested 68 * @throws DoesNotExistException bundledOfferingId not found 69 * @throws InvalidParameterException contextInfo is not valid 70 * @throws MissingParameterException bundledOfferingId or 71 * contextInfo is missing or null 72 * @throws OperationFailedException unable to complete request 73 * @throws PermissionDeniedException an authorization failure occurred 74 */ 75 public BundledOfferingInfo getBundledOffering(@WebParam(name = "bundledOfferingId") String bundledOfferingId, 76 @WebParam(name = "contextInfo") ContextInfo contextInfo) 77 throws DoesNotExistException, 78 InvalidParameterException, 79 MissingParameterException, 80 OperationFailedException, 81 PermissionDeniedException; 82 83 /** 84 * Retrieves a list of BundledOfferings from a list of 85 * BundledOffering Ids. The returned list may be in any order and 86 * if duplicates Ids are supplied, a unique set may or may not be 87 * returned. 88 * 89 * @param bundledOfferingIds a list of BundledOffering identifiers 90 * @param contextInfo information containing the principalId and 91 * locale information about the caller of service operation 92 * @return a list of BundledOfferings 93 * @throws DoesNotExistException a bundledOfferingId in the list not found 94 * @throws InvalidParameterException contextInfo is invalid 95 * @throws MissingParameterException bundledOfferingIds, an Id in 96 * bundledOfferingIds, or contextInfo is missing or null 97 * @throws OperationFailedException unable to complete request 98 * @throws PermissionDeniedException an authorization failure occurred 99 */ 100 public List<BundledOfferingInfo> getBundledOfferingsByIds(@WebParam(name = "bundledOfferingIds") List<String> bundledOfferingIds, 101 @WebParam(name = "contextInfo") ContextInfo contextInfo) 102 throws DoesNotExistException, 103 InvalidParameterException, 104 MissingParameterException, 105 OperationFailedException, 106 PermissionDeniedException; 107 108 /** 109 * Retrieves a list of BundledOffering Ids by BundledOffering Type. 110 * 111 * @param bundledOfferingTypeKey an identifier for a 112 * BundledOffering Type 113 * @param contextInfo information containing the principalId and 114 * locale information about the caller of service operation 115 * @return a list of BundledOffering identifiers matching 116 * bundledOfferingTypeKey or an empty list if none found 117 * @throws InvalidParameterException contextInfo is not valid 118 * @throws MissingParameterException bundledOfferingTypeKey or 119 * contextInfo is missing or null 120 * @throws OperationFailedException unable to complete request 121 * @throws PermissionDeniedException an authorization failure occurred 122 */ 123 public List<String> getBundledOfferingIdsByType(@WebParam(name = "bundledOfferingTypeKey") String bundledOfferingTypeKey, 124 @WebParam(name = "contextInfo") ContextInfo contextInfo) 125 throws InvalidParameterException, 126 MissingParameterException, 127 OperationFailedException, 128 PermissionDeniedException; 129 130 /** 131 * Retrieves a list of BundledOfferings belonging to a 132 * CourseBundle. 133 * 134 * @param courseBundleId the identifier for a canonical 135 * CourseBundle 136 * @param contextInfo information containing the principalId and 137 * locale information about the caller of service operation 138 * @return a list of BundledOfferings for a CourseBundle or an 139 * empty list is none found 140 * @throws InvalidParameterException contextInfo is not valid 141 * @throws MissingParameterException courseBundleId or contextInfo 142 * is missing or null 143 * @throws OperationFailedException unable to complete request 144 * @throws PermissionDeniedException an authorization failure occurred 145 */ 146 public List<BundledOfferingInfo> getBundledOfferingsByCourseBundle(@WebParam(name = "courseBundleId") String courseBundleId, 147 @WebParam(name = "contextInfo") ContextInfo contextInfo) 148 throws InvalidParameterException, 149 MissingParameterException, 150 OperationFailedException, 151 PermissionDeniedException; 152 153 /** 154 * Retrieves a list of BundledOfferings by Term. 155 * 156 * @param termId the Id of a Term 157 * @param contextInfo information containing the principalId and 158 * locale information about the caller of service operation 159 * @return a list of BundledOfferings for the Term or an empty 160 * list is none found 161 * @throws InvalidParameterException contextInfo is not valid 162 * @throws MissingParameterException termId or 163 * contextInfo is missing or null 164 * @throws OperationFailedException unable to complete request 165 * @throws PermissionDeniedException an authorization failure occurred 166 */ 167 public List<BundledOfferingInfo> getBundledOfferingsByTerm(@WebParam(name = "termId") String termId, 168 @WebParam(name = "contextInfo") ContextInfo contextInfo) 169 throws InvalidParameterException, 170 MissingParameterException, 171 OperationFailedException, 172 PermissionDeniedException; 173 174 175 /** 176 * Retrieves a list of BundledOfferings by CourseBundle and Term. 177 * 178 * @param courseBundleId the identifier for a canonical 179 * CourseBundle 180 * @param termId the Id of a Term 181 * @param contextInfo information containing the principalId and 182 * locale information about the caller of service operation 183 * @return a list of BundledOfferings for the Term or an empty 184 * list is none found 185 * @throws InvalidParameterException contextInfo is not valid 186 * @throws MissingParameterException courseBundleId, termId, or 187 * contextInfo is missing or null 188 * @throws OperationFailedException unable to complete request 189 * @throws PermissionDeniedException an authorization failure occurred 190 */ 191 public List<BundledOfferingInfo> getBundledOfferingsByCourseBundleAndTerm(@WebParam(name = "courseBundleId") String courseBundleId, 192 @WebParam(name = "termId") String termId, 193 @WebParam(name = "contextInfo") ContextInfo contextInfo) 194 throws InvalidParameterException, 195 MissingParameterException, 196 OperationFailedException, 197 PermissionDeniedException; 198 199 /** 200 * Retrieves a list of BundledOfferings containing a Registration 201 * Group. 202 * 203 * @param regsitartionGroupId the Id of a registration Group 204 * @param contextInfo information containing the principalId and 205 * locale information about the caller of service operation 206 * @return a list of BundledOfferings fwith the registration 207 * Groupor an empty list is none found 208 * @throws InvalidParameterException contextInfo is not valid 209 * @throws MissingParameterException regsitrationGroupId or 210 * contextInfo is missing or null 211 * @throws OperationFailedException unable to complete request 212 * @throws PermissionDeniedException an authorization failure occurred 213 */ 214 public List<BundledOfferingInfo> getBundledOfferingsByRegistrationGroup(@WebParam(name = "regsitrationGroupId") String registrationGroupId, 215 @WebParam(name = "contextInfo") ContextInfo contextInfo) 216 throws InvalidParameterException, 217 MissingParameterException, 218 OperationFailedException, 219 PermissionDeniedException; 220 221 /** 222 * Retrieves a list of BundledOfferings by Term and code. 223 * 224 * @param termId a Term Id 225 * @param code a BundledOffering code 226 * @param contextInfo information containing the principalId and 227 * locale information about the caller of service operation 228 * @return a list of BundledOfferings for the given code empty 229 * list is none found 230 * @throws InvalidParameterException contextInfo is not valid 231 * @throws MissingParameterException termId, code or contextInfo 232 * is missing or null 233 * @throws OperationFailedException unable to complete request 234 * @throws PermissionDeniedException an authorization failure occurred 235 */ 236 public List<BundledOfferingInfo> getBundledOfferingsByTermAndCode(@WebParam(name = "termId") String termId, 237 @WebParam(name = "code") String code, 238 @WebParam(name = "contextInfo") ContextInfo contextInfo) 239 throws InvalidParameterException, 240 MissingParameterException, 241 OperationFailedException, 242 PermissionDeniedException; 243 244 /** 245 * Retrieves a list of BundledOfferings by Term and subject area. 246 * 247 * @param term a Term Id 248 * @param subjectAreaOrgIdId a subject area Org Id 249 * @param contextInfo information containing the principalId and 250 * locale information about the caller of service operation 251 * @return a list of BundledOfferings for the given term and 252 * subject area or an empty list is none found 253 * @throws InvalidParameterException contextInfo is not valid 254 * @throws MissingParameterException termId, subjectAreaOrgId, or 255 * contextInfo is missing or null 256 * @throws OperationFailedException unable to complete request 257 * @throws PermissionDeniedException an authorization failure occurred 258 */ 259 public List<BundledOfferingInfo> getBundledOfferingsByTermAndSubjectAreaOrg(@WebParam(name = "termId") String termId, 260 @WebParam(name = "subjectAreaOrgId") String subjectAreaOrgId, 261 @WebParam(name = "contextInfo") ContextInfo contextInfo) 262 throws InvalidParameterException, 263 MissingParameterException, 264 OperationFailedException, 265 PermissionDeniedException; 266 267 /** 268 * Searches for BundledOfferings based on the criteria and returns 269 * a list of BundledOffering identifiers which match the search 270 * criteria. 271 * 272 * @param criteria the search criteria 273 * @param contextInfo information containing the principalId and 274 * locale information about the caller of service operation 275 * @return list of BundledOffering Ids matching the criteria 276 * @throws InvalidParameterException criteria or contextInfo is 277 * not valid 278 * @throws MissingParameterException criteria or contextInfo is 279 * missing or null 280 * @throws OperationFailedException unable to complete request 281 * @throws PermissionDeniedException an authorization failure occurred 282 */ 283 public List<String> searchForBundledOfferingIds(@WebParam(name = "criteria") QueryByCriteria criteria, 284 @WebParam(name = "contextInfo") ContextInfo contextInfo) 285 throws InvalidParameterException, 286 MissingParameterException, 287 OperationFailedException, 288 PermissionDeniedException; 289 290 /** 291 * Searches for BundledOfferings based on the criteria and returns 292 * a list of BundledOfferings which match the search criteria. 293 * 294 * @param criteria the search criteria 295 * @param contextInfo information containing the principalId and 296 * locale information about the caller of service operation 297 * @return list of BundledOfferings matching the criteria 298 * @throws InvalidParameterException criteria or contextInfo is 299 * not valid 300 * @throws MissingParameterException criteria or contextInfo is 301 * missing or null 302 * @throws OperationFailedException unable to complete request 303 * @throws PermissionDeniedException an authorization failure occurred 304 */ 305 public List<BundledOfferingInfo> searchForBundledOfferings(@WebParam(name = "criteria") QueryByCriteria criteria, 306 @WebParam(name = "contextInfo") ContextInfo contextInfo) 307 throws InvalidParameterException, 308 MissingParameterException, 309 OperationFailedException, 310 PermissionDeniedException; 311 312 /** 313 * Validates a BundledOffering. Depending on the value of 314 * validationType, this validation could be limited to tests on 315 * just the current BundledOffering and its directly contained 316 * sub-objects or expanded to perform all tests related to this 317 * BundledOffering. If an identifier is present for the 318 * BundledOffering (and/or one of its contained sub-objects) and a 319 * record is found for that identifier, the validation checks if 320 * the BundledOffering can be updated to the new values. If an 321 * identifier is not present or a record does not exist, the 322 * validation checks if the object with the given data can be 323 * created. 324 * 325 * @param validationTypeKey the identifier for the validation Type 326 * @param courseBundleId the identifier for the CourseBundle 327 * @param termIdId the identifier for the Term 328 * @param bundledOfferingTypeKey the identifier for the bundled 329 * offering Type 330 * @param bundledOfferingInfo the BundledOffering information to 331 * be validated 332 * @param contextInfo information containing the principalId and 333 * locale information about the caller of service operation 334 * @return a list of validation results or an empty list if 335 * validation succeeded 336 * @throws DoesNotExistException validationTypeKey, 337 * courseBundleId, termId, or bundledOfferingTypeKey is 338 * not found 339 * @throws InvalidParameterException bundledOfferingInfo or 340 * contextInfo is not valid 341 * @throws MissingParameterException validationTypeKey, 342 * courseBundleId, termId, bundledOfferingTypeKey, 343 * bundledOfferingInfo, or contextInfo is missing or null 344 * @throws OperationFailedException unable to complete request 345 * @throws PermissionDeniedException an authorization failure occurred 346 */ 347 public List<ValidationResultInfo> validateBundledOffering(@WebParam(name = "validationTypeKey") String validationTypeKey, 348 @WebParam(name = "courseBundleId") String courseBundleId, 349 @WebParam(name = "termId") String termId, 350 @WebParam(name = "bundledOfferingTypeKey") String bundledOfferingTypeKey, 351 @WebParam(name = "bundledOfferingInfo") BundledOfferingInfo bundledOfferingInfo, 352 @WebParam(name = "contextInfo") ContextInfo contextInfo) 353 throws DoesNotExistException, 354 InvalidParameterException, 355 MissingParameterException, 356 OperationFailedException, 357 PermissionDeniedException; 358 359 /** 360 * Creates a new BundledOffering from a canonical CourseBundle for 361 * a Term. The BundledOffering Id, Type, and Meta information may 362 * not be set in the supplied data. 363 * 364 * @param courseBundleId the identifier for the canonical 365 * CourseBundle 366 * @param termId the identifier for the Term 367 * @param bundledOfferingTypeKey the identifier for the Type of 368 * the new BundledOffering 369 * @param bundledOfferingInfo the data with which to create the 370 * BundledOffering 371 * @param contextInfo information containing the principalId and 372 * locale information about the caller of service operation 373 * @return the new BundledOffering 374 * @throws DataValidationErrorException supplied data is invalid 375 * @throws DoesNotExistException courseBundleId, termId, or 376 * bundledOfferingTypeKey does not exist or is not 377 * supported 378 * @throws InvalidParameterException bundledOfferingInfo or 379 * contextInfo is not valid 380 * @throws MissingParameterException courseBundleId, termId, 381 * bundledOfferingTypeKey, bundledOfferingInfo or 382 * contextInfo is missing or null 383 * @throws OperationFailedException unable to complete request 384 * @throws PermissionDeniedException an authorization failure occurred 385 * @throws ReadOnlyException an attempt at supplying information 386 * designated as read-only 387 */ 388 public BundledOfferingInfo createBundledOffering(@WebParam(name = "courseBundleId") String courseBundleId, 389 @WebParam(name = "termId") String termId, 390 @WebParam(name = "bundledOfferingTypeKey") String bundledOfferingTypeKey, 391 @WebParam(name = "bundledOfferingInfo") BundledOfferingInfo bundledOfferingInfo, 392 @WebParam(name = "contextInfo") ContextInfo contextInfo) 393 throws DataValidationErrorException, 394 InvalidParameterException, 395 MissingParameterException, 396 OperationFailedException, 397 PermissionDeniedException, 398 ReadOnlyException; 399 400 /** 401 * Updates an existing BundledOffering. The BundledOffering Id, 402 * Type, and Meta information may not be changed. 403 * 404 * @param bundledOfferingId the identifier for the BundledOffering 405 * to be updated 406 * @param bundledOfferingInfo the new data for the BundledOffering 407 * @param contextInfo information containing the principalId and 408 * locale information about the caller of service operation 409 * @return the updated BundledOffering 410 * @throws DataValidationErrorException supplied data is invalid 411 * @throws DoesNotExistException bundledOfferingId not found 412 * @throws InvalidParameterException bundledOfferingInfo or 413 * contextInfo is not valid 414 * @throws MissingParameterException bundledOfferingId, 415 * bundledOfferingInfo, or contextInfo is missing or null 416 * @throws OperationFailedException unable to complete request 417 * @throws PermissionDeniedException an authorization failure occurred 418 * @throws ReadOnlyException an attempt at changing information 419 * designated as read-only 420 * @throws VersionMismatchException optimistic locking failure or 421 * the action was attempted on an out of date version 422 */ 423 public BundledOfferingInfo updateBundledOffering(@WebParam(name = "bundledOfferingId") String bundledOfferingId, 424 @WebParam(name = "bundledOfferingInfo") BundledOfferingInfo bundledOfferingInfo, 425 @WebParam(name = "contextInfo") ContextInfo contextInfo) 426 throws DataValidationErrorException, 427 DoesNotExistException, 428 InvalidParameterException, 429 MissingParameterException, 430 OperationFailedException, 431 PermissionDeniedException, 432 ReadOnlyException, 433 VersionMismatchException; 434 435 /** 436 * Changes the state of a BundledOffering. 437 * 438 * @param bundledOfferingId the Id of the BundledOffering 439 * @param stateKey the identifier for the new State 440 * @param contextInfo information containing the principalId and 441 * locale information about the caller of service operation 442 * @return the status of the operation. This must always be true. 443 * @throws DoesNotExistException bundledOfferingId not found or stateKey 444 * not found in BundledOffering Lifecycle 445 * @throws InvalidParameterException contextInfo is not valid 446 * @throws MissingParameterException bundledOfferingId, stateKey, or 447 * contextInfo is missing or null 448 * @throws OperationFailedException unable to complete request 449 * @throws PermissionDeniedException an authorization failure occurred 450 */ 451 public StatusInfo changeBundledOfferingState(@WebParam(name = "bundledOfferingId") String bundledOfferingId, 452 @WebParam(name = "stateKey") String stateKey, 453 @WebParam(name = "contextInfo") ContextInfo contextInfo) 454 throws DoesNotExistException, 455 InvalidParameterException, 456 MissingParameterException, 457 OperationFailedException, 458 PermissionDeniedException; 459 460 /** 461 * Deletes an existing BundledOffering. 462 * 463 * @param bundledOfferingId the identifier for the BundledOffering 464 * to be deleted 465 * @param contextInfo information containing the principalId and 466 * locale information about the caller of service operation 467 * @return the status of the delete operation. This must always be 468 * true. 469 * @throws DoesNotExistException bundledOfferingId not found 470 * @throws InvalidParameterException contextInfo is not valid 471 * @throws MissingParameterException bundledOfferingId or 472 * contextInfo is missing or null 473 * @throws OperationFailedException unable to complete request 474 * @throws PermissionDeniedException an authorization failure occurred 475 */ 476 public StatusInfo deleteBundledOffering(@WebParam(name = "bundledOfferingId") String bundledOfferingId, 477 @WebParam(name = "contextInfo") ContextInfo contextInfo) 478 throws DoesNotExistException, 479 InvalidParameterException, 480 MissingParameterException, 481 OperationFailedException, 482 PermissionDeniedException; 483 }