001: /**********************************************************************************
002: *
003: * $Id: GradebookManager.java 21205 2007-02-09 20:00:15Z ray@media.berkeley.edu $
004: *
005: ***********************************************************************************
006: *
007: * Copyright (c) 2005 The Regents of the University of California, The MIT Corporation
008: *
009: * Licensed under the Educational Community License, Version 1.0 (the "License");
010: * you may not use this file except in compliance with the License.
011: * You may obtain a copy of the License at
012: *
013: * http://www.opensource.org/licenses/ecl1.php
014: *
015: * Unless required by applicable law or agreed to in writing, software
016: * distributed under the License is distributed on an "AS IS" BASIS,
017: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
018: * See the License for the specific language governing permissions and
019: * limitations under the License.
020: *
021: **********************************************************************************/package org.sakaiproject.tool.gradebook.business;
022:
023: import java.util.*;
024:
025: import org.sakaiproject.service.gradebook.shared.ConflictingAssignmentNameException;
026: import org.sakaiproject.service.gradebook.shared.ConflictingSpreadsheetNameException;
027: import org.sakaiproject.service.gradebook.shared.GradebookNotFoundException;
028: import org.sakaiproject.service.gradebook.shared.StaleObjectModificationException;
029: import org.sakaiproject.tool.gradebook.*;
030:
031: /**
032: * Manages Gradebook persistence.
033: *
034: * @author <a href="mailto:jholtzman@berkeley.edu">Josh Holtzman</a>
035: */
036: public interface GradebookManager {
037:
038: /**
039: * Updates a gradebook's representation in persistence.
040: *
041: * If the gradebook's selected grade mapping has been modified, the sort
042: * value on all explicitly graded course grade records must be updated when
043: * the gradebook is updated.
044: *
045: * A gradebook's selected grade mapping may only change (to a different kind
046: * of mapping) if there are no explicitly graded course grade records.
047: *
048: * @param gradebook The gradebook to update
049: * @throws StaleObjectModificationException
050: */
051: public void updateGradebook(Gradebook gradebook)
052: throws StaleObjectModificationException;
053:
054: /**
055: * Fetches a gradebook based on its surrogate key
056: *
057: * @param id The ID of the gradebook
058: * @return The gradebook
059: */
060: public Gradebook getGradebook(Long id);
061:
062: /**
063: * Internal services use a Long ID to identify a gradebook.
064: * External facades use a String UID instead. This method
065: * translates.
066: */
067: public String getGradebookUid(Long id);
068:
069: /**
070: * Fetches a gradebook based on its unique string id
071: *
072: * @param uid The UID of the gradebook
073: * @return The gradebook
074: */
075: public Gradebook getGradebook(String uid)
076: throws GradebookNotFoundException;
077:
078: public Gradebook getGradebookWithGradeMappings(Long id);
079:
080: /**
081: * Removes an assignment from a gradebook. The assignment should not be
082: * deleted, but the assignment and all grade records associated with the
083: * assignment should be ignored by the application. A removed assignment
084: * should not count toward the total number of points in the gradebook.
085: *
086: * @param assignmentId The assignment id
087: */
088: public void removeAssignment(Long assignmentId)
089: throws StaleObjectModificationException;
090:
091: /**
092: * Get all assignment score records for the given set of student UIDs.
093: *
094: * @param assignment
095: * @param studentUids
096: * @return AssignmentGradeRecord list
097: */
098: public List getAssignmentGradeRecords(Assignment assignment,
099: Collection studentUids);
100:
101: /**
102: * Get all course grade records (with autocalculated fields) for the given
103: * gradebook and the given set of student UIDs
104: *
105: * @param gradebookId
106: * @param studentUids
107: * @return CourseGradeRecord list
108: */
109: public List getPointsEarnedCourseGradeRecords(
110: CourseGrade courseGrade, Collection studentUids);
111:
112: /**
113: * As a side-effect, this version of the method calculates the mean course grade.
114: * The proliferation of method signatures is meant to cut back as much as possible on
115: * redundant reads from the assignment grade records.
116: *
117: * @param courseGrade This input argument is modified to include statistical information
118: * @param studentUids
119: * @return
120: */
121: public List<CourseGradeRecord> getPointsEarnedCourseGradeRecordsWithStats(
122: CourseGrade courseGrade, Collection studentUids);
123:
124: public List<CourseGradeRecord> getPointsEarnedCourseGradeRecords(
125: CourseGrade courseGrade, Collection studentUids,
126: Collection assignments, Map scoreMap);
127:
128: public void addToGradeRecordMap(Map gradeRecordMap,
129: List gradeRecords);
130:
131: /**
132: * Gets all grade records that belong to a collection of enrollments in a
133: * gradebook.
134: *
135: * @param gradebookId
136: * @param studentUids
137: */
138: public List getAllAssignmentGradeRecords(Long gradebookId,
139: Collection studentUids);
140:
141: /**
142: * Gets whether there are explicitly entered course grade records in a gradebook.
143: *
144: * @param gradebookId The gradebook
145: * @return Whether there are course grade records that have a non-null enteredGrade field
146: */
147: public boolean isExplicitlyEnteredCourseGradeRecords(
148: Long gradebookId);
149:
150: /**
151: * Gets whether scores have been entered for the given assignment.
152: * (This may include scores for students who are not currently enrolled.)
153: *
154: * @param assignmentId The assignment
155: * @return How many scores have been entered for the assignment
156: */
157: public boolean isEnteredAssignmentScores(Long assignmentId);
158:
159: /**
160: * Updates the grade records in the GradeRecordSet.
161: * Implementations of this method should add a new GradingEvent for each
162: * grade record modified, and should update the autocalculated value for
163: * each graded student's CourseGradeRecord.
164: *
165: * @return The set of student UIDs who were given scores higher than the
166: * assignment's value.
167: */
168: public Set updateAssignmentGradeRecords(Assignment assignment,
169: Collection gradeRecords)
170: throws StaleObjectModificationException;
171:
172: public Set updateAssignmentGradesAndComments(Assignment assignment,
173: Collection gradeRecords, Collection comments)
174: throws StaleObjectModificationException;
175:
176: public void updateComments(Collection comments)
177: throws StaleObjectModificationException;
178:
179: /**
180: * Updates the grade records for the keys (student IDs) in the studentsToPoints map.
181: * Map values must be valid strings (that exist in the gradebook's grade
182: * mapping) or nulls.
183: *
184: * @param studentsToPoints A Map of student IDs to grades
185: */
186: public void updateCourseGradeRecords(CourseGrade courseGrade,
187: final Collection gradeRecords)
188: throws StaleObjectModificationException;
189:
190: /**
191: * Gets all grade records for a single student in a single gradebook,
192: * not including the course grade.
193: *
194: * @param gradebookId The gradebook id
195: * @param studentId The unique student identifier
196: *
197: * @return A List of all of this student's grade records in the gradebook
198: */
199: public List getStudentGradeRecords(Long gradebookId,
200: String studentId);
201:
202: /**
203: * Gets the course grade for a single student.
204: */
205: public CourseGradeRecord getStudentCourseGradeRecord(
206: Gradebook gradebook, String studentId);
207:
208: /**
209: * Gets the grading events for the enrollments on the given gradable object.
210: *
211: * @param gradableObject
212: * @param enrollments
213: * @return
214: */
215: public GradingEvents getGradingEvents(
216: GradableObject gradableObject, Collection studentUids);
217:
218: /**
219: * Fetches a List of Assignments, but does not populate non-persistent
220: * fields.
221: *
222: * @param gradebookId The gradebook ID
223: * @param sortBy The field by which to sort the list.
224: * @return A list of Assignments with only persistent fields populated
225: */
226: public List getAssignments(Long gradebookId, String sortBy,
227: boolean ascending);
228:
229: /**
230: * Convenience method to get assignments with the default sort ordering
231: *
232: * @param gradebookId The gradebook ID
233: */
234: public List getAssignments(Long gradebookId);
235:
236: /**
237: * Fetches a List of Assignments for a given gradebook, and populates the
238: * Assignments with all of the statistics fields available in the Assignment
239: * object.
240: *
241: * @param gradebookId The gradebook ID
242: * @param studentUids The current enrollment list to filter dropped students
243: * from the calculation
244: * @param sortBy The field by which to sort the list.
245: * @return A list of Assignments with their statistics fields populated
246: */
247: public List getAssignmentsWithStats(Long gradebookId,
248: String sortBy, boolean ascending);
249:
250: /**
251: * Same as the other getAssignmentsWithStats except for tacking the
252: * CourseGrade (with statistics) at the end of the list. This is
253: * combined into one call as a way to avoid either exposing the
254: * full enrollment list for the site or fetching it twice.
255: */
256: public List getAssignmentsAndCourseGradeWithStats(Long gradebookId,
257: String sortBy, boolean ascending);
258:
259: /**
260: * Fetches an assignment
261: *
262: * @param assignmentId The assignment ID
263: * @return The assignment
264: */
265: public Assignment getAssignment(Long assignmentId);
266:
267: /**
268: * Fetches an assignment and populates its non-persistent statistics
269: * fields.
270: *
271: * @param assignmentId The assignment ID
272: * @param studentUids The current enrollment list to filter dropped students
273: * from the calculation
274: * @return The GradableObject with all statistics fields populated
275: */
276: public Assignment getAssignmentWithStats(Long assignmentId);
277:
278: /**
279: * Add a new assignment to a gradebook
280: *
281: * @param gradebookId The gradebook ID to which this new assignment belongs
282: * @param name The assignment's name (must be unique in the gradebook and not be null)
283: * @param points The number of points possible for this assignment (must not be null)
284: * @param dueDate The due date for the assignment (optional)
285: * @param isNotCounted True if the assignment should not count towards the final course grade (optional)
286: * @param isReleased True if the assignment should be release/ or visble to students
287: * @return The ID of the new assignment
288: */
289:
290: public Long createAssignment(Long gradebookId, String name,
291: Double points, Date dueDate, Boolean isNotCounted,
292: Boolean isReleased)
293: throws ConflictingAssignmentNameException,
294: StaleObjectModificationException;
295:
296: /**
297: * Updates an existing assignment
298: */
299: public void updateAssignment(Assignment assignment)
300: throws ConflictingAssignmentNameException,
301: StaleObjectModificationException;
302:
303: /**
304: * Fetches the course grade for a gradebook as found in the database.
305: * No non-persistent fields (such as points earned) are filled in.
306: *
307: * @param gradebookId The gradebook id
308: * @return The course grade
309: */
310: public CourseGrade getCourseGrade(Long gradebookId);
311:
312: public double getTotalPoints(Long gradebookId);
313:
314: /**
315: * Fetches a spreadsheet that has been saved
316: *
317: * @param spreadsheetId
318: * @return The saved spreadsheet object
319: */
320: public Spreadsheet getSpreadsheet(Long spreadsheetId);
321:
322: /**
323: *
324: * @param gradebookId
325: * @return a Collection of spreadsheets
326: */
327: public List getSpreadsheets(Long gradebookId);
328:
329: /**
330: *
331: * @param spreadsheetid
332: * @throws StaleObjectModificationException
333: */
334:
335: public void removeSpreadsheet(Long spreadsheetid)
336: throws StaleObjectModificationException;
337:
338: /**
339: * create a net spreadsheet
340: *
341: * @param gradebookId
342: * @param name
343: * @param creator
344: * @param dateCreated
345: * @param content
346: * @return
347: * @throws ConflictingSpreadsheetNameException StaleObjectModificationException
348: */
349: public Long createSpreadsheet(Long gradebookId, String name,
350: String creator, Date dateCreated, String content)
351: throws ConflictingSpreadsheetNameException,
352: StaleObjectModificationException;
353:
354: /**
355: *
356: * @param assignment
357: * @param studentIds
358: * @return
359: */
360: public List getComments(Assignment assignment, Collection studentIds);
361:
362: /**method to get comments for a assignments for a student in a gradebook
363: *
364: * @param studentId
365: * @param gradebookId
366: * @return
367: */
368: public List getStudentAssignmentComments(String studentId,
369: Long gradebookId);
370: }
|