org.osid.acknowledgement.batch

Interface CreditBatchAdminSession

All Superinterfaces:

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

public interface CreditBatchAdminSession
extends CreditAdminSession

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

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

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

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

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

The delete operations delete Credits in bulk. To unmap a Credit from the current Billing, the CreditBillingAssignmentSession should be used. These delete operations attempt to remove the Credit itself thus removing it from all known Billing catalogs. Bulk delete operations return the results in DeleteResponses.

Method Summary

Methods

Modifier and Type	Method and Description
AliasResponseList	aliasCredits(AliasRequestList aliasRequests) Adds an Id to a Credit for the purpose of creating compatibility.
CreateResponseList	createCredits(CreditBatchFormList creditForms) Creates a new set of Credits.
DeleteResponseList	deleteAllCredits() Deletes all Credits in this Billing .
DeleteResponseList	deleteCredits(IdList creditIds) Deletes credits for the given Ids.
DeleteResponseList	deleteCreditsForReference(Id referenceId) Deletes credits for the given reference.
DeleteResponseList	deleteCreditsForResource(Id resourceId) Deletes credits for the given resource.
DeleteResponseList	deleteIneffectiveCreditsByDate(DateTime date) Deletes credits expired before the given date.
CreditBatchFormList	getCreditFormsForCreate(CreditPeerList peers, Type[] creditRecordTypes) Gets the credit forms for creating a bunch of new credits.
CreditBatchFormList	getCreditFormsForUpdate(IdList creditIds) Gets the credit forms for updating an existing set of credits.
UpdateResponseList	updateCredits(CreditBatchFormList creditForms) Updates existing credits.

Methods inherited from interface org.osid.acknowledgement.CreditAdminSession

aliasCredit, canCreateCredits, canCreateCreditWithRecordTypes, canDeleteCredits, canManageCreditAliases, canUpdateCredits, createCredit, deleteCredit, getBilling, getBillingId, getCreditFormForCreate, getCreditFormForUpdate, updateCredit

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

getCreditFormsForCreate

CreditBatchFormList getCreditFormsForCreate(CreditPeerList peers,
                                          Type[] creditRecordTypes)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

Gets the credit forms for creating a bunch of new credits. A form is returned for each work and resource pair.

Parameters:

peers - the relationship peers

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

Returns:

the credit forms

Throws:

NotFoundException - a resourceId is not found

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

createCredits

CreateResponseList createCredits(CreditBatchFormList creditForms)
                                 throws OperationFailedException,
                                        PermissionDeniedException

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

Parameters:

creditForms - the credit forms

Returns:

the create responses

Throws:

NullArgumentException - creditForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCreditFormsForUpdate

CreditBatchFormList getCreditFormsForUpdate(IdList creditIds)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

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

Parameters:

creditIds - the Ids of the Credits

Returns:

the credit forms

Throws:

NotFoundException - a creditId is not found

NullArgumentException - creditIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateCredits

UpdateResponseList updateCredits(CreditBatchFormList creditForms)
                                 throws OperationFailedException,
                                        PermissionDeniedException

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

Parameters:

creditForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - creditForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllCredits

DeleteResponseList deleteAllCredits()
                                    throws OperationFailedException,
                                           PermissionDeniedException

Deletes all Credits in this Billing .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteCredits

DeleteResponseList deleteCredits(IdList creditIds)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Deletes credits for the given Ids.

Parameters:

creditIds - the Ids of the credits to delete

Returns:

the delete responses

Throws:

NullArgumentException - creditIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteCreditsForReference

DeleteResponseList deleteCreditsForReference(Id referenceId)
                                             throws OperationFailedException,
                                                    PermissionDeniedException

Deletes credits for the given reference.

Parameters:

referenceId - the Id of a reference

Returns:

the delete responses

Throws:

NullArgumentException - referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteCreditsForResource

DeleteResponseList deleteCreditsForResource(Id resourceId)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Deletes credits for the given resource.

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.

deleteIneffectiveCreditsByDate

DeleteResponseList deleteIneffectiveCreditsByDate(DateTime date)
                                                  throws OperationFailedException,
                                                         PermissionDeniedException

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

aliasCredits

AliasResponseList aliasCredits(AliasRequestList aliasRequests)
                               throws OperationFailedException,
                                      PermissionDeniedException

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