org.osid.course.syllabus.batch

Interface DocetBatchAdminSession

All Superinterfaces:

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

public interface DocetBatchAdminSession
extends DocetAdminSession

This session creates, updates, and deletes Docets in bulk. 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 an Docet, an DocetForm is requested using getDocetFormsForCreate() specifying the desired module, activity unit, and record Types or none if no record Types are needed. Each of the returned DocetForms 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 an 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.

The DocetForms returned from getDocetFormsForCreate() may be linked to the originating request through the peer Ids of the DocetForm. In the case where there may be duplicates, any DocetForm of the same peer Ids may be used for a create operation.

Once a batch of DocetForms are submitted for create, a CreateResponse is returned for each DocetForm, although the ordering is not defined. Only errors that pertain to the entire create operation are returned from createDocets(), errors specific to an individual DocetForm are indicated in the corresponding CreateResponse. CreateResponses may be linked to the originating DocetForm through the DocetForm Id .

For updates, DocetForms are requested to the Docet Id that is to be updated using getDocetFormsForUpdate() where the reference Id in the DocetForm may be used to link the request. 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.

Once a batch of DocetForms are submitted for update, an UpdateResponse is returned for each DocetForm, although the ordering is not defined. Only errors that pertain to the entire update operation are returned from updateDocets(), errors specific to an individual DocetForm are indicated in the corresponding UpdateResponse. UpdateResponses may be linked to the originating DocetForm through the DocetForm Id.

The delete operations delete Docets in bulk. To unmap an 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. Bulk delete operations return the results in DeleteResponses.

Method Summary

Methods

Modifier and Type	Method and Description
AliasResponseList	aliasDocets(AliasRequestList aliasRequests) Adds an Id to an Docet for the purpose of creating compatibility.
CreateResponseList	createDocets(DocetBatchFormList docetForms) Creates a new set of Docets.
DeleteResponseList	deleteAllDocets() Deletes all Docets in this CourseCatalog .
DeleteResponseList	deleteDocets(IdList docetIds) Deletes docets for the given Ids.
DeleteResponseList	deleteDocetsForActivityUnit(Id activityUnitId) Deletes docets for the given activity unit.
DeleteResponseList	deleteDocetsForModule(Id moduleId) Deletes docets for the given module.
DeleteResponseList	deleteIneffectiveDocetsByDate(DateTime date) Deletes docets expired before the given date.
DocetBatchFormList	getDocetFormsForCreate(DocetPeerList peers, Type[] docetRecordTypes) Gets the docet forms for creating a bunch of new docets.
DocetBatchFormList	getDocetFormsForUpdate(IdList docetIds) Gets the docet forms for updating an existing set of docets.
UpdateResponseList	updateDocets(DocetBatchFormList docetForms) Updates existing docets.

Methods inherited from interface org.osid.course.syllabus.DocetAdminSession

aliasDocet, canCreateDocets, canCreateDocetWithRecordTypes, canDeleteDocets, canManageDocetAliases, canSequenceDocets, canUpdateDocets, createDocet, deleteDocet, getCourseCatalog, getCourseCatalogId, getDocetFormForCreate, getDocetFormForUpdate, moveDocetAhead, moveDocetBehind, orderDocets, updateDocet

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

getDocetFormsForCreate

DocetBatchFormList getDocetFormsForCreate(DocetPeerList peers,
                                        Type[] docetRecordTypes)
                                          throws NotFoundException,
                                                 OperationFailedException,
                                                 PermissionDeniedException

Gets the docet forms for creating a bunch of new docets. A form is returned for each activity and resource pair.

Parameters:

peers - the relationship peers

docetRecordTypes - array of docet record types to be included in each create operation or an empty list if none

Returns:

the docet forms

Throws:

NotFoundException - a moduleId or activityUnitId is not found

NullArgumentException - peers or docetRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to request forms with given record types

Compliance:

mandatory - This method must be implemented.

createDocets

CreateResponseList createDocets(DocetBatchFormList docetForms)
                                throws OperationFailedException,
                                       PermissionDeniedException

Creates a new set of Docets. This method returns an error if the entire operation fails. Otherwise, the status of an individual create operation is indicated in the BatchCreateResponse .

Parameters:

docetForms - the docet forms

Returns:

the create responses

Throws:

NullArgumentException - docetForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetFormsForUpdate

DocetBatchFormList getDocetFormsForUpdate(IdList docetIds)
                                          throws NotFoundException,
                                                 OperationFailedException,
                                                 PermissionDeniedException

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

Parameters:

docetIds - the Ids of the Docet

Returns:

the docet form

Throws:

NotFoundException - an docetId is not found

NullArgumentException - docetIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateDocets

UpdateResponseList updateDocets(DocetBatchFormList docetForms)
                                throws OperationFailedException,
                                       PermissionDeniedException

Updates existing docets. This method returns an error if the entire operation fails. Otherwise, the status of an individual update operation is indicated in the BatchCreateResponse .

Parameters:

docetForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - docetForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllDocets

DeleteResponseList deleteAllDocets()
                                   throws OperationFailedException,
                                          PermissionDeniedException

Deletes all Docets in this CourseCatalog .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteDocets

DeleteResponseList deleteDocets(IdList docetIds)
                                throws OperationFailedException,
                                       PermissionDeniedException

Deletes docets for the given Ids.

Parameters:

docetIds - the Ids of the docets to delete

Returns:

the delete responses

Throws:

NullArgumentException - docetIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteDocetsForModule

DeleteResponseList deleteDocetsForModule(Id moduleId)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Deletes docets for the given module.

Parameters:

moduleId - an Id of a module

Returns:

the delete responses

Throws:

NullArgumentException - moduleId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteDocetsForActivityUnit

DeleteResponseList deleteDocetsForActivityUnit(Id activityUnitId)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

Deletes docets for the given activity unit.

Parameters:

activityUnitId - an Id of a resource

Returns:

the delete responses

Throws:

NullArgumentException - activityUnitId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteIneffectiveDocetsByDate

DeleteResponseList deleteIneffectiveDocetsByDate(DateTime date)
                                                 throws OperationFailedException,
                                                        PermissionDeniedException

Deletes docets expired before the given date.

Parameters:

date - a date

Returns:

the delete responses

Throws:

NullArgumentException - date is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

aliasDocets

AliasResponseList aliasDocets(AliasRequestList aliasRequests)
                              throws 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 is an alias to the primary Id. If the alias is a pointer to another docet, it is reassigned to the given docet Id.

Parameters:

aliasRequests - the alias requests

Returns:

the alias responses

Throws:

NullArgumentException - aliasRequests is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.