org.osid.course.syllabus

Interface DocetAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

DocetBatchAdminSession

public interface DocetAdminSession
extends OsidSession

This session creates, updates, and deletes Docets. 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 Docet, a DocetForm is requested using getDocetFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned DocetForm 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 DocetForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each DocetForm corresponds to an attempted transaction.

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

The delete operations delete Docet. To unmap a Docet from the current CourseCatalog, the DocetCourseCatalogAssignmentSession should be used. These delete operations attempt to remove the Docet itself thus removing it from all known CourseCatalog catalogs.

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	aliasDocet(Id docetId, Id aliasId) Adds an Id to an Docet for the purpose of creating compatibility.
boolean	canCreateDocets() Tests if this user can create Docets.
boolean	canCreateDocetWithRecordTypes(Type[] docetRecordTypes) Tests if this user can create a single Docet using the desired record types.
boolean	canDeleteDocets() Tests if this user can delete Docets A return of true does not guarantee successful authorization.
boolean	canManageDocetAliases() Tests if this user can manage Id aliases for Docets.
boolean	canSequenceDocets() Tests if this user can order Docets.
boolean	canUpdateDocets() Tests if this user can update Docets.
Docet	createDocet(DocetForm docetForm) Creates a new Docet.
void	deleteDocet(Id docetId) Deletes an Docet.
CourseCatalog	getCourseCatalog() Gets the CourseCatalog associated with this session.
Id	getCourseCatalogId() Gets the CourseCatalog Id associated with this session.
DocetForm	getDocetFormForCreate(Id moduleId, Id activityUnitId, Type[] docetRecordTypes) Gets the docet form for creating new docets.
DocetForm	getDocetFormForUpdate(Id docetId) Gets the docet form for updating an existing docet.
void	moveDocetAhead(Id docetId, Id moduleId, Id referenceId) Reorders docets in a module by moving the specified docet in front of a reference docet.
void	moveDocetBehind(Id docetId, Id moduleId, Id referenceId) Reorders docets in a module by moving the specified docet behind a reference docet.
void	orderDocets(Id[] docetIds, Id moduleId) Reorders a set of docets in a module.
void	updateDocet(DocetForm docetForm) Updates an existing docet.

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

getCourseCatalogId

Id getCourseCatalogId()

Gets the CourseCatalog Id associated with this session.

Returns:

the CourseCatalog Id associated with this session

Compliance:

mandatory - This method must be implemented.

getCourseCatalog

CourseCatalog getCourseCatalog()
                               throws OperationFailedException,
                                      PermissionDeniedException

Gets the CourseCatalog associated with this session.

Returns:

the course catalog

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateDocets

boolean canCreateDocets()

Tests if this user can create Docets. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating an Docet 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 Docet creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateDocetWithRecordTypes

boolean canCreateDocetWithRecordTypes(Type[] docetRecordTypes)

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

Parameters:

docetRecordTypes - array of docet record types

Returns:

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

Throws:

NullArgumentException - docetRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getDocetFormForCreate

DocetForm getDocetFormForCreate(Id moduleId,
                              Id activityUnitId,
                              Type[] docetRecordTypes)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

Gets the docet form for creating new docets. A new form should be requested for each create transaction.

Parameters:

moduleId - a module Id

activityUnitId - an activity unit Id

docetRecordTypes - array of docet record types

Returns:

the docet form

Throws:

NotFoundException - moduleId or activityUnitId is not found

NullArgumentException - moduleId, acticvtyUnitId, or docetRecordTypes 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.

createDocet

Docet createDocet(DocetForm docetForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Creates a new Docet.

Parameters:

docetForm - the form for this Docet

Returns:

the new Docet

Throws:

IllegalStateException - docetForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - docetForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - docetForm did not originate from getDocetFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateDocets

boolean canUpdateDocets()

Tests if this user can update Docets. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating an Docet 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 Docet modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getDocetFormForUpdate

DocetForm getDocetFormForUpdate(Id docetId)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

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

Parameters:

docetId - the Id of the Docet

Returns:

the docet form

Throws:

NotFoundException - docetId is not found

NullArgumentException - docetId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateDocet

void updateDocet(DocetForm docetForm)
                 throws OperationFailedException,
                        PermissionDeniedException

Updates an existing docet.

Parameters:

docetForm - the form containing the elements to be updated

Throws:

IllegalStateException - docetForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - docetForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - docetForm did not originate from getDocetFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteDocets

boolean canDeleteDocets()

Tests if this user can delete Docets A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Docet 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 Docet deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteDocet

void deleteDocet(Id docetId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Deletes an Docet.

Parameters:

docetId - the Id of the Docet to remove

Throws:

NotFoundException - docetId not found

NullArgumentException - docetId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageDocetAliases

boolean canManageDocetAliases()

Tests if this user can manage Id aliases for Docets. 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 Docet aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasDocet

void aliasDocet(Id docetId,
              Id aliasId)
                throws AlreadyExistsException,
                       NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

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

Parameters:

docetId - the Id of an Docet

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - docetId not found

NullArgumentException - docetId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canSequenceDocets

boolean canSequenceDocets()

Tests if this user can order Docets. 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 sequencing operations to an unauthorized user.

Returns:

false if Docet ordering is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

moveDocetAhead

void moveDocetAhead(Id docetId,
                  Id moduleId,
                  Id referenceId)
                    throws NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Reorders docets in a module by moving the specified docet in front of a reference docet.

Parameters:

docetId - the Id of a Docet

moduleId - the Id of a Module

referenceId - the reference docet Id

Throws:

NotFoundException - docetId, moduleId, or referenceId not found or, docetId or referenceId not related to moduleId

NullArgumentException - docetId, moduleId, or referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

moveDocetBehind

void moveDocetBehind(Id docetId,
                   Id moduleId,
                   Id referenceId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Reorders docets in a module by moving the specified docet behind a reference docet.

Parameters:

docetId - the Id of a Docet

moduleId - the Id of a Module

referenceId - the reference docet Id

Throws:

NotFoundException - docetId, moduleId, or referenceId not found or, docetId or referenceId not related to moduleId

NullArgumentException - docetId, moduleId or referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

orderDocets

void orderDocets(Id[] docetIds,
               Id moduleId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Reorders a set of docets in a module.

Parameters:

docetIds - the Ids for a set of Docets

moduleId - the Id of a Module

Throws:

NotFoundException - docetId not found or, a docetId not related to moduleId

NullArgumentException - docetIds or moduleId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.