org.osid.recognition.batch

Interface ConvocationBatchAdminSession

All Superinterfaces:

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

public interface ConvocationBatchAdminSession
extends ConvocationAdminSession

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

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

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

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

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

The delete operations delete Convocations in bulk. To unmap a Convocation from the current Academy, the ConvocationAcademyAssignmentSession should be used. These delete operations attempt to remove the Convocation itself thus removing it from all known Academy catalogs. Bulk delete operations return the results in DeleteResponses.

Method Summary

Methods

Modifier and Type	Method and Description
AliasResponseList	aliasConvocations(AliasRequestList aliasRequests) Adds an Id to a Convocation for the purpose of creating compatibility.
CreateResponseList	createConvocations(ConvocationBatchFormList convocationForms) Creates a new set of Convocations.
DeleteResponseList	deleteAllConvocations() Deletes all Convocations in this Academy .
DeleteResponseList	deleteConvocations(IdList convocationIds) Deletes convocations for the given Ids.
ConvocationBatchFormList	getConvocationFormsForCreate(long number, Type[] convocationRecordTypes) Gets the convocation forms for creating a bunch of new convocations.
ConvocationBatchFormList	getConvocationFormsForUpdate(IdList convocationIds) Gets the convocation forms for updating an existing set of convocations.
UpdateResponseList	updateConvocations(ConvocationBatchFormList convocationForms) Updates existing convocations.

Methods inherited from interface org.osid.recognition.ConvocationAdminSession

addAward, aliasConvocation, canCreateConvocations, canCreateConvocationWithRecordTypes, canDeleteConvocations, canManageConvocationAliases, canManageConvocations, canUpdateConvocations, createConvocation, deleteConvocation, getAcademy, getAcademyId, getConvocationFormForCreate, getConvocationFormForUpdate, removeAward, updateConvocation

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

getConvocationFormsForCreate

ConvocationBatchFormList getConvocationFormsForCreate(long number,
                                                    Type[] convocationRecordTypes)
                                                      throws OperationFailedException,
                                                             PermissionDeniedException

Gets the convocation forms for creating a bunch of new convocations.

Parameters:

number - the number of forms to retrieve

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

Returns:

the convocation forms

Throws:

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

createConvocations

CreateResponseList createConvocations(ConvocationBatchFormList convocationForms)
                                      throws OperationFailedException,
                                             PermissionDeniedException

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

Parameters:

convocationForms - the convocation forms

Returns:

the create responses

Throws:

NullArgumentException - convocationForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getConvocationFormsForUpdate

ConvocationBatchFormList getConvocationFormsForUpdate(IdList convocationIds)
                                                      throws NotFoundException,
                                                             OperationFailedException,
                                                             PermissionDeniedException

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

Parameters:

convocationIds - the Ids of the Convocation

Returns:

the convocation form

Throws:

NotFoundException - a convocationId is not found

NullArgumentException - convocationIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateConvocations

UpdateResponseList updateConvocations(ConvocationBatchFormList convocationForms)
                                      throws OperationFailedException,
                                             PermissionDeniedException

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

Parameters:

convocationForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - convocationForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllConvocations

DeleteResponseList deleteAllConvocations()
                                         throws OperationFailedException,
                                                PermissionDeniedException

Deletes all Convocations in this Academy .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteConvocations

DeleteResponseList deleteConvocations(IdList convocationIds)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Deletes convocations for the given Ids.

Parameters:

convocationIds - the Ids of the convocations to delete

Returns:

the delete responses

Throws:

NullArgumentException - convocationIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

aliasConvocations

AliasResponseList aliasConvocations(AliasRequestList aliasRequests)
                                    throws OperationFailedException,
                                           PermissionDeniedException

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