org.osid.provisioning

Interface ProvisionableAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

ProvisionableBatchAdminSession

public interface ProvisionableAdminSession
extends OsidSession

This session creates, updates, and deletes Provisionables. 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 getProvisionableFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned ProvisionableForm 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 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.

For updates, ProvisionableForms are requested to the Provisionable Id that is to be updated using getProvisionableFormForUpdate(). 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.

The delete operations delete Provisionables. 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.

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
void	aliasProvisionable(Id provisionableId, Id aliasId) Adds an Id to a Provisionable for the purpose of creating compatibility.
boolean	canCreateProvisionables() Tests if this user can create provisionables.
boolean	canCreateProvisionableWithRecordTypes(Type[] provisionableRecordTypes) Tests if this user can create a single Provisionable using the desired record types.
boolean	canDeleteProvisionables() Tests if this user can delete provisionables.
boolean	canManageProvisionableAliases() Tests if this user can manage Id aliases for Provisionables.
boolean	canUpdateProvisionables() Tests if this user can update provisionables.
Provisionable	createProvisionable(ProvisionableForm provisionableForm) Creates a new Provisionable.
void	deleteProvisionable(Id provisionableId) Deletes a Provisionable.
Distributor	getDistributor() Gets the Distributor associated with this session.
Id	getDistributorId() Gets the Distributor Id associated with this session.
ProvisionableForm	getProvisionableFormForCreate(Id resourceId, Id poolId, Type[] provisionableRecordTypes) Gets the provisionable form for creating new provisionables.
ProvisionableForm	getProvisionableFormForUpdate(Id provisionableId) Gets the provisionable form for updating an existing provisionable.
void	updateProvisionable(ProvisionableForm provisionableForm) Updates an existing provisionable.

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

getDistributorId

Id getDistributorId()

Gets the Distributor Id associated with this session.

Returns:

the Distributor Id associated with this session

Compliance:

mandatory - This method must be implemented.

getDistributor

Distributor getDistributor()
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets the Distributor associated with this session.

Returns:

the distributor

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateProvisionables

boolean canCreateProvisionables()

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

Returns:

false if Provisionable creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateProvisionableWithRecordTypes

boolean canCreateProvisionableWithRecordTypes(Type[] provisionableRecordTypes)

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

Parameters:

provisionableRecordTypes - array of provisionable record types

Returns:

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

Throws:

NullArgumentException - provisionableRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getProvisionableFormForCreate

ProvisionableForm getProvisionableFormForCreate(Id resourceId,
                                              Id poolId,
                                              Type[] provisionableRecordTypes)
                                                throws NotFoundException,
                                                       OperationFailedException,
                                                       PermissionDeniedException

Gets the provisionable form for creating new provisionables. A new form should be requested for each create transaction.

Parameters:

resourceId - the Id for the resource

poolId - the Id for the pool

provisionableRecordTypes - array of provisionable record types

Returns:

the provisionable form

Throws:

NotFoundException - resourceId or poolId is not found

NullArgumentException - resourceId, or poolId, or provisionableRecordTypes 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.

createProvisionable

Provisionable createProvisionable(ProvisionableForm provisionableForm)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Creates a new Provisionable.

Parameters:

provisionableForm - the form for this Provisionable

Returns:

the new Provisionable

Throws:

IllegalStateException - provisionableForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - provisionableForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - provisionableForm did not originate from getProvisionableFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateProvisionables

boolean canUpdateProvisionables()

Tests if this user can update provisionables. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Provisionable 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 Provisionable modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getProvisionableFormForUpdate

ProvisionableForm getProvisionableFormForUpdate(Id provisionableId)
                                                throws NotFoundException,
                                                       OperationFailedException,
                                                       PermissionDeniedException

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

Parameters:

provisionableId - the Id of the Provisionable

Returns:

the provisionable form

Throws:

NotFoundException - provisionableId is not found

NullArgumentException - provisionableId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateProvisionable

void updateProvisionable(ProvisionableForm provisionableForm)
                         throws OperationFailedException,
                                PermissionDeniedException

Updates an existing provisionable.

Parameters:

provisionableForm - the form containing the elements to be updated

Throws:

IllegalStateException - provisionableForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - provisionableForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - provisionableForm did not originate from getProvisionableFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteProvisionables

boolean canDeleteProvisionables()

Tests if this user can delete provisionables. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Provisionable 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 Provisionable deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteProvisionable

void deleteProvisionable(Id provisionableId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Deletes a Provisionable.

Parameters:

provisionableId - the Id of the Provisionable to remove

Throws:

NotFoundException - provisionableId not found

NullArgumentException - provisionableId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageProvisionableAliases

boolean canManageProvisionableAliases()

Tests if this user can manage Id aliases for Provisionables. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:

false if Provisionable aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasProvisionable

void aliasProvisionable(Id provisionableId,
                      Id aliasId)
                        throws AlreadyExistsException,
                               NotFoundException,
                               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 performs as an alias to the primary Id . If the alias is a pointer to another provisionable, it is reassigned to the given provisionable Id.

Parameters:

provisionableId - the Id of a Provisionable

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - provisionableId not found

NullArgumentException - provisionableId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.