org.osid.provisioning

Interface DistributorAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

DistributorBatchAdminSession

public interface DistributorAdminSession
extends OsidSession

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

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

The delete operations delete Distributors.

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	aliasDistributor(Id distributorId, Id aliasId) Adds an Id to a Distributor for the purpose of creating compatibility.
boolean	canCreateDistributors() Tests if this user can create Distributors.
boolean	canCreateDistributorWithRecordTypes(Type[] distributorRecordTypes) Tests if this user can create a single Distributor using the desired record types.
boolean	canDeleteDistributors() Tests if this user can delete Distributors.
boolean	canManageDistributorAliases() Tests if this user can manage Id aliases for Distributors.
boolean	canUpdateDistributors() Tests if this user can update Distributors.
Distributor	createDistributor(DistributorForm distributorForm) Creates a new Distributor.
void	deleteDistributor(Id distributorId) Deletes a Distributor.
DistributorForm	getDistributorFormForCreate(Type[] distributorRecordTypes) Gets the distributor form for creating new distributors.
DistributorForm	getDistributorFormForUpdate(Id distributorId) Gets the distributor form for updating an existing distributor.
void	updateDistributor(DistributorForm distributorForm) Updates an existing distributor

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

canCreateDistributors

boolean canCreateDistributors()

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

Returns:

false if Distributor creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateDistributorWithRecordTypes

boolean canCreateDistributorWithRecordTypes(Type[] distributorRecordTypes)

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

Parameters:

distributorRecordTypes - array of distributor record types

Returns:

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

Throws:

NullArgumentException - distributorRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getDistributorFormForCreate

DistributorForm getDistributorFormForCreate(Type[] distributorRecordTypes)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Gets the distributor form for creating new distributors. A new form should be requested for each create transaction.

Parameters:

distributorRecordTypes - array of distributor record types

Returns:

the distributor form

Throws:

NullArgumentException - distributorRecordTypes 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.

createDistributor

Distributor createDistributor(DistributorForm distributorForm)
                              throws OperationFailedException,
                                     PermissionDeniedException

Creates a new Distributor.

Parameters:

distributorForm - the form for this Distributor

Returns:

the new Distributor

Throws:

IllegalStateException - distributorForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - distributorForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - distributorForm did not originate from getDistributorFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateDistributors

boolean canUpdateDistributors()

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

Returns:

false if Distributor modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getDistributorFormForUpdate

DistributorForm getDistributorFormForUpdate(Id distributorId)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

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

Parameters:

distributorId - the Id of the Distributor

Returns:

the distributor form

Throws:

NotFoundException - distributorId is not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateDistributor

void updateDistributor(DistributorForm distributorForm)
                       throws OperationFailedException,
                              PermissionDeniedException

Updates an existing distributor

Parameters:

distributorForm - the form containing the elements to be updated

Throws:

IllegalStateException - distributorForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - distributorForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - distributorForm did not originate from getDistributorFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteDistributors

boolean canDeleteDistributors()

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

Returns:

false if Distributor deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteDistributor

void deleteDistributor(Id distributorId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Deletes a Distributor.

Parameters:

distributorId - the Id of the Distributor to remove

Throws:

NotFoundException - distributorId not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageDistributorAliases

boolean canManageDistributorAliases()

Tests if this user can manage Id aliases for Distributors. 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 Distributor aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasDistributor

void aliasDistributor(Id distributorId,
                    Id aliasId)
                      throws AlreadyExistsException,
                             NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Adds an Id to a Distributor for the purpose of creating compatibility. The primary Id of the Distributor is determined by the provider. The new Id performs as an alias to the primary Id.

Parameters:

distributorId - the Id of a Distributor

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - distributorId not found

NullArgumentException - distributorId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.