OSID - osid.provisioning.ProvisionReturnSession Service Interface Definition

Interface	osid.provisioning.ProvisionReturnSession
Implements	`osid.OsidSession`
Used By	`osid.provisioning.ProvisioningManager`
Used By	`osid.provisioning.ProvisioningProxyManager`
Description	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	getBrokerId
Description	Gets the `Broker` `Id` associated with this session.
Return	`osid.id.Id`		the `Broker Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getBroker
Description	Gets the `Broker` associated with this session.
Return	`osid.provisioning.Broker`		the broker
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canCreateProvisionReturns
Description	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.
Return	`boolean`		`false` if `Provision` return is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateProvisionReturnWithRecordTypes
Description	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	`osid.type.Type[]`	`provisionReturnRecordTypes`	array of provision return record types
Return	`boolean`		`true` if `ProvisionReturn` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`provisionReturnRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getProvisionReturnFormForCreate
Description	Gets the provision return form for creating new provisions. A new form should be requested for each return transaction.
Parameters	`osid.id.Id`	`provisionId`	the `Id` for the provision
Parameters	`osid.type.Type[]`	`provisionReturnRecordTypes`	array of provision return record types
Return	`osid.provisioning.ProvisionReturnForm`		the provision return form
Errors	NOT_FOUND		`provisionId` is not found
	NULL_ARGUMENT		`provisionId` or `provisionReturnRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	createProvisionReturn
Description	Creates a new `ProvisionReturn`.
Parameters	`osid.provisioning.ProvisionReturnForm`	`provisionReturnForm`	the form for this `ProvisionReturn`
Return	`osid.provisioning.ProvisionReturn`		the new `ProvisionReturn`
Errors	ILLEGAL_STATE		`provisionForm` is already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`provisionReturnForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`provisionReturnForm` did not oroginate from `getProvisionFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateProvisionReturns
Description	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.
Return	`boolean`		`false` if `ProvisionReturn` modification is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getProvisionReturnFormForUpdate
Description	Gets the provision form for updating an existing provision return. A new provision return form should be requested for each update transaction.
Parameters	`osid.id.Id`	`provisionReturnId`	the `Id` of the `ProvisionReturn`
Return	`osid.provisioning.ProvisionReturnForm`		the provision return form
Errors	NOT_FOUND		`provisionReturnId` is not found
	NULL_ARGUMENT		`provisionReturnId` is `null`
	OPERATION_FAILED		unable to complete request
Compliance	`mandatory`		This method must be implemented.
Method	updateProvisionReturn
Description	Updates an existing provision return.
Parameters	`osid.provisioning.ProvisionReturnForm`	`provisionReturnForm`	the form containing the elements to be updated
Errors	INVALID_ARGUMENT		the form contains an invalid value
	NOT_FOUND		`provisionReturnId` is not found
	NULL_ARGUMENT		`provisionReturnForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`provisionReturnForm` did not originate from `getProvisionReturnFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteProvisionReturns
Description	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.
Return	`boolean`		`false` if `Provision` deletion is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	deleteProvisionReturn
Description	Deletes a `ProvisionReturn`. The delete operation deletes the provision return data but does not undo the returned status of the provision.
Parameters	`osid.id.Id`	`provisionReturnId`	the `Id` of the `ProvisionReturn` to remove
Errors	NOT_FOUND		`provisionReturnId` not found
	NULL_ARGUMENT		`provisionReturnId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.