org.osid.provisioning

Interface ProvisionReturnSession

All Superinterfaces:

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

public interface ProvisionReturnSession
extends OsidSession

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

For updates, ProvisionReturnForms are requested to the ProvisionReturn Id that is to be updated using getProvisionReturnFormForUpdate(). Similarly, the ProvisionReturnForm has metadata about the data that can be updated and it can perform validation before submitting the update. The ProvisionReturnForm can only be used once for a successful update and cannot be reused.

The delete operations delete ProvisionReturns. To unmap a ProvisionReturn from the current Distributor, the RProvisionReturnDistributorAssignmentSession should be used. These delete operations attempt to remove the ProvisionReturn itself thus removing it from all known Distributor catalogs.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canCreateProvisionReturns() Tests if this user can return Provisions.
boolean	canCreateProvisionReturnWithRecordTypes(Type[] provisionReturnRecordTypes) Tests if this user can create a single ProvisionReturn using the desired record types.
boolean	canDeleteProvisionReturns() Tests if this user can delete ProvisionReturns.
boolean	canUpdateProvisionReturns() Tests if this user can update ProvisionReturns.
ProvisionReturn	createProvisionReturn(ProvisionReturnForm provisionReturnForm) Creates a new ProvisionReturn.
void	deleteProvisionReturn(Id provisionReturnId) Deletes a ProvisionReturn.
Broker	getBroker() Gets the Broker associated with this session.
Id	getBrokerId() Gets the Broker Id associated with this session.
ProvisionReturnForm	getProvisionReturnFormForCreate(Id provisionId, Type[] provisionReturnRecordTypes) Gets the provision return form for creating new provisions.
ProvisionReturnForm	getProvisionReturnFormForUpdate(Id provisionReturnId) Gets the provision form for updating an existing provision return.
void	updateProvisionReturn(ProvisionReturnForm provisionReturnForm) Updates an existing provision return.

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

getBrokerId

Id getBrokerId()

Gets the Broker Id associated with this session.

Returns:

the Broker Id associated with this session

Compliance:

mandatory - This method must be implemented.

getBroker

Broker getBroker()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the Broker associated with this session.

Returns:

the broker

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateProvisionReturns

boolean canCreateProvisionReturns()

Tests if this user can return Provisions. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Provision will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer return operations to an unauthorized user.

Returns:

false if Provision return is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateProvisionReturnWithRecordTypes

boolean canCreateProvisionReturnWithRecordTypes(Type[] provisionReturnRecordTypes)

Tests if this user can create a single ProvisionReturn using the desired record types. While ProvisioningManager.getProvisionRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Provision. Providing an empty array tests if a Provision can be created with no records.

Parameters:

provisionReturnRecordTypes - array of provision return record types

Returns:

true if ProvisionReturn creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - provisionReturnRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getProvisionReturnFormForCreate

ProvisionReturnForm getProvisionReturnFormForCreate(Id provisionId,
                                                  Type[] provisionReturnRecordTypes)
                                                    throws NotFoundException,
                                                           OperationFailedException,
                                                           PermissionDeniedException

Gets the provision return form for creating new provisions. A new form should be requested for each return transaction.

Parameters:

provisionId - the Id for the provision

provisionReturnRecordTypes - array of provision return record types

Returns:

the provision return form

Throws:

NotFoundException - provisionId is not found

NullArgumentException - provisionId or provisionReturnRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createProvisionReturn

ProvisionReturn createProvisionReturn(ProvisionReturnForm provisionReturnForm)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Creates a new ProvisionReturn.

Parameters:

provisionReturnForm - the form for this ProvisionReturn

Returns:

the new ProvisionReturn

Throws:

IllegalStateException - provisionForm is already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - provisionReturnForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - provisionReturnForm did not oroginate from getProvisionFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateProvisionReturns

boolean canUpdateProvisionReturns()

Tests if this user can update ProvisionReturns. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a ProvisionReturn will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.

Returns:

false if ProvisionReturn modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getProvisionReturnFormForUpdate

ProvisionReturnForm getProvisionReturnFormForUpdate(Id provisionReturnId)
                                                    throws NotFoundException,
                                                           OperationFailedException

Gets the provision form for updating an existing provision return. A new provision return form should be requested for each update transaction.

Parameters:

provisionReturnId - the Id of the ProvisionReturn

Returns:

the provision return form

Throws:

NotFoundException - provisionReturnId is not found

NullArgumentException - provisionReturnId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

updateProvisionReturn

void updateProvisionReturn(ProvisionReturnForm provisionReturnForm)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Updates an existing provision return.

Parameters:

provisionReturnForm - the form containing the elements to be updated

Throws:

InvalidArgumentException - the form contains an invalid value

NotFoundException - provisionReturnId is not found

NullArgumentException - provisionReturnForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - provisionReturnForm did not originate from getProvisionReturnFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteProvisionReturns

boolean canDeleteProvisionReturns()

Tests if this user can delete ProvisionReturns. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a ProvisionReturn will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.

Returns:

false if Provision deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteProvisionReturn

void deleteProvisionReturn(Id provisionReturnId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Deletes a ProvisionReturn. The delete operation deletes the provision return data but does not undo the returned status of the provision.

Parameters:

provisionReturnId - the Id of the ProvisionReturn to remove

Throws:

NotFoundException - provisionReturnId not found

NullArgumentException - provisionReturnId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.