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.grading.service; 12 13 import java.util.List; 14 15 import javax.jws.WebParam; 16 import javax.jws.WebService; 17 import javax.jws.soap.SOAPBinding; 18 19 import org.kuali.student.enrollment.grading.dto.GradeRosterEntryInfo; 20 import org.kuali.student.enrollment.grading.dto.GradeRosterInfo; 21 import org.kuali.student.enrollment.grading.dto.GradeValuesGroupInfo; 22 import org.kuali.student.r2.common.dto.ContextInfo; 23 import org.kuali.student.r2.common.dto.StatusInfo; 24 import org.kuali.student.r2.common.dto.ValidationResultInfo; 25 import org.kuali.student.r2.common.exceptions.*; 26 import org.kuali.student.r2.common.util.constants.GradingServiceConstants; 27 import org.kuali.student.r2.core.class1.type.dto.TypeInfo; 28 import org.kuali.student.r2.lum.lrc.dto.ResultValueInfo; 29 30 /** 31 * This service manages grade and credit 32 * submission for activity/course offerings. The service can be used for 33 * capturing final grades and any number of interim grades. The service provides 34 * the following primary functions: 35 * <ol> 36 * <li>Build Grade Rosters 37 * <li>Capture Assigned Grades for students in various rosters 38 * <li>Provides valid grading options for a student in an activity 39 * <li>Calculate grade translation for the grades within that offering (for e.g 40 * A-F grades to Pass/No-pass) 41 * <li>Calculate credits earned within that offering 42 * <li>Submission of final grades for the offering 43 * <li>Students are clubbed together into grade rosters for the purpose of 44 * grading. For any assessment event, one or more grade rosters of a certain 45 * type is created. Instructors (and/or delegates) are then allowed to enter 46 * grades for students on the roster. Only the final grade roster is submittable 47 * and the submission is tracked using the state of the grade roster. 48 * </ol> 49 * The service automatically creates the grade roster for the final grades. This 50 * roster(s) is created only for the offerings of the primary activity type. The 51 * structure and breakdown of the students in the final grade roster can be 52 * configured and student can exist only once in the final grade roster(s). 53 * Interim rosters can be created for activity offerings based on a assessment 54 * event like mid term, weekly quiz etc. 55 * 56 * @version 0.0.7 57 * @author Kuali Student Team (Kamal) 58 */ 59 @WebService(name = "GradingService", serviceName = "GradingService", portName = "GradingService", targetNamespace = GradingServiceConstants.NAMESPACE) 60 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) 61 public interface GradingService { 62 63 /** 64 * This method returns the TypeInfo for a given grade roster type key. 65 * 66 * @param gradeRosterTypeKey Key of the type 67 * @param context Context information containing the principalId and locale 68 * information about the caller of service operation 69 * @return Information about the Type 70 * @throws DoesNotExistException gradeRosterTypeKey not found 71 * @throws InvalidParameterException invalid gradeRosterTypeKey 72 * @throws MissingParameterException missing gradeRosterTypeKey 73 * @throws OperationFailedException unable to complete request 74 */ 75 public TypeInfo getGradeRosterType(@WebParam(name = "gradeRosterTypeKey") String gradeRosterTypeKey, @WebParam(name = "context") ContextInfo context) throws DoesNotExistException, 76 InvalidParameterException, MissingParameterException, OperationFailedException; 77 78 /** 79 * Retrieve information about a grade roster 80 * 81 * @param gradeRosterId 82 * @param context Context information containing the principalId and locale 83 * information about the caller of service operation 84 * @return 85 * @throws DoesNotExistException 86 * @throws InvalidParameterException 87 * @throws MissingParameterException 88 * @throws OperationFailedException 89 * @throws PermissionDeniedException authorization failure 90 */ 91 public GradeRosterInfo getGradeRoster(@WebParam(name = "gradeRosterId") String gradeRosterId, @WebParam(name = "context") ContextInfo context) throws DoesNotExistException, 92 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 93 94 /** 95 * Retrieve information about grade rosters by grader and term 96 * 97 * @param graderId 98 * @param termId 99 * @param context Context information containing the principalId and locale 100 * information about the caller of service operation 101 * @return 102 * @throws DoesNotExistException 103 * @throws InvalidParameterException 104 * @throws MissingParameterException 105 * @throws OperationFailedException 106 * @throws PermissionDeniedException authorization failure 107 */ 108 public List<GradeRosterInfo> getGradeRostersByGraderAndTerm(@WebParam(name = "graderId") String graderId, @WebParam(name = "termId") String termId, 109 @WebParam(name = "context") ContextInfo context) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 110 111 /** 112 * Retrieves rosters of final grades for a course offering 113 * 114 * @param courseOfferingId 115 * @param context Context information containing the principalId and locale 116 * information about the caller of service operation 117 * @return 118 * @throws DoesNotExistException 119 * @throws InvalidParameterException 120 * @throws MissingParameterException 121 * @throws OperationFailedException 122 * @throws PermissionDeniedException authorization failure 123 */ 124 public List<GradeRosterInfo> getFinalGradeRostersForCourseOffering(@WebParam(name = "courseOfferingId") String courseOfferingId, @WebParam(name = "context") ContextInfo context) 125 throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 126 127 /** 128 * Retrieves rosters of final grade by actvity offerings 129 * 130 * @param activityOfferingId 131 * @param context Context information containing the principalId and locale 132 * information about the caller of service operation 133 * @return 134 * @throws DoesNotExistException 135 * @throws InvalidParameterException 136 * @throws MissingParameterException 137 * @throws OperationFailedException 138 * @throws PermissionDeniedException authorization failure 139 */ 140 public List<GradeRosterInfo> getFinalGradeRostersForActivityOffering(@WebParam(name = "activityOfferingId") String activityOfferingId, @WebParam(name = "context") ContextInfo context) 141 throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 142 143 /** 144 * Retrieves all rosters for an activity offering 145 * 146 * @param activityOfferingId 147 * @param context Context information containing the principalId and locale 148 * information about the caller of service operation 149 * @return 150 * @throws DoesNotExistException 151 * @throws InvalidParameterException 152 * @throws MissingParameterException 153 * @throws OperationFailedException 154 * @throws PermissionDeniedException authorization failure 155 */ 156 public List<GradeRosterInfo> getGradeRostersForActivityOffering(@WebParam(name = "activityOfferingId") String activityOfferingId, @WebParam(name = "context") ContextInfo context) 157 throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 158 159 /** 160 * Build an interim roster of given type. Roster type should be used to 161 * figure out which students from the activity offerings will be in the 162 * roster 163 * 164 * @param activityOfferingIds 165 * @param rosterTypeKey 166 * @param context Context information containing the principalId and locale 167 * information about the caller of service operation 168 * @return 169 * @throws AlreadyExistsException 170 * @throws InvalidParameterException 171 * @throws MissingParameterException 172 * @throws OperationFailedException 173 * @throws PermissionDeniedException authorization failure 174 */ 175 public GradeRosterInfo buildInterimGradeRosterByType(@WebParam(name = "activityOfferingIds") String courseOfferingId, 176 @WebParam(name = "activityOfferingIds") List<String> activityOfferingIds, @WebParam(name = "rosterTypeKey") String rosterTypeKey, @WebParam(name = "context") ContextInfo context) 177 throws AlreadyExistsException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 178 179 /** 180 * Update interim grade roster information 181 * 182 * @param gradeRoster 183 * @param context Context information containing the principalId and locale 184 * information about the caller of service operation 185 * @return 186 * @throws DataValidationErrorException One or more values invalid for this 187 * operation 188 * @throws DoesNotExistException 189 * @throws InvalidParameterException 190 * @throws MissingParameterException 191 * @throws OperationFailedException 192 * @throws PermissionDeniedException authorization failure 193 * @throws VersionMismatchException 194 */ 195 public GradeRosterInfo updateInterimGradeRoster(@WebParam(name = "gradeRoster") GradeRosterInfo gradeRoster, @WebParam(name = "context") ContextInfo context) throws DataValidationErrorException, 196 DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, VersionMismatchException; 197 198 /** 199 * Delete an interim grade roster 200 * 201 * @param gradeRosterId 202 * @param context Context information containing the principalId and locale 203 * information about the caller of service operation 204 * @return 205 * @throws DoesNotExistException 206 * @throws InvalidParameterException 207 * @throws MissingParameterException 208 * @throws OperationFailedException 209 * @throws PermissionDeniedException authorization failure 210 */ 211 public StatusInfo deleteInterimGradeRoster(@WebParam(name = "gradeRosterId") String gradeRosterId, @WebParam(name = "context") ContextInfo context) throws DoesNotExistException, 212 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 213 214 /** 215 * Update state of final grade roster. Only state can be changed for the 216 * final grade roster. Final grade submission is tracked through state 217 * change on the roster. 218 * 219 * @param gradeRosterId 220 * @param stateKey 221 * @param context Context information containing the principalId and locale 222 * information about the caller of service operation 223 * @return 224 * @throws DataValidationErrorException One or more values invalid for this 225 * operation 226 * @throws DoesNotExistException 227 * @throws InvalidParameterException 228 * @throws MissingParameterException 229 * @throws OperationFailedException 230 * @throws PermissionDeniedException authorization failure 231 * @throws VersionMismatchException 232 */ 233 public GradeRosterInfo updateFinalGradeRosterState(@WebParam(name = "gradeRosterId") String gradeRosterId, @WebParam(name = "newStateKey") String stateKey, 234 @WebParam(name = "context") ContextInfo context) throws DataValidationErrorException, DoesNotExistException, InvalidParameterException, MissingParameterException, 235 OperationFailedException, PermissionDeniedException, VersionMismatchException; 236 237 /** 238 * Validate a grade roster information 239 * 240 * @param gradeRoster 241 * @param context Context information containing the principalId and locale 242 * information about the caller of service operation 243 * @return 244 * @throws DoesNotExistException 245 * @throws InvalidParameterException 246 * @throws MissingParameterException 247 * @throws OperationFailedException 248 */ 249 public List<ValidationResultInfo> validateGradeRoster(@WebParam(name = "gradeRoster") GradeRosterInfo gradeRoster, @WebParam(name = "context") ContextInfo context) throws DoesNotExistException, 250 InvalidParameterException, MissingParameterException, OperationFailedException; 251 252 /** 253 * Retrieve information about a grade roster entry 254 * 255 * @param gradeRosterEntryId 256 * @param context Context information containing the principalId and locale 257 * information about the caller of service operation 258 * @return 259 * @throws DoesNotExistException 260 * @throws InvalidParameterException 261 * @throws MissingParameterException 262 * @throws OperationFailedException 263 * @throws PermissionDeniedException authorization failure 264 */ 265 public GradeRosterEntryInfo getGradeRosterEntry(@WebParam(name = "gradeRosterEntryId") String gradeRosterEntryId, @WebParam(name = "context") ContextInfo context) throws DoesNotExistException, 266 InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 267 268 /** 269 * Retrieve a list of grade roster entries based on their Ids. The method 270 * should fail if there is an error in retrieving any id from the list. 271 * 272 * @param gradeRosterEntryIds list of grade roster entry Ids 273 * @param context Context information containing the principalId and locale 274 * information about the caller of service operation 275 * @return 276 * @throws DoesNotExistException 277 * @throws InvalidParameterException 278 * @throws MissingParameterException 279 * @throws OperationFailedException 280 * @throws PermissionDeniedException authorization failure 281 */ 282 public List<GradeRosterEntryInfo> getGradeRosterEntriesByIds(@WebParam(name = "gradeRosterEntryIds") List<String> gradeRosterEntryIds, @WebParam(name = "context") ContextInfo context) 283 throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 284 285 /** 286 * Retrieve grade roster entries by roster. 287 * 288 * @param gradeRosterId 289 * @param context Context information containing the principalId and locale 290 * information about the caller of service operation 291 * @return 292 * @throws DoesNotExistException 293 * @throws InvalidParameterException 294 * @throws MissingParameterException 295 * @throws OperationFailedException 296 * @throws PermissionDeniedException authorization failure 297 */ 298 public List<GradeRosterEntryInfo> getGradeRosterEntriesByRosterId(@WebParam(name = "gradeRosterId") String gradeRosterId, @WebParam(name = "context") ContextInfo context) 299 throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 300 301 302 /** 303 * Based on the id list, return {@link GradeValuesGroupInfo}. 304 * 305 * @param gradeRosterEntryIds 306 * @param rosterId 307 * @param context 308 * @return 309 * @throws DoesNotExistException 310 * @throws InvalidParameterException 311 * @throws MissingParameterException 312 * @throws OperationFailedException 313 * @throws PermissionDeniedException 314 */ 315 public List<GradeValuesGroupInfo> getGradeGroupsByKeyList(@WebParam(name = "gradeGroupKeyList") List<String> gradeGroupKeyList, @WebParam(name = "context") ContextInfo context) 316 throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 317 318 /** 319 * 320 * Get the final grades for a student in a particular course offering. 321 * 322 * @param studentId 323 * @param courseOfferingId 324 * @param context Context information containing the principalId and locale 325 * information about the caller of service operation 326 * @return 327 * @throws DoesNotExistException 328 * @throws InvalidParameterException 329 * @throws MissingParameterException 330 * @throws OperationFailedException 331 * @throws PermissionDeniedException authorization failure 332 */ 333 334 @Deprecated 335 public GradeRosterEntryInfo getFinalGradeForStudentInCourseOffering(@WebParam(name = "studentId") String studentId, @WebParam(name = "courseOfferingId") String courseOfferingId, 336 @WebParam(name = "context") ContextInfo context) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, DisabledIdentifierException; 337 338 /** 339 * This method ... 340 * 341 * @param gradeRosterEntry 342 * @param gradeRosterId 343 * @param context Context information containing the principalId and locale 344 * information about the caller of service operation 345 * @return 346 * @throws AlreadyExistsException 347 * @throws InvalidParameterException 348 * @throws MissingParameterException 349 * @throws OperationFailedException 350 * @throws PermissionDeniedException authorization failure 351 */ 352 public GradeRosterEntryInfo addEntrytoInterimRoster(@WebParam(name = "gradeRosterEntry") GradeRosterEntryInfo gradeRosterEntry, @WebParam(name = "gradeRosterId") String gradeRosterId, 353 @WebParam(name = "context") ContextInfo context) throws AlreadyExistsException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 354 355 /** 356 * This method ... 357 * 358 * @param gradeRosterEntryId 359 * @param gradeRosterId 360 * @param context Context information containing the principalId and locale 361 * information about the caller of service operation 362 * @return 363 * @throws DoesNotExistException 364 * @throws InvalidParameterException 365 * @throws MissingParameterException 366 * @throws OperationFailedException 367 * @throws PermissionDeniedException authorization failure 368 */ 369 public StatusInfo removeEntryFromInterimRoster(@WebParam(name = "gradeRosterEntryId") String gradeRosterEntryId, @WebParam(name = "gradeRosterId") String gradeRosterId, 370 @WebParam(name = "context") ContextInfo context) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 371 372 /** 373 * Assign any admin or letter grades which have a distinct value using this 374 * method. The keys of those grades is the key of {@link ResultValueInfo} in 375 * the {@link GradeValuesGroupInfo}. TODO - do we need to change the output 376 * to an object instead of boolean? 377 * 378 * @param gradeRosterEntryId 379 * @param assignedGradeKey the result value key 380 * @param context Context information containing the principalId and locale 381 * information about the caller of service operation 382 * @return 383 * @throws DataValidationErrorException One or more values invalid for this 384 * operation 385 * @throws DoesNotExistException 386 * @throws InvalidParameterException 387 * @throws MissingParameterException 388 * @throws OperationFailedException 389 * @throws PermissionDeniedException authorization failure 390 * @throws VersionMismatchException 391 */ 392 public boolean updateGrade(@WebParam(name = "gradeRosterEntryId") String gradeRosterEntryId, @WebParam(name = "assignedGradeKey") String assignedGradeKey, 393 @WebParam(name = "context") ContextInfo context) throws DataValidationErrorException, DoesNotExistException, InvalidParameterException, MissingParameterException, 394 OperationFailedException, PermissionDeniedException, VersionMismatchException; 395 396 /** 397 * Assign any number grade that are in a range since those don't have any 398 * unique key to begin with. Put in the value of the number grade - the 399 * system generates a unique key and persists the grade. 400 * 401 * @param gradeRosterEntryId 402 * @param numberGradeValue 403 * @param context 404 * @return 405 * @throws DataValidationErrorException 406 * @throws DoesNotExistException 407 * @throws InvalidParameterException 408 * @throws MissingParameterException 409 * @throws OperationFailedException 410 * @throws PermissionDeniedException 411 * @throws VersionMismatchException 412 */ 413 public boolean updateNumberGrade(@WebParam(name = "gradeRosterEntryId") String gradeRosterEntryId, @WebParam(name = "numberGradeValue") String numberGradeValue, 414 @WebParam(name = "context") ContextInfo context) throws DataValidationErrorException, DoesNotExistException, InvalidParameterException, MissingParameterException, 415 OperationFailedException, PermissionDeniedException, VersionMismatchException; 416 417 /** 418 * TODO - do we need to change the output to an object instead of boolean? 419 * 420 * @param gradeRosterEntryId 421 * @param assignedGrade 422 * @param context Context information containing the principalId and locale 423 * information about the caller of service operation 424 * @return 425 * @throws DataValidationErrorException One or more values invalid for this 426 * operation 427 * @throws DoesNotExistException 428 * @throws InvalidParameterException 429 * @throws MissingParameterException 430 * @throws OperationFailedException 431 * @throws PermissionDeniedException authorization failure 432 * @throws VersionMismatchException 433 */ 434 public boolean updateCredit(@WebParam(name = "gradeRosterEntryId") String gradeRosterEntryId, @WebParam(name = "creditsEarned") String assignedGrade, 435 @WebParam(name = "context") ContextInfo context) throws DataValidationErrorException, DoesNotExistException, InvalidParameterException, MissingParameterException, 436 OperationFailedException, PermissionDeniedException, VersionMismatchException; 437 }