org.sakaiproject.contentreview.service

Interface ContentReviewService

public interface ContentReviewService

ContentReview Service manages submission to the Content review queue and retrieving reports from the service

Author:

David Jaka, David Horwitz

Method Summary

Modifier and Type	Method and Description
boolean	allowAllContent() Each content review implementation can either accept all files or reject unsupported file formats.
boolean	allowResubmission() Does the service support resubmissions?
boolean	allowSubmissionsOnBehalf() Flag to determine whether the service accepts submissions on behalf of users
void	checkForReports() Check for reports for all submitted items that don't have reports yet
void	createAssignment(String siteId, String taskId, Map extraAsnnOpts) This is a vendor specific method needed for some deep integrations (such as A2) to pre provision assignments on an external content checking system.
Map<String,SortedSet<String>>	getAcceptableExtensionsToMimeTypes() Gets a map of acceptable file extensions for this content-review service to their associated mime types (ie. ".rtf" -> ["text/rtf", "application,rtf"])
Map<String,SortedSet<String>>	getAcceptableFileTypesToExtensions() Gets a map of acceptable file types for this content-review service (as UI presentable names) to their associated file extensions (ie.
List<ContentReviewItem>	getAllContentReviewItems(String siteId, String taskId) This is a complement to getReportList, except that it returns all ContentReviewItems for a site and task, rather than just the ones whose reports have been completed.
Map	getAssignment(String siteId, String taskId) This is a vendor specific method to allow getting information about a particular assignment in an external plagiarism checking system.
ContentReviewItem	getContentReviewItemByContentId(String contentId) This method returns all the information related with a ContentReviewItem encapsulated as a ContentReviewResult Using this method will likely tie you to a particular Content Review implementation.
Date	getDateQueued(String contextId) The date an item was queued
Date	getDateSubmitted(String contextId) The date an item was submitted to the queue
String	getEndUserLicenseAgreementLink(String userId) Returns a hyperlink to a providers EULA, if empty, no EULA will be shown to the user
Instant	getEndUserLicenseAgreementTimestamp() Returns date for most recent EULA.
String	getEndUserLicenseAgreementVersion() Returns version for most recent EULA.
String	getIconCssClassforScore(int score, String contentId) Get a icon URL that for a specific score
String	getLocalizedLastError(ContentReviewItem item) Gets the ContentReviewItem's last error localized for the current user session
String	getLocalizedStatusMessage(String messageCode) Get a status message for a submission in the locale of the current user
String	getLocalizedStatusMessage(String messageCode, Locale locale) Get a status message for a submission in the locale specified
String	getLocalizedStatusMessage(String messageCode, String userRef) Get a status message for a submission in the locale of the specified user
default Integer	getProviderId() Provides a default implementation for uniquely identifying a provider
List<ContentReviewItem>	getReportList(String siteId) Get a list of reports for all tasks in a site
List<ContentReviewItem>	getReportList(String siteId, String taskId) Get a list of reports for a task
String	getReviewError(String contentId) Deprecated. use getLocalizedStatusMessage(String)
String	getReviewReport(String contentId, String assignmentRef, String userId) Get the URL of the report
String	getReviewReportInstructor(String contentId, String assignmentRef, String userId) Get the URL for a report constructed for an Instructor
String	getReviewReportRedirectUrl(String contentId, String assignmentRef, String userId, String contextId, boolean isInstructor) Option for providers to decide whether they want to use redirect logic for the report URLs.
String	getReviewReportStudent(String contentId, String assignmentRef, String userId) Get the URL of a report constructed for a student
int	getReviewScore(String contentId, String taskId, String userId) Retrieve a score for a item
Long	getReviewStatus(String contentId) Get the status of a submission
String	getServiceName() Return the Name of the Service Implementation for Display Purposes
Instant	getUserEULATimestamp(String userId) Returns date for the user's last agreement to the EULA.
String	getUserEULAVersion(String userId) Returns version for the user's last agreement to the EULA.
boolean	isAcceptableContent(ContentResource resource) Is the content resource of a type that can be accepted by the service implementation
boolean	isSiteAcceptable(Site site) Can this site make use of the content review service
void	processQueue() Proccess all pending jobs in the Queue
void	queueContent(String userId, String siteId, String taskId, List<ContentResource> content) Add an item to the Queue for Submission to Turnitin
void	removeFromQueue(String contentId) Remove an item from the review Queue
void	resetUserDetailsLockedItems(String userId) Reset the Items for a specific user that where locked because of incomplete user details
void	syncRosters() Sync roster information with services that depend on membership information.
void	updateUserEULATimestamp(String userId) Sets date for the user's last agreement to the EULA to current date
void	webhookEvent(HttpServletRequest request, int providerId, Optional<String> customParam) Webhook event listener that can be used to get messages sent from the provider to Sakai

Method Detail

getProviderId

default Integer getProviderId()

Provides a default implementation for uniquely identifying a provider

Returns:

Integer

queueContent

void queueContent(String userId,
                  String siteId,
                  String taskId,
                  List<ContentResource> content)
           throws QueueException

Add an item to the Queue for Submission to Turnitin

Parameters:

userId - if nulll current user is used

siteId - is null current site is used

taskId - reference to the task

content - list of content resources to be queued

Throws:

QueueException

getReviewScore

int getReviewScore(String contentId,
                   String taskId,
                   String userId)
            throws QueueException,
                   ReportException,
                   Exception

Retrieve a score for a item

Parameters:

contentId -

taskId -

userId -

Returns:

the originality score

Throws:

QueueException

ReportException

Exception

getReviewReport

String getReviewReport(String contentId,
                       String assignmentRef,
                       String userId)
                throws QueueException,
                       ReportException

Get the URL of the report

Parameters:

contentId -

assignmentRef -

userId -

Returns:

the url

Throws:

QueueException

ReportException - * * @deprecated since Nov 2007, use getReviewReportInstructor(String contentId) or getReviewReportInstructor(String contentId)

getReviewReportStudent

String getReviewReportStudent(String contentId,
                              String assignmentRef,
                              String userId)
                       throws QueueException,
                              ReportException

Get the URL of a report constructed for a student

Parameters:

contentId -

assignmentRef -

userId -

Returns:

Throws:

QueueException

ReportException

getReviewReportInstructor

String getReviewReportInstructor(String contentId,
                                 String assignmentRef,
                                 String userId)
                          throws QueueException,
                                 ReportException

Get the URL for a report constructed for an Instructor

Parameters:

contentId -

assignmentRef -

userId -

Returns:

Throws:

QueueException

ReportException

getReviewStatus

Long getReviewStatus(String contentId)
              throws QueueException

Get the status of a submission

Parameters:

contentId -

Returns:

Throws:

QueueException

getDateQueued

Date getDateQueued(String contextId)
            throws QueueException

The date an item was queued

Parameters:

contextId -

Returns:

Throws:

QueueException

getDateSubmitted

Date getDateSubmitted(String contextId)
               throws QueueException,
                      SubmissionException

The date an item was submitted to the queue

Parameters:

contextId -

Returns:

Throws:

QueueException

SubmissionException

processQueue

void processQueue()

Proccess all pending jobs in the Queue

checkForReports

void checkForReports()

Check for reports for all submitted items that don't have reports yet

syncRosters

void syncRosters()

Sync roster information with services that depend on membership information. For example, Turnitin Sakai API expects the creation of courses, assignments, user accounts, and instructor assignments.

getReportList

List<ContentReviewItem> getReportList(String siteId,
                                      String taskId)
                               throws QueueException,
                                      SubmissionException,
                                      ReportException

Get a list of reports for a task

Parameters:

siteId -

taskId -

Returns:

Throws:

QueueException

SubmissionException

ReportException

getReportList

List<ContentReviewItem> getReportList(String siteId)
                               throws QueueException,
                                      SubmissionException,
                                      ReportException

Get a list of reports for all tasks in a site

Parameters:

siteId -

Returns:

Throws:

QueueException

SubmissionException

ReportException

getAllContentReviewItems

List<ContentReviewItem> getAllContentReviewItems(String siteId,
                                                 String taskId)
                                          throws QueueException,
                                                 SubmissionException,
                                                 ReportException

This is a complement to getReportList, except that it returns all ContentReviewItems for a site and task, rather than just the ones whose reports have been completed. This is the result of running into leaky abstraction problems while working on Assignments 2, namely that we need to make the pretty little color coded bars for an entire class for a given assignment, and if some of them had issues we need to present a fine grained error message (such as, your paper was less than 2 paragraphs, or your paper was the wrong file type). This requires another property method, but rather than add a getErrorCode(String contentId) method it's more efficient to add this so we can get the whole lot in one DB query, rather than lookup the special case failures.

Parameters:

siteId -

taskId -

Returns:

Throws:

QueueException

SubmissionException

ReportException

getServiceName

String getServiceName()

Return the Name of the Service Implementation for Display Purposes

resetUserDetailsLockedItems

void resetUserDetailsLockedItems(String userId)

Reset the Items for a specific user that where locked because of incomplete user details

Parameters:

userId -

allowAllContent

boolean allowAllContent()

Each content review implementation can either accept all files or reject unsupported file formats. VeriCite for instance accepts files of any type; if content is in a format that cannot be checked for originality, it returns a score of 0. However, TurnItIn reports errors when the file format cannot be checked for originality, so we need to block unsupported content.

Returns:

whether all content is accepted by this content review service

isAcceptableContent

boolean isAcceptableContent(ContentResource resource)

Is the content resource of a type that can be accepted by the service implementation

Parameters:

resource -

Returns:

getAcceptableExtensionsToMimeTypes

Map<String,SortedSet<String>> getAcceptableExtensionsToMimeTypes()

Gets a map of acceptable file extensions for this content-review service to their associated mime types (ie. ".rtf" -> ["text/rtf", "application,rtf"])

getAcceptableFileTypesToExtensions

Map<String,SortedSet<String>> getAcceptableFileTypesToExtensions()

Gets a map of acceptable file types for this content-review service (as UI presentable names) to their associated file extensions (ie. "PowerPoint" -> [".ppt", ".pptx", ".pps", ".ppsx"]) NB: This must always be implemented as a LinkedHashMap or equivalent; the order is expected to be preserved

isSiteAcceptable

boolean isSiteAcceptable(Site site)

Can this site make use of the content review service

Parameters:

site -

Returns:

getIconCssClassforScore

String getIconCssClassforScore(int score,
                               String contentId)

Get a icon URL that for a specific score

Parameters:

score -

contentId -

Returns:

allowResubmission

boolean allowResubmission()

Does the service support resubmissions?

Returns:

removeFromQueue

void removeFromQueue(String contentId)

Remove an item from the review Queue

Parameters:

contentId -

getLocalizedStatusMessage

String getLocalizedStatusMessage(String messageCode,
                                 String userRef)

Get a status message for a submission in the locale of the specified user

Parameters:

messageCode -

userRef -

Returns:

getLocalizedStatusMessage

String getLocalizedStatusMessage(String messageCode)

Get a status message for a submission in the locale of the current user

Parameters:

messageCode -

Returns:

getReviewError

String getReviewError(String contentId)

Deprecated. use getLocalizedStatusMessage(String)

Get a error report for a Specific method

Parameters:

contentId -

Returns:

getLocalizedStatusMessage

String getLocalizedStatusMessage(String messageCode,
                                 Locale locale)

Get a status message for a submission in the locale specified

Parameters:

messageCode -

locale -

Returns:

getAssignment

Map getAssignment(String siteId,
                  String taskId)
           throws SubmissionException,
                  TransientSubmissionException

This is a vendor specific method to allow getting information about a particular assignment in an external plagiarism checking system. The method returns a Map of keys and properties since they may differ between implementations. In the Turnitin implementation this provides all the return information that comes over the wire from their Fid4 Fcmd7 function which can be referenced from their API Documentation. This method may be necessary for deeper integrations (A2), but could tie your code to a particular implementation.

Parameters:

siteId -

taskId -

Returns:

Throws:

SubmissionException

TransientSubmissionException

createAssignment

void createAssignment(String siteId,
                      String taskId,
                      Map extraAsnnOpts)
               throws SubmissionException,
                      TransientSubmissionException

This is a vendor specific method needed for some deep integrations (such as A2) to pre provision assignments on an external content checking system. The method takes in a Map which can take varying keys and values depending on implementation. For the Turnitin implementation these keys map to some input parameters for Fid4 Fcmd 2/3. These can be seen in Turnitin's API documentation. Using this method will likely tie you to a particular Content Review implementation.

Parameters:

siteId -

taskId -

extraAsnnOpts -

Throws:

SubmissionException

TransientSubmissionException

getContentReviewItemByContentId

ContentReviewItem getContentReviewItemByContentId(String contentId)

This method returns all the information related with a ContentReviewItem encapsulated as a ContentReviewResult Using this method will likely tie you to a particular Content Review implementation.

Parameters:

contentId -

Returns:

ContentReviewResult

getEndUserLicenseAgreementLink

String getEndUserLicenseAgreementLink(String userId)

Returns a hyperlink to a providers EULA, if empty, no EULA will be shown to the user

Returns:

getEndUserLicenseAgreementTimestamp

Instant getEndUserLicenseAgreementTimestamp()

Returns date for most recent EULA. If null, no date will be checked. If provided, the user must re-accept the EULA if the date has changed.

Returns:

getEndUserLicenseAgreementVersion

String getEndUserLicenseAgreementVersion()

Returns version for most recent EULA. If provided, the user must re-accept the EULA if the version doesn't match.

Returns:

getUserEULATimestamp

Instant getUserEULATimestamp(String userId)

Returns date for the user's last agreement to the EULA. If null, the user has not agreed.

Parameters:

userId -

Returns:

getUserEULAVersion

String getUserEULAVersion(String userId)

Returns version for the user's last agreement to the EULA. If null, the user has not agreed.

Parameters:

userId -

Returns:

updateUserEULATimestamp

void updateUserEULATimestamp(String userId)

Sets date for the user's last agreement to the EULA to current date

Parameters:

userId -

getReviewReportRedirectUrl

String getReviewReportRedirectUrl(String contentId,
                                  String assignmentRef,
                                  String userId,
                                  String contextId,
                                  boolean isInstructor)

Option for providers to decide whether they want to use redirect logic for the report URLs. This means that instead of loading the report URLs for the entire page all at once, Sakai will only request the URL when the user clicks the link.

Parameters:

contentId -

assignmentRef -

userId -

isInstructor -

Returns:

webhookEvent

void webhookEvent(HttpServletRequest request,
                  int providerId,
                  Optional<String> customParam)

Webhook event listener that can be used to get messages sent from the provider to Sakai

Parameters:

request -

customParam -

providerId -

getLocalizedLastError

String getLocalizedLastError(ContentReviewItem item)

Gets the ContentReviewItem's last error localized for the current user session

allowSubmissionsOnBehalf

boolean allowSubmissionsOnBehalf()

Flag to determine whether the service accepts submissions on behalf of users