org.osid.provisioning.batch

Interface ProvisionableBatchAdminSession

All Superinterfaces:

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

public interface ProvisionableBatchAdminSession
extends ProvisionableAdminSession

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

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

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

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

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

The delete operations delete Provisionables in bulk. To unmap a Provisionable from the current Distributor, the ProvisionableDistributorAssignmentSession should be used. These delete operations attempt to remove the Provisionable 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	aliasProvisionables(AliasRequestList aliasRequests) Adds an Id to a Provisionable for the purpose of creating compatibility.
CreateResponseList	createProvisionables(ProvisionableBatchFormList provisionableForms) Creates a new set of Provisionables.
DeleteResponseList	deleteAllProvisionables() Deletes all Provisionables in this Distributor .
DeleteResponseList	deleteIneffectiveProvisionablesByDate(DateTime date) Deletes provisionables expired before the given date.
DeleteResponseList	deleteProvisionables(IdList provisionableIds) Deletes provisionables for the given Ids.
DeleteResponseList	deleteProvisionablesForPool(Id poolId) Deletes all provisionables for the given pool.
DeleteResponseList	deleteProvisionablesForResource(Id resourceId) Deletes all provisionables for the given resource.
ProvisionableBatchFormList	getProvisionableFormsForCreate(ProvisionablePeerList peers, Type[] provisionableRecordTypes) Gets the provisionable forms for creating a bunch of new provisionables.
ProvisionableBatchFormList	getProvisionableFormsForUpdate(IdList provisionableIds) Gets the provisionable forms for updating an existing set of provisionables.
UpdateResponseList	updateProvisionables(ProvisionableBatchFormList provisionableForms) Updates existing provisionables.

Methods inherited from interface org.osid.provisioning.ProvisionableAdminSession

aliasProvisionable, canCreateProvisionables, canCreateProvisionableWithRecordTypes, canDeleteProvisionables, canManageProvisionableAliases, canUpdateProvisionables, createProvisionable, deleteProvisionable, getDistributor, getDistributorId, getProvisionableFormForCreate, getProvisionableFormForUpdate, updateProvisionable

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

getProvisionableFormsForCreate

ProvisionableBatchFormList getProvisionableFormsForCreate(ProvisionablePeerList peers,
                                                        Type[] provisionableRecordTypes)
                                                          throws NotFoundException,
                                                                 OperationFailedException,
                                                                 PermissionDeniedException

Gets the provisionable forms for creating a bunch of new provisionables. A ProvisionableForm is returned for each pool and resource pair.

Parameters:

peers - the relationship peers

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

Returns:

the provisionable forms

Throws:

NotFoundException - a resourceId or poolId is not found

NullArgumentException - peers or provisionableRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to request transaction forms with given record types

Compliance:

mandatory - This method must be implemented.

createProvisionables

CreateResponseList createProvisionables(ProvisionableBatchFormList provisionableForms)
                                        throws OperationFailedException,
                                               PermissionDeniedException

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

Parameters:

provisionableForms - the provisionable forms

Returns:

the create responses

Throws:

NullArgumentException - provisionableForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProvisionableFormsForUpdate

ProvisionableBatchFormList getProvisionableFormsForUpdate(IdList provisionableIds)
                                                          throws NotFoundException,
                                                                 OperationFailedException,
                                                                 PermissionDeniedException

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

Parameters:

provisionableIds - the Ids of the Provisionable

Returns:

the provisionable form

Throws:

NotFoundException - a provisionableId is not found

NullArgumentException - provisionableIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateProvisionables

UpdateResponseList updateProvisionables(ProvisionableBatchFormList provisionableForms)
                                        throws OperationFailedException,
                                               PermissionDeniedException

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

Parameters:

provisionableForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - provisionableForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllProvisionables

DeleteResponseList deleteAllProvisionables()
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Deletes all Provisionables in this Distributor .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteProvisionables

DeleteResponseList deleteProvisionables(IdList provisionableIds)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Deletes provisionables for the given Ids.

Parameters:

provisionableIds - the Ids of the provisionables to delete

Returns:

the delete responses

Throws:

NullArgumentException - provisionableIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteProvisionablesForResource

DeleteResponseList deleteProvisionablesForResource(Id resourceId)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

Deletes all provisionables for the given resource.

Parameters:

resourceId - an 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.

deleteProvisionablesForPool

DeleteResponseList deleteProvisionablesForPool(Id poolId)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

Deletes all provisionables for the given pool.

Parameters:

poolId - an Id of a pool

Returns:

the delete responses

Throws:

NullArgumentException - poolId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteIneffectiveProvisionablesByDate

DeleteResponseList deleteIneffectiveProvisionablesByDate(DateTime date)
                                                         throws OperationFailedException,
                                                                PermissionDeniedException

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

aliasProvisionables

AliasResponseList aliasProvisionables(AliasRequestList aliasRequests)
                                      throws OperationFailedException,
                                             PermissionDeniedException

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