org.osid.grading

Interface GradebookAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

All Known Subinterfaces:

GradebookBatchAdminSession

public interface GradebookAdminSession
extends OsidSession

This session creates, updates, and deletes Gradebooks. The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create a Gradebook, a GradebookForm is requested using getGradebookFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned GradebookForm will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the GradebookForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each GradebookForm corresponds to an attempted transaction.

For updates, GradebookForms are requested to the Gradebook Id that is to be updated using getGradebookFormForUpdate(). Similarly, the GradebookForm has metadata about the data that can be updated and it can perform validation before submitting the update. The GradebookForm can only be used once for a successful update and cannot be reused.

The delete operations delete Gradebooks.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
void	aliasGradebook(Id gradebookId, Id aliasId) Adds an Id to a Gradebook for the purpose of creating compatibility.
boolean	canCreateGradebooks() Tests if this user can create Gradebooks.
boolean	canCreateGradebookWithRecordTypes(Type[] gradebookRecordTypes) Tests if this user can create a single Gradebook using the desired record types.
boolean	canDeleteGradebooks() Tests if this user can delete gradebooks.
boolean	canManageGradebookAliases() Tests if this user can manage Id aliases for Gradebooks.
boolean	canUpdateGradebooks() Tests if this user can update Gradebooks.
Gradebook	createGradebook(GradebookForm gradebookForm) Creates a new Gradebook.
void	deleteGradebook(Id gradebookId) Deletes a Gradebook.
GradebookForm	getGradebookFormForCreate(Type[] gradebookRecordTypes) Gets the gradebook form for creating new gradebooks.
GradebookForm	getGradebookFormForUpdate(Id gradebookId) Gets the gradebook form for updating an existing gradebook.
void	updateGradebook(GradebookForm gradebookForm) Updates an existing gradebook.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

canCreateGradebooks

boolean canCreateGradebooks()

Tests if this user can create Gradebooks. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Gradebook will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returns:

false if Gradebook creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateGradebookWithRecordTypes

boolean canCreateGradebookWithRecordTypes(Type[] gradebookRecordTypes)

Tests if this user can create a single Gradebook using the desired record types. While GradingManager.getGradebookRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Gradebook. Providing an empty array tests if a Gradebook can be created with no records.

Parameters:

gradebookRecordTypes - array of gradebook record types

Returns:

true if Gradebook creation using the specified Types is supported, false otherwise

Throws:

NullArgumentException - gradebookRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getGradebookFormForCreate

GradebookForm getGradebookFormForCreate(Type[] gradebookRecordTypes)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Gets the gradebook form for creating new gradebooks. A new form should be requested for each create transaction.

Parameters:

gradebookRecordTypes - array of gradebook record types

Returns:

the gradebook form

Throws:

NullArgumentException - gradebookRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createGradebook

Gradebook createGradebook(GradebookForm gradebookForm)
                          throws OperationFailedException,
                                 PermissionDeniedException

Creates a new Gradebook.

Parameters:

gradebookForm - the form for this Gradebook

Returns:

the new Gradebook

Throws:

IllegalStateException - gradebookForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - gradebookForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - gradebookForm did not originate from getGradebookFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateGradebooks

boolean canUpdateGradebooks()

Tests if this user can update Gradebooks. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Gradebook will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returns:

false if Gradebook modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getGradebookFormForUpdate

GradebookForm getGradebookFormForUpdate(Id gradebookId)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets the gradebook form for updating an existing gradebook. A new gradebook form should be requested for each update transaction.

Parameters:

gradebookId - the Id of the Gradebook

Returns:

the gradebook form

Throws:

NotFoundException - gradebookId is not found

NullArgumentException - gradebookId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateGradebook

void updateGradebook(GradebookForm gradebookForm)
                     throws OperationFailedException,
                            PermissionDeniedException

Updates an existing gradebook.

Parameters:

gradebookForm - the form containing the elements to be updated

Throws:

IllegalStateException - gradebookForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - gradebookForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - gradebookForm did not originate from getGradebookFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteGradebooks

boolean canDeleteGradebooks()

Tests if this user can delete gradebooks. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Gradebook will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returns:

false if Gradebook deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteGradebook

void deleteGradebook(Id gradebookId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Deletes a Gradebook.

Parameters:

gradebookId - the Id of the Gradebook to remove

Throws:

NotFoundException - gradebookId not found

NullArgumentException - gradebookId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageGradebookAliases

boolean canManageGradebookAliases()

Tests if this user can manage Id aliases for Gradebooks. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:

false if Gradebook aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasGradebook

void aliasGradebook(Id gradebookId,
                  Id aliasId)
                    throws AlreadyExistsException,
                           NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Adds an Id to a Gradebook for the purpose of creating compatibility. The primary Id of the Gradebook is determined by the provider. The new Id performs as an alias to the primary Id . If the alias is a pointer to another gradebook, it is reassigned to the given gradebook Id.

Parameters:

gradebookId - the Id of a Gradebook

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - gradebookId not found

NullArgumentException - gradebookId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.