org.sakaiproject.service.gradebook.shared
Interface GradebookService

public interface GradebookService

This is the externally exposed API of the gradebook application. This interface is principally intended for clients of application services -- that is, clients who want to "act like the Gradebook would" to automate what would normally be done in the UI, including any authorization checks. As a result, these methods may throw security exceptions. Call the service's authorization-check methods if you want to avoid them.

WARNING: For documentation of the deprecated methods, please see the service interfaces which own them.

Nested Class Summary

static class

GradebookService.PointsPossibleValidation An enum for defining valid/invalid information for a points possible/relative weight value for a gradebook item.

Field Summary

static int	CATEGORY_TYPE_NO_CATEGORY
static int	CATEGORY_TYPE_ONLY_CATEGORY
static int	CATEGORY_TYPE_WEIGHTED_CATEGORY
static String	enableLetterGradeString
static int	GRADE_TYPE_LETTER
static int	GRADE_TYPE_PERCENTAGE
static int	GRADE_TYPE_POINTS
static String	gradePermission
static Comparator	lettergradeComparator
static MathContext	MATH_CONTEXT
static String[]	validLetterGrade
static String	viewPermission

Method Summary

void	addAssignment(String gradebookUid, Assignment assignmentDefinition) Create a new Gradebook-managed assignment.
void	addExternalAssessment(String gradebookUid, String externalId, String externalUrl, String title, double points, Date dueDate, String externalServiceDescription) Deprecated. Replaced by addExternalAssessment(String, String, String, Boolean)
void	addExternalAssessment(String gradebookUid, String externalId, String externalUrl, String title, Double points, Date dueDate, String externalServiceDescription, Boolean ungraded) Deprecated. Replaced by GradebookExternalAssessmentService.addExternalAssessment(String, String, String, String, Double, Date, String, Boolean)
void	addGradebook(String uid, String name) Deprecated. Replaced by GradebookFrameworkService.addGradebook(String, String)
boolean	checkStudentsNotSubmitted(String gradebookUid)
boolean	checkStuendsNotSubmitted(String gradebookUid)
boolean	currentUserHasEditPerm(String gradebookUid)
boolean	currentUserHasGradeAllPerm(String gradebookUid)
boolean	currentUserHasGradingPerm(String gradebookUid)
boolean	currentUserHasViewOwnGradesPerm(String gradebookUid)
void	deleteGradebook(String uid) Deprecated. Replaced by GradebookFrameworkService.deleteGradebook(String)
void	finalizeGrades(String gradebookUid) Finalize the gradebook's course grades by setting all still-unscored assignments to zero scores.
Assignment	getAssignment(String gradebookUid, Long gbItemId)
Assignment	getAssignment(String gradebookUid, String assignmentName)
List	getAssignments(String gradebookUid)
Double	getAssignmentScore(String gradebookUid, Long gbItemId, String studentUid) Deprecated. Replaced by getAssignmentScoreString(String, Long, String)
Double	getAssignmentScore(String gradebookUid, String assignmentName, String studentUid) Deprecated. Replaced by getAssignmentScoreString(String, String, String)
CommentDefinition	getAssignmentScoreComment(String gradebookUid, Long gbItemId, String studentUid) Get the comment (if any) currently provided for the given combination of student and assignment.
CommentDefinition	getAssignmentScoreComment(String gradebookUid, String assignmentName, String studentUid) Get the comment (if any) currently provided for the given combination of student and assignment.
String	getAssignmentScoreString(String gradebookUid, Long gbItemId, String studentUid) Get student's assignment's score as string.
String	getAssignmentScoreString(String gradebookUid, String assignmentName, String studentUid) Get student's assignment's score as string.
Map	getCalculatedCourseGrade(String gradebookUid) Get a Map of auto calculated CourseGrade for students.
List	getCategories(Long gradebookId) method to get all categories for a gradebook.
List<CategoryDefinition>	getCategoryDefinitions(String gradebookUid)
Map	getEnteredCourseGrade(String gradebookUid) Get a Map of overridden CourseGrade for students.
Map	getFixedGrade(String gradebookUid) Get fixed grades for students by using course grade scale.
Map	getFixedPoint(String gradebookUid) Get fixed earned points for students by using course grade scale.
Object	getGradebook(String uid) return Object to avoid circular dependency with sakai-gradebook-tool
String	getGradebookDefinitionXml(String gradebookUid) Get an archivable definition of gradebook data suitable for migration between sites.
GradeDefinition	getGradeDefinitionForStudentForItem(String gradebookUid, Long gbItemId, String studentUid)
int	getGradeEntryType(String gradebookUid)
List<GradeDefinition>	getGradesForStudentsForItem(String gradebookUid, Long gradableObjectId, List<String> studentIds)
String	getGradeViewFunctionForUserForStudentForItem(String gradebookUid, Long itemId, String studentUid) Check to see if current user may grade or view the given student for the given item in the given gradebook.
String	getGradeViewFunctionForUserForStudentForItem(String gradebookUid, String itemName, String studentUid) Check to see if current user may grade or view the given student for the given item in the given gradebook.
Map	getImportCourseGrade(String gradebookUid)
String	getLowestPossibleGradeForGbItem(String gradebookUid, Long gradebookItemId)
Map	getOldPoint(String gradebookUid) Get old earned points for students by using letter grade scale.
List<Assignment>	getViewableAssignmentsForCurrentUser(String gradebookUid)
Map	getViewableSectionUuidToNameMap(String gradebookUid) Using the grader permissions, return map of section uuid to section name that includes all sections that the current user may view or grade
Map<String,String>	getViewableStudentsForItemForCurrentUser(String gradebookUid, Long gradableObjectId)
Map<String,String>	getViewableStudentsForItemForUser(String userUid, String gradebookUid, Long gradableObjectId)
List<String>	identifyStudentsWithInvalidGrades(String gradebookUid, Map<String,String> studentIdToGradeMap)
boolean	isAssignmentDefined(String gradebookUid, String assignmentTitle) Check to see if an assignment with the given name already exists in the given gradebook.
boolean	isExternalAssignmentDefined(String gradebookUid, String externalId) Deprecated. Replaced by GradebookExternalAssessmentService.isExternalAssignmentDefined(String, String)
boolean	isGradableObjectDefined(Long gradableObjectId)
boolean	isGradebookDefined(String gradebookUid) Checks to see whether a gradebook with the given uid exists.
boolean	isGradeValid(String gradebookUuid, String grade)
GradebookService.PointsPossibleValidation	isPointsPossibleValid(String gradebookUid, Assignment gradebookItem, Double pointsPossible)
boolean	isUserAbleToGradeItemForStudent(String gradebookUid, Long itemId, String studentUid) Check to see if the current user is allowed to grade the given item for the given student in the given gradebook.
boolean	isUserAbleToGradeItemForStudent(String gradebookUid, String itemName, String studentUid) Check to see if the current user is allowed to grade the given item for the given student in the given gradebook.
boolean	isUserAbleToViewItemForStudent(String gradebookUid, Long itemId, String studentUid) Check to see if the current user is allowed to view the given item for the given student in the given gradebook.
boolean	isUserAbleToViewItemForStudent(String gradebookUid, String itemName, String studentUid) Check to see if the current user is allowed to view the given item for the given student in the given gradebook.
boolean	isUserAllowedToGrade(String gradebookUid, String userUid)
boolean	isUserAllowedToGradeAll(String gradebookUid, String userUid)
void	mergeGradebookDefinitionXml(String toGradebookUid, String fromGradebookXml) Attempt to merge archived gradebook data (notably the assignnments) into a new gradebook.
void	removeAssignment(Long assignmentId) Removes an assignment from a gradebook.
void	removeCategory(Long categoryId) remove category from gradebook
void	removeExternalAssessment(String gradebookUid, String externalId) Deprecated. Replaced by GradebookExternalAssessmentService.removeExternalAssessment(String, String)
void	saveGradeAndCommentForStudent(String gradebookUid, Long gradableObjectId, String studentId, String grade, String comment) Save a student score and comment for a gradebook item.
void	saveGradesAndComments(String gradebookUid, Long gradableObjectId, List<GradeDefinition> gradeDefList) Given a list of GradeDefinitions for students for a given gradebook and gradable object, will save the associated scores and comments.
void	setAssignmentScore(String gradebookUid, String assignmentName, String studentUid, Double score, String clientServiceDescription) Deprecated. Replaced by setAssignmentScoreString(String, String, String, String, String)
void	setAssignmentScoreComment(String gradebookUid, String assignmentName, String studentUid, String comment) Provide a student-viewable comment on the score (or lack of score) associated with the given assignment.
void	setAssignmentScoreString(String gradebookUid, String assignmentName, String studentUid, String score, String clientServiceDescription) set student's score for assignment.
void	setAvailableGradingScales(Collection gradingScaleDefinitions) Deprecated. Replaced by GradebookFrameworkService.setAvailableGradingScales(Collection)
void	setDefaultGradingScale(String uid) Deprecated. Replaced by GradebookFrameworkService.setDefaultGradingScale(String)
void	transferGradebookDefinitionXml(String fromGradebookUid, String toGradebookUid, String fromGradebookXml) Attempt to transfer gradebook data with Category and weight and settings
void	updateAssignment(String gradebookUid, String assignmentName, Assignment assignmentDefinition) Modify the definition of an existing Gradebook-managed assignment.
void	updateExternalAssessment(String gradebookUid, String externalId, String externalUrl, String title, double points, Date dueDate) Deprecated. Replaced by updateExternalAssessment(String, String, String, String, Double, Date)
void	updateExternalAssessment(String gradebookUid, String externalId, String externalUrl, String title, Double points, Date dueDate) Deprecated. Replaced by GradebookExternalAssessmentService.updateExternalAssessment(String, String, String, String, Double, Date, Boolean)
void	updateExternalAssessmentScore(String gradebookUid, String externalId, String studentUid, Double points) Deprecated. Replaced by GradebookExternalAssessmentService#updateExternalAssessmentScore(String, String, String, Double)
void	updateExternalAssessmentScores(String gradebookUid, String externalId, Map studentUidsToScores) Deprecated. Replaced by GradebookExternalAssessmentService.updateExternalAssessmentScoresString(String, String, Map)

Field Detail

GRADE_TYPE_POINTS

static final int GRADE_TYPE_POINTS

See Also:

Constant Field Values

GRADE_TYPE_PERCENTAGE

static final int GRADE_TYPE_PERCENTAGE

See Also:

Constant Field Values

GRADE_TYPE_LETTER

static final int GRADE_TYPE_LETTER

See Also:

Constant Field Values

CATEGORY_TYPE_NO_CATEGORY

static final int CATEGORY_TYPE_NO_CATEGORY

See Also:

Constant Field Values

CATEGORY_TYPE_ONLY_CATEGORY

static final int CATEGORY_TYPE_ONLY_CATEGORY

See Also:

Constant Field Values

CATEGORY_TYPE_WEIGHTED_CATEGORY

static final int CATEGORY_TYPE_WEIGHTED_CATEGORY

See Also:

Constant Field Values

validLetterGrade

static final String[] validLetterGrade

gradePermission

static final String gradePermission

See Also:

Constant Field Values

viewPermission

static final String viewPermission

See Also:

Constant Field Values

enableLetterGradeString

static final String enableLetterGradeString

See Also:

Constant Field Values

MATH_CONTEXT

static final MathContext MATH_CONTEXT

lettergradeComparator

static final Comparator lettergradeComparator

Method Detail

isGradebookDefined

boolean isGradebookDefined(String gradebookUid)

Checks to see whether a gradebook with the given uid exists.

Parameters:

gradebookUid - The gradebook UID to check

Returns:

Whether the gradebook exists

isUserAbleToGradeItemForStudent

boolean isUserAbleToGradeItemForStudent(String gradebookUid,
                                        Long itemId,
                                        String studentUid)

Check to see if the current user is allowed to grade the given item for the given student in the given gradebook. This will give clients a chance to avoid a security exception.

isUserAbleToGradeItemForStudent

boolean isUserAbleToGradeItemForStudent(String gradebookUid,
                                        String itemName,
                                        String studentUid)

Check to see if the current user is allowed to grade the given item for the given student in the given gradebook. This will give clients a chance to avoid a security exception.

Parameters:

gradebookUid -

itemId -

studentUid -

Returns:

isUserAbleToViewItemForStudent

boolean isUserAbleToViewItemForStudent(String gradebookUid,
                                       Long itemId,
                                       String studentUid)

Check to see if the current user is allowed to view the given item for the given student in the given gradebook. This will give clients a chance to avoid a security exception.

Parameters:

gradebookUid -

itemId -

studentUid -

Returns:

isUserAbleToViewItemForStudent

boolean isUserAbleToViewItemForStudent(String gradebookUid,
                                       String itemName,
                                       String studentUid)

Check to see if the current user is allowed to view the given item for the given student in the given gradebook. This will give clients a chance to avoid a security exception.

Parameters:

gradebookUid -

itemName -

studentUid -

Returns:

getGradeViewFunctionForUserForStudentForItem

String getGradeViewFunctionForUserForStudentForItem(String gradebookUid,
                                                    Long itemId,
                                                    String studentUid)

Check to see if current user may grade or view the given student for the given item in the given gradebook. Returns string representation of function per GradebookService vars (view/grade) or null if no permission

Parameters:

gradebookUid -

itemId -

studentUid -

Returns:

GradebookService.gradePermission, GradebookService.viewPermission, or null if no permission

getGradeViewFunctionForUserForStudentForItem

String getGradeViewFunctionForUserForStudentForItem(String gradebookUid,
                                                    String itemName,
                                                    String studentUid)

Check to see if current user may grade or view the given student for the given item in the given gradebook. Returns string representation of function per GradebookService vars (view/grade) or null if no permission

Parameters:

gradebookUid -

itemName -

studentUid -

Returns:

GradebookService.gradePermission, GradebookService.viewPermission, or null if no permission

getAssignments

List getAssignments(String gradebookUid)
                    throws GradebookNotFoundException

Returns:

Returns a list of Assignment objects describing the assignments that are currently defined in the given gradebook.

Throws:

GradebookNotFoundException

getAssignment

Assignment getAssignment(String gradebookUid,
                         String assignmentName)
                         throws GradebookNotFoundException

Parameters:

gradebookUid -

assignmentName -

Returns:

the assignment definition, or null if not found

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getAssignment

Assignment getAssignment(String gradebookUid,
                         Long gbItemId)
                         throws AssessmentNotFoundException

Parameters:

gradebookUid -

gbItemId -

Returns:

the associated Assignment with the given gbItemId

Throws:

AssessmentNotFoundException

getAssignmentScore

Double getAssignmentScore(String gradebookUid,
                          String assignmentName,
                          String studentUid)
                          throws GradebookNotFoundException,
                                 AssessmentNotFoundException

Deprecated. Replaced by getAssignmentScoreString(String, String, String)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getAssignmentScore

Double getAssignmentScore(String gradebookUid,
                          Long gbItemId,
                          String studentUid)
                          throws GradebookNotFoundException,
                                 AssessmentNotFoundException

Deprecated. Replaced by getAssignmentScoreString(String, Long, String)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getGradeDefinitionForStudentForItem

GradeDefinition getGradeDefinitionForStudentForItem(String gradebookUid,
                                                    Long gbItemId,
                                                    String studentUid)
                                                    throws GradebookNotFoundException,
                                                           AssessmentNotFoundException

Parameters:

gradebookUid -

gbItemId -

studentUid -

Returns:

Returns a GradeDefinition for the student, respecting the grade entry type for the gradebook (ie in %, letter grade, or points format). Returns null if no grade

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getAssignmentScoreComment

CommentDefinition getAssignmentScoreComment(String gradebookUid,
                                            String assignmentName,
                                            String studentUid)
                                            throws GradebookNotFoundException,
                                                   AssessmentNotFoundException

Get the comment (if any) currently provided for the given combination of student and assignment.

Parameters:

gradebookUid -

assignmentName -

studentUid -

Returns:

null if no comment is avaailable

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getAssignmentScoreComment

CommentDefinition getAssignmentScoreComment(String gradebookUid,
                                            Long gbItemId,
                                            String studentUid)
                                            throws GradebookNotFoundException,
                                                   AssessmentNotFoundException

Get the comment (if any) currently provided for the given combination of student and assignment.

Parameters:

gradebookUid -

gbItemId -

studentUid -

Returns:

null if no comment is avaailable

Throws:

GradebookNotFoundException

AssessmentNotFoundException

setAssignmentScore

void setAssignmentScore(String gradebookUid,
                        String assignmentName,
                        String studentUid,
                        Double score,
                        String clientServiceDescription)
                        throws GradebookNotFoundException,
                               AssessmentNotFoundException

Deprecated. Replaced by setAssignmentScoreString(String, String, String, String, String)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

setAssignmentScoreComment

void setAssignmentScoreComment(String gradebookUid,
                               String assignmentName,
                               String studentUid,
                               String comment)
                               throws GradebookNotFoundException,
                                      AssessmentNotFoundException

Provide a student-viewable comment on the score (or lack of score) associated with the given assignment.

Parameters:

gradebookUid -

assignmentName -

studentUid -

comment - a plain text comment, or null to remove any currrent comment

Throws:

GradebookNotFoundException

AssessmentNotFoundException

isAssignmentDefined

boolean isAssignmentDefined(String gradebookUid,
                            String assignmentTitle)
                            throws GradebookNotFoundException

Check to see if an assignment with the given name already exists in the given gradebook. This will give clients a chance to avoid the ConflictingAssignmentNameException.

Throws:

GradebookNotFoundException

getGradebookDefinitionXml

String getGradebookDefinitionXml(String gradebookUid)

Get an archivable definition of gradebook data suitable for migration between sites. Assignment definitions and the currently selected grading scale are included. Student view options and all information related to specific students or instructors (such as scores) are not.

Parameters:

gradebookUid -

Returns:

a versioned XML string

transferGradebookDefinitionXml

void transferGradebookDefinitionXml(String fromGradebookUid,
                                    String toGradebookUid,
                                    String fromGradebookXml)

Attempt to transfer gradebook data with Category and weight and settings

Parameters:

fromGradebookUid -

toGradebookUid -

fromGradebookXml -

mergeGradebookDefinitionXml

void mergeGradebookDefinitionXml(String toGradebookUid,
                                 String fromGradebookXml)

Attempt to merge archived gradebook data (notably the assignnments) into a new gradebook. Assignment definitions whose names match assignments that are already in the targeted gradebook will be skipped. Imported assignments will not automatically be released to students, even if they were released in the original gradebook. Externally managed assessments will not be imported, since such imports should be handled by the external assessment engine. If possible, the targeted gradebook's selected grading scale will be set to match the archived grading scale. If there are any mismatches that make this impossible, the existing grading scale will be left alone, but assignment imports will still happen.

Parameters:

toGradebookUid -

fromGradebookXml -

removeAssignment

void removeAssignment(Long assignmentId)
                      throws StaleObjectModificationException

Removes an assignment from a gradebook. The assignment should not be deleted, but the assignment and all grade records associated with the assignment should be ignored by the application. A removed assignment should not count toward the total number of points in the gradebook.

Parameters:

assignmentId - The assignment id

Throws:

StaleObjectModificationException

getCategories

List getCategories(Long gradebookId)

method to get all categories for a gradebook. This method cannot be used outside of the gradebook because it returns the org.sakaiproject.tool.gradebook.Category object. If you require info on the categories from a consumer outside the gradebook, use getCategoryDefinitions(String)

Parameters:

gradebookId -

Returns:

List of categories

Throws:

HibernateException

getCategoryDefinitions

List<CategoryDefinition> getCategoryDefinitions(String gradebookUid)

Parameters:

gradebookUid -

Returns:

CategoryDefinitions for the categories defined for the given gradebook. Returns an empty list if the gradebook does not have categories.

Throws:

GradebookNotFoundException

removeCategory

void removeCategory(Long categoryId)
                    throws StaleObjectModificationException

remove category from gradebook

Parameters:

categoryId -

Throws:

StaleObjectModificationException

addAssignment

void addAssignment(String gradebookUid,
                   Assignment assignmentDefinition)

Create a new Gradebook-managed assignment.

Parameters:

assignmentDefinition -

updateAssignment

void updateAssignment(String gradebookUid,
                      String assignmentName,
                      Assignment assignmentDefinition)

Modify the definition of an existing Gradebook-managed assignment. Clients should be aware that it's allowed to change the points value of an assignment even if students have already been scored on it. Any existing scores will not be adjusted. This method cannot be used to modify the defintions of externally-managed assessments or to make Gradebook-managed assignments externally managed.

Parameters:

assignmentName - the name of the assignment that needs to be changed

assignmentDefinition - the new properties of the assignment

getViewableAssignmentsForCurrentUser

List<Assignment> getViewableAssignmentsForCurrentUser(String gradebookUid)

Parameters:

gradebookUid -

Returns:

list of gb items that the current user is authorized to view. If user has gradeAll permission, returns all gb items. If user has gradeSection perm with no grader permissions, returns all gb items. If user has gradeSection with grader perms, returns only the items that the current user is authorized to view or grade. If user does not have grading privileges but does have viewOwnGrades perm, will return all released gb items.

getViewableStudentsForItemForCurrentUser

Map<String,String> getViewableStudentsForItemForCurrentUser(String gradebookUid,
                                                            Long gradableObjectId)

Parameters:

gradebookUid -

gradableObjectId -

Returns:

a map of studentId to view/grade function for the given gradebook and gradebook item. students who are not viewable or gradable will not be returned. if the current user does not have grading privileges, an empty map is returned

getViewableStudentsForItemForUser

Map<String,String> getViewableStudentsForItemForUser(String userUid,
                                                     String gradebookUid,
                                                     Long gradableObjectId)

Parameters:

userUid -

gradebookUid -

gradableObjectId -

Returns:

a map of studentId to view/grade function for the given gradebook and gradebook item that the given userUid is allowed to view or grade. students who are not viewable or gradable will not be returned. if the given user does not have grading privileges, an empty map is returned

addGradebook

void addGradebook(String uid,
                  String name)

Deprecated. Replaced by GradebookFrameworkService.addGradebook(String, String)

deleteGradebook

void deleteGradebook(String uid)
                     throws GradebookNotFoundException

Deprecated. Replaced by GradebookFrameworkService.deleteGradebook(String)

Throws:

GradebookNotFoundException

setAvailableGradingScales

void setAvailableGradingScales(Collection gradingScaleDefinitions)

Deprecated. Replaced by GradebookFrameworkService.setAvailableGradingScales(Collection)

setDefaultGradingScale

void setDefaultGradingScale(String uid)

Deprecated. Replaced by GradebookFrameworkService.setDefaultGradingScale(String)

addExternalAssessment

void addExternalAssessment(String gradebookUid,
                           String externalId,
                           String externalUrl,
                           String title,
                           Double points,
                           Date dueDate,
                           String externalServiceDescription,
                           Boolean ungraded)
                           throws GradebookNotFoundException,
                                  ConflictingAssignmentNameException,
                                  ConflictingExternalIdException,
                                  AssignmentHasIllegalPointsException

Deprecated. Replaced by GradebookExternalAssessmentService.addExternalAssessment(String, String, String, String, Double, Date, String, Boolean)

Throws:

GradebookNotFoundException

ConflictingAssignmentNameException

ConflictingExternalIdException

AssignmentHasIllegalPointsException

addExternalAssessment

void addExternalAssessment(String gradebookUid,
                           String externalId,
                           String externalUrl,
                           String title,
                           double points,
                           Date dueDate,
                           String externalServiceDescription)
                           throws GradebookNotFoundException,
                                  ConflictingAssignmentNameException,
                                  ConflictingExternalIdException,
                                  AssignmentHasIllegalPointsException

Deprecated. Replaced by addExternalAssessment(String, String, String, Boolean)

Throws:

GradebookNotFoundException

ConflictingAssignmentNameException

ConflictingExternalIdException

AssignmentHasIllegalPointsException

updateExternalAssessment

void updateExternalAssessment(String gradebookUid,
                              String externalId,
                              String externalUrl,
                              String title,
                              double points,
                              Date dueDate)
                              throws GradebookNotFoundException,
                                     AssessmentNotFoundException,
                                     ConflictingAssignmentNameException,
                                     AssignmentHasIllegalPointsException

Deprecated. Replaced by updateExternalAssessment(String, String, String, String, Double, Date)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

ConflictingAssignmentNameException

AssignmentHasIllegalPointsException

updateExternalAssessment

void updateExternalAssessment(String gradebookUid,
                              String externalId,
                              String externalUrl,
                              String title,
                              Double points,
                              Date dueDate)
                              throws GradebookNotFoundException,
                                     AssessmentNotFoundException,
                                     ConflictingAssignmentNameException,
                                     AssignmentHasIllegalPointsException

Deprecated. Replaced by GradebookExternalAssessmentService.updateExternalAssessment(String, String, String, String, Double, Date, Boolean)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

ConflictingAssignmentNameException

AssignmentHasIllegalPointsException

removeExternalAssessment

void removeExternalAssessment(String gradebookUid,
                              String externalId)
                              throws GradebookNotFoundException,
                                     AssessmentNotFoundException

Deprecated. Replaced by GradebookExternalAssessmentService.removeExternalAssessment(String, String)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

updateExternalAssessmentScore

void updateExternalAssessmentScore(String gradebookUid,
                                   String externalId,
                                   String studentUid,
                                   Double points)
                                   throws GradebookNotFoundException,
                                          AssessmentNotFoundException

Deprecated. Replaced by GradebookExternalAssessmentService#updateExternalAssessmentScore(String, String, String, Double)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

updateExternalAssessmentScores

void updateExternalAssessmentScores(String gradebookUid,
                                    String externalId,
                                    Map studentUidsToScores)
                                    throws GradebookNotFoundException,
                                           AssessmentNotFoundException

Deprecated. Replaced by GradebookExternalAssessmentService.updateExternalAssessmentScoresString(String, String, Map)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

isExternalAssignmentDefined

boolean isExternalAssignmentDefined(String gradebookUid,
                                    String externalId)
                                    throws GradebookNotFoundException

Deprecated. Replaced by GradebookExternalAssessmentService.isExternalAssignmentDefined(String, String)

Throws:

GradebookNotFoundException

getImportCourseGrade

Map getImportCourseGrade(String gradebookUid)

getGradebook

Object getGradebook(String uid)
                    throws GradebookNotFoundException

return Object to avoid circular dependency with sakai-gradebook-tool

Throws:

GradebookNotFoundException

checkStuendsNotSubmitted

boolean checkStuendsNotSubmitted(String gradebookUid)

Parameters:

gradebookUid -

Returns:

checkStudentsNotSubmitted

boolean checkStudentsNotSubmitted(String gradebookUid)

Parameters:

gradebookUid -

Returns:

isGradableObjectDefined

boolean isGradableObjectDefined(Long gradableObjectId)

Parameters:

gradableObjectId -

Returns:

true if a gradable object with the given id exists and was not removed

getViewableSectionUuidToNameMap

Map getViewableSectionUuidToNameMap(String gradebookUid)

Using the grader permissions, return map of section uuid to section name that includes all sections that the current user may view or grade

Parameters:

gradebookUid -

Returns:

currentUserHasGradeAllPerm

boolean currentUserHasGradeAllPerm(String gradebookUid)

Parameters:

gradebookUid -

Returns:

true if current user has the gradebook.gradeAll permission

isUserAllowedToGradeAll

boolean isUserAllowedToGradeAll(String gradebookUid,
                                String userUid)

Parameters:

gradebookUid -

userUid -

Returns:

true if the given user is allowed to grade all students in this gradebook

currentUserHasGradingPerm

boolean currentUserHasGradingPerm(String gradebookUid)

Parameters:

gradebookUid -

Returns:

true if the current user has some form of grading privileges in the gradebook (grade all, grade section, etc)

isUserAllowedToGrade

boolean isUserAllowedToGrade(String gradebookUid,
                             String userUid)

Parameters:

gradebookUid -

userUid -

Returns:

true if the given user has some form of grading privileges in the gradebook (grade all, grade section, etc)

currentUserHasEditPerm

boolean currentUserHasEditPerm(String gradebookUid)

Parameters:

gradebookUid -

Returns:

true if the current user has the gradebook.editAssignments permission

currentUserHasViewOwnGradesPerm

boolean currentUserHasViewOwnGradesPerm(String gradebookUid)

Parameters:

gradebookUid -

Returns:

true if the current user has the gradebook.viewOwnGrades permission

getGradesForStudentsForItem

List<GradeDefinition> getGradesForStudentsForItem(String gradebookUid,
                                                  Long gradableObjectId,
                                                  List<String> studentIds)

Parameters:

gradebookUid -

gradableObjectId -

studentIds -

Returns:

a list of GradeDefinition with the grade information for the given students for the given gradableObjectId

Throws:

SecurityException - if the current user is not authorized to view or grade a student in the passed list

isGradeValid

boolean isGradeValid(String gradebookUuid,
                     String grade)
                     throws GradebookNotFoundException

Parameters:

gradebookUuid -

grade -

Returns:

true if the given grade is a valid grade given the gradebook's grade entry type. ie, if gradebook is set to grade entry by points, will check for valid point value. if entry by letter, will check for valid letter, etc

Throws:

GradebookNotFoundException - if no gradebook exists with given gradebookUid

identifyStudentsWithInvalidGrades

List<String> identifyStudentsWithInvalidGrades(String gradebookUid,
                                               Map<String,String> studentIdToGradeMap)
                                               throws GradebookNotFoundException

Parameters:

gradebookUid -

studentIdToGradeMap - - the student's username mapped to their grade that you want to validate

Returns:

a list of the studentIds that were associated with invalid grades given the gradebook's grade entry type. useful if validating a list of student/grade pairs for a single gradebook (more efficient than calling gradeIsValid repeatedly). returns empty list if all grades are valid

Throws:

GradebookNotFoundException - if no gradebook exists with given gradebookUid

saveGradeAndCommentForStudent

void saveGradeAndCommentForStudent(String gradebookUid,
                                   Long gradableObjectId,
                                   String studentId,
                                   String grade,
                                   String comment)
                                   throws InvalidGradeException,
                                          GradebookNotFoundException,
                                          AssessmentNotFoundException

Save a student score and comment for a gradebook item. The input score must be valid according to the given gradebook's grade entry type.

Parameters:

gradebookUid -

gradableObjectId -

studentId -

grade - - must be in format according to gradebook's grade entry type

comment -

Throws:

InvalidGradeException - - if grade is invalid. grade and comment will not be saved

GradebookNotFoundException

AssessmentNotFoundException

SecurityException - if current user is not authorized to grade student

saveGradesAndComments

void saveGradesAndComments(String gradebookUid,
                           Long gradableObjectId,
                           List<GradeDefinition> gradeDefList)
                           throws InvalidGradeException,
                                  GradebookNotFoundException,
                                  AssessmentNotFoundException

Given a list of GradeDefinitions for students for a given gradebook and gradable object, will save the associated scores and comments. Scores must be in a format according to the gradebook's grade entry type (ie points, %, letter).

Parameters:

gradebookUid -

gradableObjectId -

gradeDefList -

Throws:

InvalidGradeException - if any of the grades are not valid - none will be saved

SecurityException - if the user does not have access to a student in the list - no grades or comments will be saved for any student

GradebookNotFoundException

AssessmentNotFoundException

getFixedGrade

Map getFixedGrade(String gradebookUid)

Get fixed grades for students by using course grade scale.

Parameters:

gradebookUid -

Returns:

Map of enrollment displayId as key, grade as value

getFixedPoint

Map getFixedPoint(String gradebookUid)

Get fixed earned points for students by using course grade scale.

Parameters:

gradebookUid -

Returns:

Map of enrollment displayId as key, point as value string

getOldPoint

Map getOldPoint(String gradebookUid)

Get old earned points for students by using letter grade scale.

Parameters:

gradebookUid -

Returns:

Map of enrollment displayId as key, point as value string

getGradeEntryType

int getGradeEntryType(String gradebookUid)
                      throws GradebookNotFoundException

Parameters:

gradebookUid -

Returns:

the constant representation of the grade entry type (ie points, %, letter grade)

Throws:

GradebookNotFoundException - if no gradebook exists w/ the given uid

getEnteredCourseGrade

Map getEnteredCourseGrade(String gradebookUid)

Get a Map of overridden CourseGrade for students.

Parameters:

gradebookUid -

Returns:

Map of enrollment displayId as key, point as value string

getCalculatedCourseGrade

Map getCalculatedCourseGrade(String gradebookUid)

Get a Map of auto calculated CourseGrade for students.

Parameters:

gradebookUid -

Returns:

Map of enrollment displayId as key, point as value

getAssignmentScoreString

String getAssignmentScoreString(String gradebookUid,
                                String assignmentName,
                                String studentUid)
                                throws GradebookNotFoundException,
                                       AssessmentNotFoundException

Get student's assignment's score as string.

Parameters:

gradebookUid -

assignmentName -

studentUid -

Returns:

String of score

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getAssignmentScoreString

String getAssignmentScoreString(String gradebookUid,
                                Long gbItemId,
                                String studentUid)
                                throws GradebookNotFoundException,
                                       AssessmentNotFoundException

Get student's assignment's score as string.

Parameters:

gradebookUid -

gbItemId -

studentUid -

Returns:

String of score

Throws:

GradebookNotFoundException

AssessmentNotFoundException

setAssignmentScoreString

void setAssignmentScoreString(String gradebookUid,
                              String assignmentName,
                              String studentUid,
                              String score,
                              String clientServiceDescription)
                              throws GradebookNotFoundException,
                                     AssessmentNotFoundException

set student's score for assignment.

Parameters:

gradebookUid -

assignmentName -

studentUid -

score -

clientServiceDescription -

Throws:

GradebookNotFoundException

AssessmentNotFoundException

finalizeGrades

void finalizeGrades(String gradebookUid)
                    throws GradebookNotFoundException

Finalize the gradebook's course grades by setting all still-unscored assignments to zero scores.

Parameters:

gradebookUid -

Throws:

GradebookNotFoundException

getLowestPossibleGradeForGbItem

String getLowestPossibleGradeForGbItem(String gradebookUid,
                                       Long gradebookItemId)

Parameters:

gradebookUid -

gradebookItemId -

Returns:

the lowest possible grade allowed for the given gradebookItemId. For example, in a points or %-based gradebook, the lowest possible grade for a gradebook item is 0. In a letter-grade gb, it may be 'F' depending on the letter grade mapping. Ungraded items have a lowest value of null.

Throws:

SecurityException - if user does not have permission to view assignments in the given gradebook

AssessmentNotFoundException - if there is no gradebook item with the given gradebookItemId

isPointsPossibleValid

GradebookService.PointsPossibleValidation isPointsPossibleValid(String gradebookUid,
                                                                Assignment gradebookItem,
                                                                Double pointsPossible)

Parameters:

gradebookUid - (non-null)

gradebookItem - (non-null) the Assignment object representing the gradebook item for which you are setting the points possible (aka relative weight). May be a new gradebook item without an id yet.

pointsPossible - the points possible/relative weight you would like to validate for the gradebookItem above.

Returns:

GradebookService.PointsPossibleValidation value indicating the validity of the given points possible/relative weight or a problem code defining why it is invalid