org.osid.offering

Interface CanonicalUnitAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

CanonicalUnitBatchAdminSession

public interface CanonicalUnitAdminSession
extends OsidSession

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

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

The delete operations delete CanonicalUnits. To unmap a CanonicalUnit from the current Catalogue, the CanonicalUnitCatalogueAssignmentSession should be used. These delete operations attempt to remove the CanonicalUnit itself thus removing it from all known Catalogue 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	aliasCanonicalUnit(Id canonicalUnitId, Id aliasId) Adds an Id to a CanonicalUnit for the purpose of creating compatibility.
boolean	canCreateCanonicalUnits() Tests if this user can create canonical units.
boolean	canCreateCanonicalUnitWithRecordTypes(Type[] canonicalUnitRecordTypes) Tests if this user can create a single CanonicalUnit using the desired record types.
boolean	canDeleteCanonicalUnits() Tests if this user can delete canonical units.
boolean	canManageCanonicalUnitAliases() Tests if this user can manage Id aliases for CanonicalUnits.
boolean	canUpdateCanonicalUnits() Tests if this user can update canonical units.
CanonicalUnit	createCanonicalUnit(CanonicalUnitForm canonicalUnitForm) Creates a new CanonicalUnit.
void	deleteCanonicalUnit(Id canonicalUnitId) Deletes a CanonicalUnit.
CanonicalUnitForm	getCanonicalUnitFormForCreate(Type[] canonicalUnitRecordTypes) Gets the canonical unit form for creating new canonical units.
CanonicalUnitForm	getCanonicalUnitFormForUpdate(Id canonicalUnitId) Gets the canonical unit form for updating an existing canonical unit.
Catalogue	getCatalogue() Gets the Catalogue associated with this session.
Id	getCatalogueId() Gets the Catalogue Id associated with this session.
void	updateCanonicalUnit(CanonicalUnitForm canonicalUnitForm) Updates an existing canonical unit.

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

getCatalogueId

Id getCatalogueId()

Gets the Catalogue Id associated with this session.

Returns:

the Catalogue Id associated with this session

Compliance:

mandatory - This method must be implemented.

getCatalogue

Catalogue getCatalogue()
                       throws OperationFailedException,
                              PermissionDeniedException

Gets the Catalogue associated with this session.

Returns:

the catalogue

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateCanonicalUnits

boolean canCreateCanonicalUnits()

Tests if this user can create canonical units. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a CanonicalUnit 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 CanonicalUnit creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateCanonicalUnitWithRecordTypes

boolean canCreateCanonicalUnitWithRecordTypes(Type[] canonicalUnitRecordTypes)

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

Parameters:

canonicalUnitRecordTypes - array of canonical unit record types

Returns:

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

Throws:

NullArgumentException - canonicalUnitRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getCanonicalUnitFormForCreate

CanonicalUnitForm getCanonicalUnitFormForCreate(Type[] canonicalUnitRecordTypes)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

Gets the canonical unit form for creating new canonical units. A new form should be requested for each create transaction.

Parameters:

canonicalUnitRecordTypes - array of canonical unit record types to be included in the create operation or an empty list if none

Returns:

the canonical unit form

Throws:

NullArgumentException - canonicalUnitRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - cannot get form for requested record types

Compliance:

mandatory - This method must be implemented.

createCanonicalUnit

CanonicalUnit createCanonicalUnit(CanonicalUnitForm canonicalUnitForm)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Creates a new CanonicalUnit.

Parameters:

canonicalUnitForm - the form for this CanonicalUnit

Returns:

the new CanonicalUnit

Throws:

IllegalStateException - canonicalUnitForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - canonicalUnitForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - canonicalUnitForm did not originate from getCanonicalUnitFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateCanonicalUnits

boolean canUpdateCanonicalUnits()

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

Compliance:

mandatory - This method must be implemented.

getCanonicalUnitFormForUpdate

CanonicalUnitForm getCanonicalUnitFormForUpdate(Id canonicalUnitId)
                                                throws NotFoundException,
                                                       OperationFailedException,
                                                       PermissionDeniedException

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

Parameters:

canonicalUnitId - the Id of the CanonicalUnit

Returns:

the canonical unit form

Throws:

NotFoundException - canonicalUnitId is not found

NullArgumentException - canonicalUnitId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateCanonicalUnit

void updateCanonicalUnit(CanonicalUnitForm canonicalUnitForm)
                         throws OperationFailedException,
                                PermissionDeniedException

Updates an existing canonical unit.

Parameters:

canonicalUnitForm - the form containing the elements to be updated

Throws:

IllegalStateException - canonicalUnitForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - canonicalUnitForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - canonicalUnitForm did not originate from getCanonicalUnitFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteCanonicalUnits

boolean canDeleteCanonicalUnits()

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

Compliance:

mandatory - This method must be implemented.

deleteCanonicalUnit

void deleteCanonicalUnit(Id canonicalUnitId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Deletes a CanonicalUnit.

Parameters:

canonicalUnitId - the Id of the CanonicalUnit to remove

Throws:

NotFoundException - canonicalUnitId not found

NullArgumentException - canonicalUnitId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageCanonicalUnitAliases

boolean canManageCanonicalUnitAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasCanonicalUnit

void aliasCanonicalUnit(Id canonicalUnitId,
                      Id aliasId)
                        throws AlreadyExistsException,
                               NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Adds an Id to a CanonicalUnit for the purpose of creating compatibility. The primary Id of the CanonicalUnit is determined by the provider. The new Id is an alias to the primary Id. If the alias is a pointer to another canonical unit, it is reassigned to the given canonical unit Id.

Parameters:

canonicalUnitId - the Id of a CanonicalUnit

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - canonicalUnitId not found

NullArgumentException - canonicalUnitId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.