1 /* 2 * Copyright 2009 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.r2.lum.course.service; 12 13 import java.util.Date; 14 import java.util.List; 15 16 import javax.jws.WebParam; 17 import javax.jws.WebService; 18 import javax.jws.soap.SOAPBinding; 19 20 import org.kuali.rice.core.api.criteria.QueryByCriteria; 21 import org.kuali.student.r1.common.dictionary.service.DictionaryService; 22 import org.kuali.student.r2.common.exceptions.IllegalVersionSequencingException; 23 import org.kuali.student.r2.common.dto.ContextInfo; 24 import org.kuali.student.r2.common.dto.StatusInfo; 25 import org.kuali.student.r2.common.dto.ValidationResultInfo; 26 import org.kuali.student.r2.common.exceptions.AlreadyExistsException; 27 28 import org.kuali.student.r2.common.exceptions.CircularReferenceException; 29 import org.kuali.student.r2.common.exceptions.CircularRelationshipException; 30 import org.kuali.student.r2.common.exceptions.DataValidationErrorException; 31 import org.kuali.student.r2.common.exceptions.DependentObjectsExistException; 32 import org.kuali.student.r2.common.exceptions.DoesNotExistException; 33 import org.kuali.student.r2.common.exceptions.InvalidParameterException; 34 import org.kuali.student.r2.common.exceptions.MissingParameterException; 35 import org.kuali.student.r2.common.exceptions.OperationFailedException; 36 import org.kuali.student.r2.common.exceptions.PermissionDeniedException; 37 import org.kuali.student.r2.common.exceptions.ReadOnlyException; 38 import org.kuali.student.r2.common.exceptions.UnsupportedActionException; 39 import org.kuali.student.r2.common.exceptions.VersionMismatchException; 40 import org.kuali.student.r2.core.versionmanagement.dto.VersionDisplayInfo; 41 42 import org.kuali.student.r1.core.statement.dto.StatementTreeViewInfo; 43 import org.kuali.student.r2.lum.util.constants.CourseServiceConstants; 44 45 import org.kuali.student.r2.lum.course.dto.ActivityInfo; 46 import org.kuali.student.r2.lum.course.dto.CourseInfo; 47 import org.kuali.student.r2.lum.course.dto.FormatInfo; 48 import org.kuali.student.r2.lum.course.dto.LoDisplayInfo; 49 50 51 52 /** 53 * A course is a specified area of knowledge contained and taught independently 54 * from other areas of knowledge that may or may not be related. Courses typically 55 * have specific learning objectives, defined student learning outcomes and assessments. 56 * They can be recognized for academic credit or not. Courses can be delivered in 57 * various instructional formats such as lecture, lab, discussion, seminar, colloquium, 58 * etc. A course would utilize at least one instructional format, but often will 59 * use more than one. 60 * 61 * Course is pre-configured type of CLU (Canonical Learning Unit) that represents 62 * a credit course. The courseInfo object supports a number of complex course 63 * options – cross-listed, joint and variations. Course can have any number of associated 64 * learning objectives and requisites (rules that model pre-, co-, anti-requisites 65 * and enrollment restrictions). 66 * 67 * @version 2.0 68 * @author Kuali Student Team (sambitpa@kuali.org) 69 */ 70 @WebService(name = "CourseService", targetNamespace = CourseServiceConstants.NAMESPACE) 71 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) 72 public interface CourseService extends DictionaryService { 73 /** 74 * Retrieves a Course 75 * 76 * @param courseId Unique Id of the Course. Maps to cluId 77 * @return the created course 78 * @throws DoesNotExistException Course does not exist 79 * @throws InvalidParameterException invalid course 80 * @throws MissingParameterException missing Course 81 * @throws OperationFailedException unable to complete request 82 * @throws PermissionDeniedException authorization failure 83 */ 84 public CourseInfo getCourse(@WebParam(name = "courseId") String courseId, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, InvalidParameterException, 85 MissingParameterException, OperationFailedException, PermissionDeniedException; 86 87 /** 88 * Retrieves a list of courses by Ids 89 * 90 * @param courseIds 91 * @param contextInfo 92 * @return 93 * @throws DoesNotExistException 94 * @throws InvalidParameterException 95 * @throws MissingParameterException 96 * @throws OperationFailedException 97 * @throws PermissionDeniedException 98 */ 99 public List<CourseInfo> getCoursesByIds(@WebParam(name = "courseIds") List<String> courseIds, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, 100 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 101 102 /** 103 * Searches for courses based on the criteria and returns a list of Comment 104 * identifiers which match the search criteria. 105 * 106 * @param criteria the search criteria 107 * @param contextInfo Context information containing the principalId and 108 * locale information about the caller of service operation 109 * @return list of Comment Ids 110 * @throws InvalidParameterException invalid parameter 111 * @throws MissingParameterException criteria, contextInfo not specified 112 * @throws OperationFailedException unable to complete request 113 * @throws PermissionDeniedException authorization failure 114 */ 115 public List<String> searchForCourseIds(@WebParam(name = "criteria") QueryByCriteria criteria, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws InvalidParameterException, 116 MissingParameterException, OperationFailedException, PermissionDeniedException; 117 118 /** 119 * Searches for courses based on the criteria and returns a list of Comments 120 * which match the search criteria. 121 * 122 * @param criteria the search criteria 123 * @param contextInfo Context information containing the principalId and 124 * locale information about the caller of service operation 125 * @return list of Comment information 126 * @throws InvalidParameterException invalid parameter 127 * @throws MissingParameterException criteria, contextInfo not specified 128 * @throws OperationFailedException unable to complete request 129 * @throws PermissionDeniedException authorization failure 130 */ 131 public List<CourseInfo> searchForCourses(@WebParam(name = "criteria") QueryByCriteria criteria, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws InvalidParameterException, 132 MissingParameterException, OperationFailedException, PermissionDeniedException; 133 134 /** 135 * Creates a Course 136 * 137 * @param courseInfo courseInfo 138 * @return the created course 139 * @throws DataValidationErrorException One or more values invalid for this 140 * operation 141 * @throws InvalidParameterException invalid course 142 * @throws MissingParameterException missing Course 143 * @throws OperationFailedException unable to complete request 144 * @throws PermissionDeniedException authorization failure 145 * @throws VersionMismatchException 146 * @throws DependentObjectsExistException 147 */ 148 public CourseInfo createCourse(@WebParam(name = "courseInfo") CourseInfo courseInfo, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DataValidationErrorException, 149 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, VersionMismatchException; 150 151 /** 152 * Updates a Course. 153 * 154 * @param courseInfo courseInfo 155 * @param courseId 156 * @return updated Course 157 * @throws DataValidationErrorException One or more values invalid for this 158 * operation 159 * @throws DoesNotExistException course not found 160 * @throws InvalidParameterException invalid course 161 * @throws MissingParameterException missing course 162 * @throws VersionMismatchException The action was attempted on an out of 163 * date version. 164 * @throws OperationFailedException unable to complete request 165 * @throws PermissionDeniedException authorization failure 166 * @throws CircularReferenceException 167 * @throws CircularRelationshipException 168 * @throws AlreadyExistsException 169 * @throws DependentObjectsExistException 170 * @throws UnsupportedActionException 171 */ 172 public CourseInfo updateCourse(@WebParam(name = "courseId") String courseId, @WebParam(name = "courseInfo") CourseInfo courseInfo, @WebParam(name = "contextInfo") ContextInfo contextInfo) 173 throws DataValidationErrorException, DoesNotExistException, InvalidParameterException, MissingParameterException, VersionMismatchException, OperationFailedException, 174 PermissionDeniedException, UnsupportedActionException, DependentObjectsExistException, AlreadyExistsException, CircularRelationshipException, CircularReferenceException, ReadOnlyException; 175 176 /** 177 * Deletes a Course. 178 * 179 * @param courseId identifier for Course.Maps to cluId 180 * @return status of the operation (success or failure) 181 * @throws DoesNotExistException Course does not exist 182 * @throws InvalidParameterException invalid courseId 183 * @throws MissingParameterException invalid courseId 184 * @throws OperationFailedException unable to complete request 185 * @throws PermissionDeniedException authorization failure 186 * @throws CircularReferenceException 187 * @throws CircularRelationshipException 188 * @throws DependentObjectsExistException 189 * @throws UnsupportedActionException 190 */ 191 public StatusInfo deleteCourse(@WebParam(name = "courseId") String courseId, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, InvalidParameterException, 192 MissingParameterException, OperationFailedException, PermissionDeniedException, VersionMismatchException, DataValidationErrorException, AlreadyExistsException, UnsupportedActionException, DependentObjectsExistException, CircularRelationshipException, CircularReferenceException, ReadOnlyException; 193 194 /** 195 * Validates a course based on its dictionary 196 * 197 * @param validationType identifier of the extent of validation 198 * @param courseInfo Course to be validated 199 * @return results from performing the validation 200 * @throws DoesNotExistException Course does not exist 201 * @throws InvalidParameterException invalid courseId 202 * @throws MissingParameterException invalid courseId 203 * @throws OperationFailedException unable to complete request 204 */ 205 public List<ValidationResultInfo> validateCourse(String validationType, CourseInfo courseInfo, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, 206 InvalidParameterException, MissingParameterException, OperationFailedException; 207 208 /** 209 * Retrieves the formats for a Course. 210 * 211 * @param courseId Unique Id of the Course. Maps to cluId 212 * @return a list of format info Structures 213 * @throws DoesNotExistException Course does not exist 214 * @throws InvalidParameterException invalid courseId 215 * @throws MissingParameterException invalid courseId 216 * @throws OperationFailedException unable to complete request 217 * @throws PermissionDeniedException authorization failure 218 */ 219 public List<FormatInfo> getCourseFormatsByCourse(@WebParam(name = "courseId") String courseId, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, 220 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 221 222 /** 223 * Retrieves the Activities for a Course. 224 * 225 * @param formatId Unique Id of the Format. Maps to cluId 226 * @return a list of activity info Structures 227 * @throws DoesNotExistException Format does not exist 228 * @throws InvalidParameterException invalid format 229 * @throws MissingParameterException missing Format 230 * @throws OperationFailedException unable to complete request 231 * @throws PermissionDeniedException authorization failure 232 */ 233 public List<ActivityInfo> getCourseActivitiesByCourseFormat(@WebParam(name = "formatId") String formatId, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, 234 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 235 236 /** 237 * Retrieves the Learning Objectives for a Course. 238 * 239 * @param courseId Unique Id of the Course. Maps to cluId 240 * @return a list of LoDisplay info Structures 241 * @throws DoesNotExistException Course does not exist 242 * @throws InvalidParameterException invalid courseId 243 * @throws MissingParameterException invalid courseId 244 * @throws OperationFailedException unable to complete request 245 * @throws PermissionDeniedException authorization failure 246 */ 247 public List<LoDisplayInfo> getCourseLearningObjectivesByCourse(@WebParam(name = "courseId") String courseId, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, 248 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 249 250 /** 251 * Retrieves the Statements of a Course. 252 * 253 * @param courseId Unique Id of the Course. Maps to cluId 254 * @param nlUsageTypeKey Natural language usage type key (context) 255 * @param language Translation language e.g en, es, gr 256 * @return a list of Statement tree Structures 257 * @throws DoesNotExistException Course does not exist 258 * @throws InvalidParameterException invalid courseId 259 * @throws MissingParameterException invalid courseId 260 * @throws OperationFailedException unable to complete request 261 * @throws PermissionDeniedException authorization failure 262 */ 263 public List<StatementTreeViewInfo> getCourseStatements(@WebParam(name = "courseId") String courseId, @WebParam(name = "nlUsageTypeKey") String nlUsageTypeKey, 264 @WebParam(name = "language") String language, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, InvalidParameterException, MissingParameterException, 265 OperationFailedException, PermissionDeniedException; 266 267 /** 268 * Creates the Statement for a Course. 269 * 270 * @param courseId Unique Id of the Course. Maps to cluId 271 * @param statementTreeViewInfoList a Statementree Structures 272 * @return created Statementree Structures 273 * @throws DoesNotExistException Course does not exist 274 * @throws InvalidParameterException invalid courseId 275 * @throws MissingParameterException invalid courseId 276 * @throws OperationFailedException unable to complete request 277 * @throws PermissionDeniedException authorization failure 278 * @throws DataValidationErrorException 279 */ 280 public StatementTreeViewInfo createCourseStatement(@WebParam(name = "courseId") String courseId, @WebParam(name = "statementTreeViewInfo") StatementTreeViewInfo statementTreeViewInfo, 281 @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, 282 PermissionDeniedException, DataValidationErrorException; 283 284 /** 285 * Updates the Statement for a Course. 286 * 287 * @param courseId Unique Id of the Course. Maps to cluId 288 * @param statementId 289 * @param statementTreeViewInfoList a Statementree Structures 290 * @return updated Statementree Structures 291 * @throws DoesNotExistException Course does not exist 292 * @throws InvalidParameterException invalid courseId 293 * @throws MissingParameterException invalid courseId 294 * @throws OperationFailedException unable to complete request 295 * @throws PermissionDeniedException authorization failure 296 * @throws VersionMismatchException 297 * @throws DataValidationErrorException 298 */ 299 public StatementTreeViewInfo updateCourseStatement(@WebParam(name = "courseId") String courseId, @WebParam(name = "statementTreeId") String statementId, 300 @WebParam(name = "statementTreeViewInfo") StatementTreeViewInfo statementTreeViewInfo, @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, 301 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, DataValidationErrorException, VersionMismatchException; 302 303 /** 304 * Delete the Statement for a Course. 305 * 306 * @param courseId Unique Id of the Course. Maps to cluId 307 * @param statementTreeViewInfoList a Statementree Structures 308 * @return status of the operation (success or failure) 309 * @throws DoesNotExistException Course does not exist 310 * @throws InvalidParameterException invalid courseId 311 * @throws MissingParameterException invalid courseId 312 * @throws OperationFailedException unable to complete request 313 * @throws PermissionDeniedException authorization failure 314 */ 315 public StatusInfo deleteCourseStatement(@WebParam(name = "courseId") String courseId, @WebParam(name = "statementTreeViewInfo") StatementTreeViewInfo statementTreeViewInfo, 316 @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, 317 PermissionDeniedException; 318 319 /** 320 * Validates the Statement for a Course. 321 * 322 * @param courseId Unique Id of the Course. Maps to cluId 323 * @param statementTreeViewInfoList a Statementree Structures 324 * @return results from performing the validation 325 * @throws DoesNotExistException Course or StementTreeView does not exist 326 * @throws InvalidParameterException invalid courseId or stratement tree 327 * view Id 328 * @throws MissingParameterException invalid courseId or statement tree view 329 * Id 330 * @throws OperationFailedException unable to complete request 331 * @throws PermissionDeniedException 332 */ 333 public List<ValidationResultInfo> validateCourseStatement(@WebParam(name = "courseId") String courseId, @WebParam(name = "statementTreeViewInfo") StatementTreeViewInfo statementTreeViewInfo, 334 @WebParam(name = "contextInfo") ContextInfo contextInfo) throws InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 335 336 /** 337 * Creates a new Course version based on the current course 338 * 339 * @param courseId identifier for the Course to be versioned 340 * @param versionComment comment for the current version 341 * @return the new versioned Course information 342 * @throws DataValidationErrorException One or more values invalid for this 343 * operation 344 * @throws DoesNotExistException courseId not found 345 * @throws InvalidParameterException invalid courseId 346 * @throws MissingParameterException missing courseId 347 * @throws OperationFailedException unable to complete request 348 * @throws PermissionDeniedException authorization failure 349 * @throws VersionMismatchException The action was attempted on an out of 350 * date version 351 * @throws ReadOnlyException 352 */ 353 public CourseInfo createNewCourseVersion(@WebParam(name = "courseId") String courseId, @WebParam(name = "versionComment") String versionComment, 354 @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DataValidationErrorException, DoesNotExistException, InvalidParameterException, MissingParameterException, 355 OperationFailedException, PermissionDeniedException, VersionMismatchException, ReadOnlyException; 356 357 /** 358 * Sets a specific version of the Course as current. The sequence number 359 * must be greater than the existing current Course version. This will 360 * truncate the current version's end date to the currentVersionStart param. 361 * If a Course exists which is set to become current in the future, that 362 * course's currentVersionStart and CurrentVersionEnd will be nullified. The 363 * currentVersionStart must be in the future to prevent changing historic 364 * data. 365 * 366 * @param courseVersionId Version Specific Id of the Course 367 * @param currentVersionStart Date when this course becomes current. Must be 368 * in the future and be after the most current course's start 369 * date. 370 * @return status of the operation 371 * @throws DoesNotExistException courseVersionId not found 372 * @throws InvalidParameterException invalid courseVersionId, previousState, 373 * newState 374 * @throws MissingParameterException missing courseVersionId, previousState, 375 * newState 376 * @throws IllegalVersionSequencingException a Course with higher sequence 377 * number from the one provided is marked current 378 * @throws OperationFailedException unable to complete request 379 * @throws PermissionDeniedException authorization failure 380 * @throws IllegalVersionSequencingException 381 * @throws DataValidationErrorException 382 */ 383 public StatusInfo setCurrentCourseVersion(@WebParam(name = "courseVersionId") String courseVersionId, @WebParam(name = "currentVersionStart") Date currentVersionStart, 384 @WebParam(name = "contextInfo") ContextInfo contextInfo) throws DoesNotExistException, InvalidParameterException, MissingParameterException, 385 OperationFailedException, PermissionDeniedException, IllegalVersionSequencingException, DataValidationErrorException; 386 387 /** 388 * Retrieves current version associated with the objectId. 389 * 390 * @param refObjectTypeURI 391 * reference object type URI 392 * @param refObjectId 393 * reference object Id 394 * @return current version 395 * @throws DoesNotExistException 396 * specified refObjectId, refObjectTypeURI not found 397 * @throws InvalidParameterException 398 * invalid refObjectId, refObjectTypeURI 399 * @throws MissingParameterException 400 * refObjectId, refObjectTypeURI not specified 401 * @throws OperationFailedException 402 * unable to complete request 403 * @throws PermissionDeniedException 404 * authorization failure 405 */ 406 @Deprecated 407 public VersionDisplayInfo getCurrentVersion(@WebParam(name = "refObjectTypeURI") String refObjectTypeURI, @WebParam(name = "refObjectId") String refObjectId, ContextInfo contextInfo) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 408 409 @Deprecated 410 public List<VersionDisplayInfo> getVersions(String refObjectTypeURI, 411 String refObjectId, ContextInfo contextInfo) throws DoesNotExistException, 412 InvalidParameterException, MissingParameterException, 413 OperationFailedException, PermissionDeniedException; 414 415 }