Package org.sakaiproject.service.gradebook.shared

Interface GradebookService

  • All Superinterfaces:
    org.sakaiproject.entity.api.EntityProducer
    public interface GradebookService
extends org.sakaiproject.entity.api.EntityProducer
    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.

    • 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 assignmentId,
                                        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 -
        assignmentId -
        studentUid -

      • isUserAbleToViewItemForStudent

        boolean isUserAbleToViewItemForStudent​(String gradebookUid,
                                       Long assignmentId,
                                       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 -
        assignmentId -
        studentUid -
        Returns:

      • getGradeViewFunctionForUserForStudentForItem

        String getGradeViewFunctionForUserForStudentForItem​(String gradebookUid,
                                                    Long assignmentId,
                                                    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 -
        assignmentId -
        studentUid -
        Returns:
        GradebookService.gradePermission, GradebookService.viewPermission, or null if no permission

      • 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. This is not deprecated as we currently need the ability to check for duplciate assignment names in the given gradebook
        Throws:
        GradebookNotFoundException

      • transferGradebook

        Map<String,​String> transferGradebook​(GradebookInformation gradebookInformation,
                                           List<Assignment> assignments,
                                           String toGradebookUid,
                                           String fromContext)
        Transfer the gradebook information and assignments from one gradebook to another
        Parameters:
        gradebookInformation - GradebookInformation to copy
        assignments - list of Assignments to copy
        toGradebookUid - target gradebook uid

      • getGradebookInformation

        GradebookInformation getGradebookInformation​(String gradebookUid)
        Parameters:
        gradebookUid -
        Returns:
        a GradebookInformation object that contains information about this Gradebook that may be useful to consumers outside the Gradebook tool

      • 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

        @Deprecated
List getCategories​(Long gradebookId)
        Deprecated.
        Get the categories for the given 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

      • addAssignment

        Long addAssignment​(String gradebookUid,
                   Assignment assignmentDefinition)
        Create a new Gradebook-managed assignment.
        Parameters:
        assignmentDefinition -
        Returns:
        the id of the newly created assignment

      • updateAssignment

        void updateAssignment​(String gradebookUid,
                      Long assignmentId,
                      Assignment assignmentDefinition)
        Modify the definition of an existing Gradebook item. 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 can be used to manage both internal and external gradebook items, however the title, due date and total points will not be edited for external gradebook items.
        Parameters:
        assignmentId - the id 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.

      • getViewableAssignmentsForCurrentUser

        List<Assignment> getViewableAssignmentsForCurrentUser​(String gradebookUid,
                                                      SortType sortBy)
        Parameters:
        gradebookUid -
        Returns:
        list of gb items that the current user is authorized to view sorted by the provided SortType. 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 assignmentId)
        Parameters:
        gradebookUid -
        assignmentId -
        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 assignmentId)
        Parameters:
        userUid -
        gradebookUid -
        assignmentId -
        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

      • checkStudentsNotSubmitted

        boolean checkStudentsNotSubmitted​(String gradebookUid)
        Check if there are students that have not submitted
        Parameters:
        gradebookUid -
        Returns:

      • isGradableObjectDefined

        boolean isGradableObjectDefined​(Long gradableObjectId)
        Check if a gradeable object with the given id exists
        Parameters:
        gradableObjectId -
        Returns:
        true if a gradable object with the given id exists and was not removed

      • getViewableSectionUuidToNameMap

        Map<String,​String> 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)
        Check if the current user has the gradebook.gradeAll permission
        Parameters:
        gradebookUid -
        Returns:
        true if current user has the gradebook.gradeAll permission

      • isUserAllowedToGradeAll

        boolean isUserAllowedToGradeAll​(String gradebookUid,
                                String userUid)
        Check if the given user is allowed to grade all students in this gradebook
        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

      • currentUserHasViewStudentNumbersPerm

        boolean currentUserHasViewStudentNumbersPerm​(String gradebookUid)
        Parameters:
        gradebookUid -
        Returns:
        true if the current user has the gradebook.viewStudentNumbers permission

      • getGradesForStudentsForItem

        List<GradeDefinition> getGradesForStudentsForItem​(String gradebookUid,
                                                  Long assignmentId,
                                                  List<String> studentIds)
        Get the grade records for the given list of students and the given assignment. This can only be called by an instructor or TA that has access, not student. See getGradeDefinitionForStudentForItem(java.lang.String, java.lang.Long, java.lang.String) for the method call that can be made as a student.
        Parameters:
        gradebookUid -
        assignmentId -
        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

      • getGradesWithoutCommentsForStudentsForItems

        Map<Long,​List<GradeDefinition>> getGradesWithoutCommentsForStudentsForItems​(String gradebookUid,
                                                                                  List<Long> gradableOjbectIds,
                                                                                  List<String> studentIds)
        This method gets grades for multiple gradebook items with emphasis on performance. This is particularly useful for reporting tools
        Parameters:
        gradebookUid -
        gradableObjectIds -
        studentIds -
        Returns:
        a Map of GradableObjectIds to a List of GradeDefinitions containing the grade information for the given students for the given gradableObjectIds. Comments are excluded which can be useful for performance. If a student does not have a grade on a gradableObject, the GradeDefinition will be omitted
        Throws:
        SecurityException - if the current user is not authorized with gradeAll in this gradebook
        IllegalArgumentException - if gradableObjectIds is null/empty, or if gradableObjectIds contains items that are not members of the gradebook with uid = gradebookUid

      • 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

      • isValidNumericGrade

        boolean isValidNumericGrade​(String grade)
        Determines if the given string contains a valid numeric grade.
        Parameters:
        grade - the grade as a string, expected to contain a numeric value
        Returns:
        true if the string contains a valid numeric grade

      • 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

      • 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<String,​String> getEnteredCourseGrade​(String gradebookUid)
        Get a Map of overridden CourseGrade for students.
        Parameters:
        gradebookUid -
        Returns:
        Map of enrollment displayId as key, point as value string

      • getAssignmentScoreStringByNameOrId

        String getAssignmentScoreStringByNameOrId​(String gradebookUid,
                                          String assignmentName,
                                          String studentUid)
                                   throws GradebookNotFoundException,
                                          AssessmentNotFoundException
        Get student's assignment's score as string. This is intended as a migration path from the deprecated #getAssignmentScoreString(String,String) to the new #getAssignmentScoreString(String,Long) This method will attempt to lookup the name as provided then fallback to the ID as a Long (If it is a Long) You should use #getAssignmentScoreString(String,Long) if you always can use the Long instead.
        Parameters:
        gradebookUid -
        assignmentName -
        studentUid -
        Returns:
        String of score
        Throws:
        GradebookNotFoundException
        AssessmentNotFoundException

      • getLowestPossibleGradeForGbItem

        String getLowestPossibleGradeForGbItem​(String gradebookUid,
                                       Long assignmentId)
        Parameters:
        gradebookUid -
        assignmentId -
        Returns:
        the lowest possible grade allowed for the given assignmentId. 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 assignment,
                                                                Double pointsPossible)
        Parameters:
        gradebookUid - (non-null)
        assignment - (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

      • getAverageCourseGrade

        String getAverageCourseGrade​(String gradebookUid)
        Computes the Average Course Grade as a letter.
        Parameters:
        gradebookUid -
        Returns:

      • updateAssignmentOrder

        void updateAssignmentOrder​(String gradebookUid,
                           Long assignmentId,
                           Integer order)
        Update the ordering of an assignment. This can be performed on internal and external assignments.
        Parameters:
        gradebookUid - uid of the gradebook
        assignmentId - id of the assignment in the gradebook
        order - the new order for this assignment. Note it is 0 based index ordering.

      • getGradingEvents

        List getGradingEvents​(String studentId,
                      long assignmentId)
        Gets the grading events for the given student and the given assignment
        Parameters:
        studentId -
        assignmentId -
        Returns:
        List of GradingEvent objects.

      • calculateCategoryScore

        Optional<CategoryScoreData> calculateCategoryScore​(Long gradebookId,
                                                   String studentUuid,
                                                   Long categoryId,
                                                   boolean includeNonReleasedItems,
                                                   int categoryType,
                                                   Boolean equalWeightAssignments)
        Calculate the category score for the given gradebook, student and category, looking up the grades. Safe to call in context of a student.
        Parameters:
        gradebookId - Id of the gradebook
        studentUuid - uuid of the student
        categoryId - id of category
        isInstructor - will determine whether category score includes non-released items
        categoryType - category type of the gradebook
        equalWeightAssignments - whether category is equal-weighting regardless of points
        Returns:
        percentage and dropped items, or empty if no calculations were made

      • calculateCategoryScore

        Optional<CategoryScoreData> calculateCategoryScore​(Object gradebook,
                                                   String studentUuid,
                                                   CategoryDefinition category,
                                                   List<Assignment> categoryAssignments,
                                                   Map<Long,​String> gradeMap,
                                                   boolean includeNonReleasedItems)
        Calculate the category score for the given gradebook, category, assignments in the category and grade map. This doesn't do any additional grade lookups. Safe to call in context of a student.
        Parameters:
        gradebook - the gradebook. As this method is called for every student at once, this is passed in to save additional lookups by id.
        studentUuid - uuid of the student
        category - the category
        categoryAssignments - list of assignments the student can view, and are in the category
        gradeMap - map of assignmentId to grade, to use for the calculations
        includeNonReleasedItems - relevant for student view
        Returns:
        percentage and dropped items, or empty if no calculations were made

      • getCourseGradeForStudent

        CourseGrade getCourseGradeForStudent​(String gradebookUid,
                                     String userUuid)
        Get the course grade for a student
        Parameters:
        gradebookUid -
        userUuid - uuid of the user
        Returns:
        The CourseGrade for the student

      • getCourseGradeForStudents

        Map<String,​CourseGrade> getCourseGradeForStudents​(String gradebookUid,
                                                        List<String> userUuids)
        Get the course grade for a list of students
        Parameters:
        gradebookUid -
        userUuids - uuids of the users
        Returns:
        a Map of CourseGrade for the students. Key is the student uuid.

      • getCourseGradeForStudents

        Map<String,​CourseGrade> getCourseGradeForStudents​(String gradebookUid,
                                                        List<String> userUuids,
                                                        Map<String,​Double> schema)
        Get the course grade for a list of students using the given grading schema
        Parameters:
        gradebookUid -
        userUuids - uuids of the users
        schema - the grading schema (bottom percents) to use in the calculation
        Returns:
        a Map of CourseGrade for the students. Key is the student uuid.

      • getViewableSections

        List getViewableSections​(String gradebookUid)
        Get a list of CourseSections that the current user has access to in the given gradebook. This is a combination of sections and groups and is permission filtered.
        Parameters:
        gradebookUid -
        Returns:
        list of CourseSection objects.

      • updateGradebookSettings

        void updateGradebookSettings​(String gradebookUid,
                             GradebookInformation gbInfo)
        Update the settings for this gradebook
        Parameters:
        gradebookUid -
        gbInfo - GradebookInformation object

      • getGradebookGradeMappings

        Set getGradebookGradeMappings​(Long gradebookId)
        Return the GradeMappings for the given gradebook. The normal getGradebook(siteId) doesn't return the GradeMapping.
        Parameters:
        gradebookId -
        Returns:
        Set of GradeMappings for the gradebook

      • getGradebookGradeMappings

        Set getGradebookGradeMappings​(String gradebookUid)
        Return the GradeMappings for the given gradebook.
        Parameters:
        gradebookUid -
        Returns:
        Set of GradeMappings for the gradebook

      • updateCourseGradeForStudent

        void updateCourseGradeForStudent​(String gradebookUid,
                                 String studentUuid,
                                 String grade,
                                 String gradeScale)
        Allows an instructor to set a course grade override for the given student
        Parameters:
        gradebookUid - uuid of the gradebook
        studentUuid - uuid of the student
        grade - the new course grade

      • updateAssignmentCategorizedOrder

        void updateAssignmentCategorizedOrder​(String gradebookUid,
                                      Long categoryId,
                                      Long assignmentId,
                                      Integer order)
        Updates the categorized order of an assignment
        Parameters:
        gradebookUid - uuid of the gradebook
        categoryId - id of the category
        assignmentId - id of the assignment
        order - new position of the assignment

      • getGradingEvents

        List getGradingEvents​(List<Long> assignmentIds,
                      Date since)
        Return the grade changes made since a given time
        Parameters:
        assignmentIds - list of assignment ids to check
        since - timestamp from which to check for changes
        Returns:
        set of changes made