org.osid.provisioning.batch

Interface ProvisionBatchAdminSession

All Superinterfaces:

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

public interface ProvisionBatchAdminSession
extends ProvisionAdminSession

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

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

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

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

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

The delete operations delete Provisions in bulk. To unmap a Provision from the current Distributor, the ProvisionDistributorAssignmentSession should be used. These delete operations attempt to remove the Provision itself thus removing it from all known Distributor catalogs. Bulk delete operations return the results in DeleteResponses.

Method Summary

Methods

Modifier and Type	Method and Description
AliasResponseList	aliasProvisions(AliasRequestList aliasRequests) Adds an Id to a Provision for the purpose of creating compatibility.
CreateResponseList	createProvisions(ProvisionBatchFormList provisionForms) Creates a new set of Provisions.
DeleteResponseList	deleteAllProvisions() Deletes all Provisions in this Distributor .
DeleteResponseList	deleteIneffectiveProvisionsByDate(DateTime date) Deletes provisions expired before the given date.
DeleteResponseList	deleteProvisions(IdList provisionIds) Deletes provisions for the given Ids.
DeleteResponseList	deleteProvisionsForBroker(Id brokerId) Deletes provisions for the given broker.
DeleteResponseList	deleteProvisionsForProvisionable(Id provisionableId) Deletes provisions for the given provisionable.
DeleteResponseList	deleteProvisionsForRecipient(Id resourceId) Deletes provisions for the given recipient.
DeleteResponseList	deleteProvisionsForRequest(Id requestId) Deletes provisions for the given request.
ProvisionBatchFormList	getProvisionFormsForCreate(long peers, Type[] provisionRecordTypes) Gets the provision forms for creating a bunch of new provisions.
ProvisionBatchFormList	getProvisionFormsForUpdate(IdList provisionIds) Gets the provision forms for updating an existing set of provisions.
UpdateResponseList	updateProvisions(ProvisionBatchFormList provisionForms) Updates existing provisions.

Methods inherited from interface org.osid.provisioning.ProvisionAdminSession

aliasProvision, canCreateProvisions, canCreateProvisionWithRecordTypes, canDeleteProvisions, canManageProvisionAliases, canUpdateProvisions, createProvision, deleteProvision, getDistributor, getDistributorId, getProvisionFormForCreate, getProvisionFormForUpdate, updateProvision

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

getProvisionFormsForCreate

ProvisionBatchFormList getProvisionFormsForCreate(long peers,
                                                Type[] provisionRecordTypes)
                                                  throws NotFoundException,
                                                         OperationFailedException,
                                                         PermissionDeniedException

Gets the provision forms for creating a bunch of new provisions. A form is returned for each supplied provisionable, request, and broker.

Parameters:

peers - a list of provision peers

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

Returns:

the provision forms

Throws:

NotFoundException - a provisionableId, requestId, or brokerId is not found

NullArgumentException - peers or provisionRecordTypes 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.

createProvisions

CreateResponseList createProvisions(ProvisionBatchFormList provisionForms)
                                    throws OperationFailedException,
                                           PermissionDeniedException

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

Parameters:

provisionForms - the provision forms

Returns:

the create responses

Throws:

NullArgumentException - provisionForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProvisionFormsForUpdate

ProvisionBatchFormList getProvisionFormsForUpdate(IdList provisionIds)
                                                  throws NotFoundException,
                                                         OperationFailedException,
                                                         PermissionDeniedException

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

Parameters:

provisionIds - the Ids of the Provision

Returns:

the provision form

Throws:

NotFoundException - a provisionId is not found

NullArgumentException - provisionIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateProvisions

UpdateResponseList updateProvisions(ProvisionBatchFormList provisionForms)
                                    throws OperationFailedException,
                                           PermissionDeniedException

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

Parameters:

provisionForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - provisionForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllProvisions

DeleteResponseList deleteAllProvisions()
                                       throws OperationFailedException,
                                              PermissionDeniedException

Deletes all Provisions in this Distributor .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteProvisions

DeleteResponseList deleteProvisions(IdList provisionIds)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Deletes provisions for the given Ids.

Parameters:

provisionIds - the Ids of the provisions to delete

Returns:

the delete responses

Throws:

NullArgumentException - provisionIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteProvisionsForBroker

DeleteResponseList deleteProvisionsForBroker(Id brokerId)
                                             throws OperationFailedException,
                                                    PermissionDeniedException

Deletes provisions for the given broker.

Parameters:

brokerId - the Id of a broker

Returns:

the delete responses

Throws:

NullArgumentException - brokerId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteProvisionsForProvisionable

DeleteResponseList deleteProvisionsForProvisionable(Id provisionableId)
                                                    throws OperationFailedException,
                                                           PermissionDeniedException

Deletes provisions for the given provisionable.

Parameters:

provisionableId - the Id of a provisionable

Returns:

the delete responses

Throws:

NullArgumentException - provisionableId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteProvisionsForRecipient

DeleteResponseList deleteProvisionsForRecipient(Id resourceId)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

Deletes provisions for the given recipient.

Parameters:

resourceId - the Id of a resource

Returns:

the delete responses

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteProvisionsForRequest

DeleteResponseList deleteProvisionsForRequest(Id requestId)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Deletes provisions for the given request.

Parameters:

requestId - the Id of a request

Returns:

the delete responses

Throws:

NullArgumentException - requestId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteIneffectiveProvisionsByDate

DeleteResponseList deleteIneffectiveProvisionsByDate(DateTime date)
                                                     throws OperationFailedException,
                                                            PermissionDeniedException

Deletes provisions 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.

aliasProvisions

AliasResponseList aliasProvisions(AliasRequestList aliasRequests)
                                  throws OperationFailedException,
                                         PermissionDeniedException

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