org.osid.course.batch

Interface TermBatchAdminSession

All Superinterfaces:

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

public interface TermBatchAdminSession
extends TermAdminSession

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

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

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

For updates, TermForms are requested to the Term Id that is to be updated using getTermFormsForUpdate() where the reference Id in the TermForm may be used to link the request. Similarly, the TermForm has metadata about the data that can be updated and it can perform validation before submitting the update. The TermForm can only be used once for a successful update and cannot be reused.

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

The delete operations delete Terms in bulk. To unmap a Term from the current CourseCatalog, the TermCourseCatalogAssignmentSession should be used. These delete operations attempt to remove the Term 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	aliasTerms(AliasRequestList aliasRequests) Adds an Id to a Term for the purpose of creating compatibility.
CreateResponseList	createTerms(TermBatchFormList termForms) Creates a new set of Terms.
DeleteResponseList	deleteAllTerms() Deletes all Terms in this CourseCatalog .
DeleteResponseList	deleteChildTerms(Id termId) Deletes terms under the given term.
DeleteResponseList	deleteTerms(IdList termIds) Deletes terms for the given Ids.
DeleteResponseList	deleteTermsByDate(DateTime date) Deletes terms containing the given date.
TermBatchFormList	getTermFormsForCreate(long number, Type[] termRecordTypes) Gets the term forms for creating a bunch of new terms.
TermBatchFormList	getTermFormsForUpdate(IdList termIds) Gets the term forms for updating an existing set of terms.
UpdateResponseList	updateTerms(TermBatchFormList termForms) Updates existing terms.

Methods inherited from interface org.osid.course.TermAdminSession

aliasTerm, canCreateTerms, canCreateTermWithRecordTypes, canDeleteTerms, canManageTermAliases, canUpdateTerms, createTerm, deleteTerm, getCourseCatalog, getCourseCatalogId, getTermFormForCreate, getTermFormForUpdate, updateTerm

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

getTermFormsForCreate

TermBatchFormList getTermFormsForCreate(long number,
                                      Type[] termRecordTypes)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Gets the term forms for creating a bunch of new terms.

Parameters:

number - the number of forms to retrieve

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

Returns:

the term forms

Throws:

NullArgumentException - termRecordTypes 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.

createTerms

CreateResponseList createTerms(TermBatchFormList termForms)
                               throws OperationFailedException,
                                      PermissionDeniedException

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

Parameters:

termForms - the term forms

Returns:

the create responses

Throws:

NullArgumentException - termForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getTermFormsForUpdate

TermBatchFormList getTermFormsForUpdate(IdList termIds)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

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

Parameters:

termIds - the Ids of the Term

Returns:

the term form

Throws:

NotFoundException - a termId is not found

NullArgumentException - termIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateTerms

UpdateResponseList updateTerms(TermBatchFormList termForms)
                               throws OperationFailedException,
                                      PermissionDeniedException

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

Parameters:

termForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - termForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllTerms

DeleteResponseList deleteAllTerms()
                                  throws OperationFailedException,
                                         PermissionDeniedException

Deletes all Terms in this CourseCatalog .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteTerms

DeleteResponseList deleteTerms(IdList termIds)
                               throws OperationFailedException,
                                      PermissionDeniedException

Deletes terms for the given Ids.

Parameters:

termIds - the Ids of the terms to delete

Returns:

the delete responses

Throws:

NullArgumentException - termIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteChildTerms

DeleteResponseList deleteChildTerms(Id termId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Deletes terms under the given term.

Parameters:

termId - an Id of a term

Returns:

the delete responses

Throws:

NullArgumentException - termId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteTermsByDate

DeleteResponseList deleteTermsByDate(DateTime date)
                                     throws OperationFailedException,
                                            PermissionDeniedException

Deletes terms containing 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.

aliasTerms

AliasResponseList aliasTerms(AliasRequestList aliasRequests)
                             throws OperationFailedException,
                                    PermissionDeniedException

Adds an Id to a Term for the purpose of creating compatibility. The primary Id of the Term is determined by the provider. The new Id is an alias to the primary Id. If the alias is a pointer to another term, it is reassigned to the given term 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.