001: /**********************************************************************************
002: *
003: * $Id: GradebookService.java 28316 2007-04-04 18:18:49Z ajpoland@iupui.edu $
004: *
005: ***********************************************************************************
006: *
007: * Copyright (c) 2005, 2006 The Regents of the University of California, The MIT Corporation
008: *
009: * Licensed under the Educational Community License Version 1.0 (the "License");
010: * By obtaining, using and/or copying this Original Work, you agree that you have read,
011: * understand, and will comply with the terms and conditions of the Educational Community License.
012: * You may obtain a copy of the License at:
013: *
014: * http://www.opensource.org/licenses/ecl1.php
015: *
016: * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
017: * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
018: * AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
019: * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
020: * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
021: *
022: **********************************************************************************/package org.sakaiproject.service.gradebook.shared;
023:
024: import java.util.Collection;
025: import java.util.Date;
026: import java.util.List;
027: import java.util.Map;
028:
029: /**
030: * This is the externally exposed API of the gradebook application.
031: *
032: * This interface is principally intended for clients of application services --
033: * that is, clients who want to "act like the Gradebook would" to automate what
034: * would normally be done in the UI, including any authorization checks.
035: *
036: * As a result, these methods may throw security exceptions. Call the service's
037: * authorization-check methods if you want to avoid them.
038: *
039: * <p>WARNING: For documentation of the deprecated methods, please see the
040: * service interfaces which own them.
041: */
042: public interface GradebookService {
043: // Application service hooks.
044:
045: /**
046: * Checks to see whether a gradebook with the given uid exists.
047: *
048: * @param gradebookUid The gradebook UID to check
049: * @return Whether the gradebook exists
050: */
051: public boolean isGradebookDefined(String gradebookUid);
052:
053: /**
054: * Check to see if the current user is allowed to grade the given student in
055: * the given gradebook. This will give clients a chance to avoid a security
056: * exception.
057: */
058: public boolean isUserAbleToGradeStudent(String gradebookUid,
059: String studentUid);
060:
061: /**
062: * @return Returns a list of Assignment objects describing the assignments
063: * that are currently defined in the given gradebook.
064: */
065: public List getAssignments(String gradebookUid)
066: throws GradebookNotFoundException;
067:
068: /**
069: * @param gradebookUid
070: * @param assignmentName
071: * @return the assignment definition, or null if not found
072: * @throws GradebookNotFoundException
073: * @throws AssessmentNotFoundException
074: */
075: public Assignment getAssignment(String gradebookUid,
076: String assignmentName) throws GradebookNotFoundException;
077:
078: /**
079: * Besides the declared exceptions, possible runtime exceptions include:
080: * <ul>
081: * <li> SecurityException - If the current user is not authorized to view
082: * the student's score
083: * </ul>
084: *
085: * @return Returns the current score for the student, or null if no score
086: * has been assigned yet.
087: */
088: public Double getAssignmentScore(String gradebookUid,
089: String assignmentName, String studentUid)
090: throws GradebookNotFoundException,
091: AssessmentNotFoundException;
092:
093: /**
094: * Get the comment (if any) currently provided for the given combination
095: * of student and assignment.
096: *
097: * @param gradebookUid
098: * @param assignmentName
099: * @param studentUid
100: * @return null if no comment is avaailable
101: * @throws GradebookNotFoundException
102: * @throws AssessmentNotFoundException
103: */
104: public CommentDefinition getAssignmentScoreComment(
105: String gradebookUid, String assignmentName,
106: String studentUid) throws GradebookNotFoundException,
107: AssessmentNotFoundException;
108:
109: /**
110: * Besides the declared exceptions, possible runtime exceptions include:
111: * <ul>
112: * <li> SecurityException - If the current user is not authorized to grade
113: * the student, or if the assignment is externally maintained.
114: * <li> StaleObjectModificationException - If the student's scores have been
115: * edited by someone else during this transaction.
116: * </ul>
117: *
118: * @param clientServiceDescription
119: * What to display as the programmatic source of the score (e.g.,
120: * "Message Center").
121: */
122: public void setAssignmentScore(String gradebookUid,
123: String assignmentName, String studentUid, Double score,
124: String clientServiceDescription)
125: throws GradebookNotFoundException,
126: AssessmentNotFoundException;
127:
128: /**
129: * Provide a student-viewable comment on the score (or lack of score) associated
130: * with the given assignment.
131: *
132: * @param gradebookUid
133: * @param assignmentName
134: * @param studentUid
135: * @param comment a plain text comment, or null to remove any currrent comment
136: * @throws GradebookNotFoundException
137: * @throws AssessmentNotFoundException
138: */
139: public void setAssignmentScoreComment(String gradebookUid,
140: String assignmentName, String studentUid, String comment)
141: throws GradebookNotFoundException,
142: AssessmentNotFoundException;
143:
144: /**
145: * Check to see if an assignment with the given name already exists in the
146: * given gradebook. This will give clients a chance to avoid the
147: * ConflictingAssignmentNameException.
148: */
149: public boolean isAssignmentDefined(String gradebookUid,
150: String assignmentTitle) throws GradebookNotFoundException;
151:
152: /**
153: * Get an archivable definition of gradebook data suitable for migration
154: * between sites. Assignment definitions and the currently selected grading
155: * scale are included. Student view options and all information related
156: * to specific students or instructors (such as scores) are not.
157: * @param gradebookUid
158: * @return a versioned XML string
159: */
160: public String getGradebookDefinitionXml(String gradebookUid);
161:
162: /**
163: * Attempt to merge archived gradebook data (notably the assignnments) into a new gradebook.
164: *
165: * Assignment definitions whose names match assignments that are already in
166: * the targeted gradebook will be skipped.
167: *
168: * Imported assignments will not automatically be released to students, even if they
169: * were released in the original gradebook.
170: *
171: * Externally managed assessments will not be imported, since such imports
172: * should be handled by the external assessment engine.
173: *
174: * If possible, the targeted gradebook's selected grading scale will be set
175: * to match the archived grading scale. If there are any mismatches that make
176: * this impossible, the existing grading scale will be left alone, but assignment
177: * imports will still happen.
178: *
179: * @param toGradebookUid
180: * @param fromGradebookXml
181: */
182: public void mergeGradebookDefinitionXml(String toGradebookUid,
183: String fromGradebookXml);
184:
185: /**
186: * Create a new Gradebook-managed assignment.
187: *
188: * @param assignmentDefinition
189: */
190: public void addAssignment(String gradebookUid,
191: Assignment assignmentDefinition);
192:
193: /**
194: * Modify the definition of an existing Gradebook-managed assignment.
195: *
196: * Clients should be aware that it's allowed to change the points value of an
197: * assignment even if students have already been scored on it. Any existing
198: * scores will not be adjusted.
199: *
200: * This method cannot be used to modify the defintions of externally-managed
201: * assessments or to make Gradebook-managed assignments externally managed.
202: *
203: * @param assignmentName the name of the assignment that needs to be changed
204: * @param assignmentDefinition the new properties of the assignment
205: */
206: public void updateAssignment(String gradebookUid,
207: String assignmentName, Assignment assignmentDefinition);
208:
209: // Site management hooks.
210:
211: /**
212: * @deprecated Replaced by
213: * {@link GradebookFrameworkService#addGradebook(String, String)}
214: */
215: public void addGradebook(String uid, String name);
216:
217: /**
218: * @deprecated Replaced by
219: * {@link GradebookFrameworkService#deleteGradebook(String)}
220: */
221: public void deleteGradebook(String uid)
222: throws GradebookNotFoundException;
223:
224: /**
225: * @deprecated Replaced by
226: * {@link GradebookFrameworkService#setAvailableGradingScales(Collection)}
227: */
228: public void setAvailableGradingScales(
229: Collection gradingScaleDefinitions);
230:
231: /**
232: * @deprecated Replaced by
233: * {@link GradebookFrameworkService#setDefaultGradingScale(String)}
234: */
235: public void setDefaultGradingScale(String uid);
236:
237: // External assessment management hooks.
238:
239: /**
240: * @deprecated Replaced by {@link GradebookExternalAssessmentService#addExternalAssessment(String, String, String, String, double, Date, String)}
241: */
242: public void addExternalAssessment(String gradebookUid,
243: String externalId, String externalUrl, String title,
244: double points, Date dueDate,
245: String externalServiceDescription)
246: throws GradebookNotFoundException,
247: ConflictingAssignmentNameException,
248: ConflictingExternalIdException,
249: AssignmentHasIllegalPointsException;
250:
251: /**
252: * @deprecated Replaced by {@link GradebookExternalAssessmentService#updateExternalAssessment(String, String, String, String, double, Date)}
253: */
254: public void updateExternalAssessment(String gradebookUid,
255: String externalId, String externalUrl, String title,
256: double points, Date dueDate)
257: throws GradebookNotFoundException,
258: AssessmentNotFoundException,
259: ConflictingAssignmentNameException,
260: AssignmentHasIllegalPointsException;
261:
262: /**
263: * @deprecated Replaced by {@link GradebookExternalAssessmentService#removeExternalAssessment(String, String)}
264: */
265: public void removeExternalAssessment(String gradebookUid,
266: String externalId) throws GradebookNotFoundException,
267: AssessmentNotFoundException;
268:
269: /**
270: * @deprecated Replaced by {@link GradebookExternalAssessmentService#updateExternalAssessmentScore(String, String, String, Double)}
271: */
272: public void updateExternalAssessmentScore(String gradebookUid,
273: String externalId, String studentUid, Double points)
274: throws GradebookNotFoundException,
275: AssessmentNotFoundException;
276:
277: /**
278: * @deprecated Replaced by {@link GradebookExternalAssessmentService#updateExternalAssessmentScores(String, String, Map)}
279: */
280: public void updateExternalAssessmentScores(String gradebookUid,
281: String externalId, Map studentUidsToScores)
282: throws GradebookNotFoundException,
283: AssessmentNotFoundException;
284:
285: /**
286: * @deprecated Replaced by {@link GradebookExternalAssessmentService#isExternalAssignmentDefined(String, String)}
287: */
288: public boolean isExternalAssignmentDefined(String gradebookUid,
289: String externalId) throws GradebookNotFoundException;
290:
291: }
|