org.osid.offering

Interface OfferingAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

OfferingBatchAdminSession

public interface OfferingAdminSession
extends OsidSession

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

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

The delete operations delete Offerings. To unmap an Offering from the current Catalogue, the OfferingCatalogueAssignmentSession should be used. These delete operations attempt to remove the Offering 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	aliasOffering(Id offeringId, Id aliasId) Adds an Id to an Offering for the purpose of creating compatibility.
boolean	canCreateOfferings() Tests if this user can create offerings.
boolean	canCreateOfferingWithRecordTypes(Type[] offeringRecordTypes) Tests if this user can create a single Offering using the desired record types.
boolean	canDeleteOfferings() Tests if this user can delete offerings.
boolean	canManageOfferingAliases() Tests if this user can manage Id aliases for Offerings.
boolean	canUpdateOfferings() Tests if this user can update offerings.
Offering	createOffering(OfferingForm offeringForm) Creates a new Offering.
void	deleteOffering(Id offeringId) Deletes an Offering.
Catalogue	getCatalogue() Gets the Catalogue associated with this session.
Id	getCatalogueId() Gets the Catalogue Id associated with this session.
OfferingForm	getOfferingFormForCreate(Id canonicalUnitId, Id timePeriodId, Type[] offeringRecordTypes) Gets the offering form for creating new offerings.
OfferingForm	getOfferingFormForUpdate(Id offeringId) Gets the offering form for updating an existing offering.
void	updateOffering(OfferingForm offeringForm) Updates an existing offering.

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.

canCreateOfferings

boolean canCreateOfferings()

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

Compliance:

mandatory - This method must be implemented.

canCreateOfferingWithRecordTypes

boolean canCreateOfferingWithRecordTypes(Type[] offeringRecordTypes)

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

Parameters:

offeringRecordTypes - array of offering record types

Returns:

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

Throws:

NullArgumentException - offeringRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getOfferingFormForCreate

OfferingForm getOfferingFormForCreate(Id canonicalUnitId,
                                    Id timePeriodId,
                                    Type[] offeringRecordTypes)
                                      throws NotFoundException,
                                             OperationFailedException,
                                             PermissionDeniedException

Gets the offering form for creating new offerings. A new form should be requested for each create transaction.

Parameters:

canonicalUnitId - the canonical unit Id

timePeriodId - the time period Id

offeringRecordTypes - array of offering record types to be included in the create operation or an empty list if none

Returns:

the offering form

Throws:

NotFoundException - canonicalUnitId or timePeriodId is not found

NullArgumentException - canonicalUnitId, timePeriodId , or offeringRecordTypes 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.

createOffering

Offering createOffering(OfferingForm offeringForm)
                        throws OperationFailedException,
                               PermissionDeniedException

Creates a new Offering.

Parameters:

offeringForm - the form for this Offering

Returns:

the new Offering

Throws:

IllegalStateException - offeringForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - offeringForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - offeringForm did not originate from getOfferingFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateOfferings

boolean canUpdateOfferings()

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

Compliance:

mandatory - This method must be implemented.

getOfferingFormForUpdate

OfferingForm getOfferingFormForUpdate(Id offeringId)
                                      throws NotFoundException,
                                             OperationFailedException,
                                             PermissionDeniedException

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

Parameters:

offeringId - the Id of the Offering

Returns:

the offering form

Throws:

NotFoundException - offeringId is not found

NullArgumentException - offeringId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateOffering

void updateOffering(OfferingForm offeringForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Updates an existing offering.

Parameters:

offeringForm - the form containing the elements to be updated

Throws:

IllegalStateException - offeringForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - offeringForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - offeringForm did not originate from getOfferingFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteOfferings

boolean canDeleteOfferings()

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

Compliance:

mandatory - This method must be implemented.

deleteOffering

void deleteOffering(Id offeringId)
                    throws NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Deletes an Offering.

Parameters:

offeringId - the Id of the Offering to remove

Throws:

NotFoundException - offeringId not found

NullArgumentException - offeringId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageOfferingAliases

boolean canManageOfferingAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasOffering

void aliasOffering(Id offeringId,
                 Id aliasId)
                   throws AlreadyExistsException,
                          NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

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

Parameters:

offeringId - the Id of an Offering

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - offeringId not found

NullArgumentException - offeringId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.