View Javadoc

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 }