001: /**********************************************************************************
002: *
003: * $Id: GradebookExternalAssessmentService.java 20819 2007-01-30 22:29:31Z ray@media.berkeley.edu $
004: *
005: ***********************************************************************************
006: *
007: * Copyright (c) 2007 The Regents of the University of California
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.service.gradebook.shared;
022:
023: import java.util.Date;
024: import java.util.Map;
025:
026: /**
027: * This service is designed for use by external assessment engines. These use
028: * the Gradebook as a passive mirror of their own assignments and scores,
029: * letting Gradebook users see those assignments alongside Gradebook-managed
030: * assignments, and combine them when calculating a course grade. The Gradebook
031: * application itself will not modify externally-managed assignments and scores.
032: *
033: * <b>WARNING</b>: Because the Gradebook project team is not responsible for
034: * defining the external clients' requirements, the Gradebook service does not
035: * attempt to guess at their authorization needs. Our administrative and
036: * external-assessment methods simply follow orders and assume that the caller
037: * has taken the responsibility of "doing the right thing." DO NOT wrap these
038: * methods in an open web service!
039: */
040:
041: public interface GradebookExternalAssessmentService {
042: /**
043: * Add an externally-managed assessment to a gradebook to be treated as a
044: * read-only assignment. The gradebook application will not modify the
045: * assessment properties or create any scores for the assessment.
046: * Since each assignment in a given gradebook must have a unique name,
047: * conflicts are possible.
048: *
049: * @param externalId
050: * some unique identifier which Samigo uses for the assessment.
051: * The externalId is globally namespaced within the gradebook, so
052: * if other apps decide to put assessments into the gradebook,
053: * they should prefix their externalIds with a well known (and
054: * unique within sakai) string.
055: * @param externalUrl
056: * a link to go to if the instructor or student wants to look at the assessment
057: * in Samigo; if null, no direct link will be provided in the
058: * gradebook, and the user will have to navigate to the assessment
059: * within the other application
060: * @param points
061: * this is the total amount of points available and must be greater than zero
062: *
063: * @param externalServiceDescription
064: * what to display as the source of the assignment (e.g., "from Samigo")
065: *
066: */
067: public void addExternalAssessment(String gradebookUid,
068: String externalId, String externalUrl, String title,
069: double points, Date dueDate,
070: String externalServiceDescription)
071: throws GradebookNotFoundException,
072: ConflictingAssignmentNameException,
073: ConflictingExternalIdException,
074: AssignmentHasIllegalPointsException;
075:
076: public void updateExternalAssessment(String gradebookUid,
077: String externalId, String externalUrl, String title,
078: double points, Date dueDate)
079: throws GradebookNotFoundException,
080: AssessmentNotFoundException,
081: ConflictingAssignmentNameException,
082: AssignmentHasIllegalPointsException;
083:
084: /**
085: * Remove the assessment reference from the gradebook. Although Samigo
086: * doesn't currently delete assessments, an instructor can retract an
087: * assessment to keep it from students. Since such an assessment would
088: * presumably no longer be used to calculate final grades, Samigo should
089: * also remove that assessment from the gradebook.
090: *
091: * @param externalId
092: * the UID of the assessment
093: */
094: public void removeExternalAssessment(String gradebookUid,
095: String externalId) throws GradebookNotFoundException,
096: AssessmentNotFoundException;
097:
098: /**
099: * Updates an external score for an external assignment in the gradebook.
100: *
101: * @param gradebookUid
102: * The Uid of the gradebook
103: * @param externalId
104: * The external ID of the assignment/assessment
105: * @param studentUid
106: * The unique id of the student
107: * @param points
108: * The number of points earned on this assessment, or null if a score
109: * should be removed
110: */
111: public void updateExternalAssessmentScore(String gradebookUid,
112: String externalId, String studentUid, Double points)
113: throws GradebookNotFoundException,
114: AssessmentNotFoundException;
115:
116: /**
117: * Updates a set of external scores for an external assignment in the gradebook.
118: *
119: * @param gradebookUid
120: * The Uid of the gradebook
121: * @param externalId
122: * The external ID of the assignment/assessment
123: * @param studentUidsToScores
124: * A map whose String keys are the unique ID strings of the students and whose
125: * Double values are points earned on this assessment or null if the score
126: * should be removed.
127: */
128: public void updateExternalAssessmentScores(String gradebookUid,
129: String externalId, Map studentUidsToScores)
130: throws GradebookNotFoundException,
131: AssessmentNotFoundException;
132:
133: /**
134: * Check to see if an assignment with the given name already exists
135: * in the given gradebook. This will give external assessment systems
136: * a chance to avoid the ConflictingAssignmentNameException.
137: */
138: public boolean isAssignmentDefined(String gradebookUid,
139: String assignmentTitle) throws GradebookNotFoundException;
140:
141: /**
142: * Check to see if an assignment with the given external id already exists
143: * in the given gradebook. This will give external assessment systems
144: * a chance to avoid the ConflictingExternalIdException.
145: *
146: * @param gradebookUid The gradebook's unique identifier
147: * @param externalId The external assessment's external identifier
148: */
149: public boolean isExternalAssignmentDefined(String gradebookUid,
150: String externalId) throws GradebookNotFoundException;
151:
152: /**
153: * Checks to see whether a gradebook with the given uid exists.
154: *
155: * @param gradebookUid
156: * The gradebook UID to check
157: * @return Whether the gradebook exists
158: */
159: public boolean isGradebookDefined(String gradebookUid);
160:
161: /**
162: * Break the connection between an external assessment engine and an assessment which
163: * it created, giving it up to the Gradebook application to control from now on.
164: *
165: * @param gradebookUid
166: * @param externalId
167: */
168: public void setExternalAssessmentToGradebookAssignment(
169: String gradebookUid, String externalId);
170:
171: }
|