org.osid.recognition

Interface AwardAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

AwardBatchAdminSession

public interface AwardAdminSession
extends OsidSession

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

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

The delete operations delete Awards. To unmap an Award from the current Academy, the AwardAcademyAssignmentSession should be used. These delete operations attempt to remove the Award itself thus removing it from all known Academy 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	aliasAward(Id awardId, Id aliasId) Adds an Id to an Award for the purpose of creating compatibility.
boolean	canCreateAwards() Tests if this user can create Awards.
boolean	canCreateAwardWithRecordTypes(Type[] awardRecordTypes) Tests if this user can create a single Award using the desired record types.
boolean	canDeleteAwards() Tests if this user can delete Awards A return of true does not guarantee successful authorization.
boolean	canManageAwardAliases() Tests if this user can manage Id aliases for Awards.
boolean	canUpdateAwards() Tests if this user can update Awards.
Award	createAward(AwardForm awardForm) Creates a new Award.
void	deleteAward(Id awardId) Deletes an Award.
Academy	getAcademy() Gets the Academy associated with this session.
Id	getAcademyId() Gets the Academy Id associated with this session.
AwardForm	getAwardFormForCreate(Type[] awardRecordTypes) Gets the award form for creating new awards.
AwardForm	getAwardFormForUpdate(Id awardId) Gets the award form for updating an existing award.
void	updateAward(AwardForm awardForm) Updates an existing award.

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

getAcademyId

Id getAcademyId()

Gets the Academy Id associated with this session.

Returns:

the Academy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getAcademy

Academy getAcademy()
                   throws OperationFailedException,
                          PermissionDeniedException

Gets the Academy associated with this session.

Returns:

the academy

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateAwards

boolean canCreateAwards()

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

Compliance:

mandatory - This method must be implemented.

canCreateAwardWithRecordTypes

boolean canCreateAwardWithRecordTypes(Type[] awardRecordTypes)

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

Parameters:

awardRecordTypes - array of award record types

Returns:

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

Throws:

NullArgumentException - awardRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getAwardFormForCreate

AwardForm getAwardFormForCreate(Type[] awardRecordTypes)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets the award form for creating new awards. A new form should be requested for each create transaction.

Parameters:

awardRecordTypes - array of award record types

Returns:

the award form

Throws:

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

createAward

Award createAward(AwardForm awardForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Creates a new Award.

Parameters:

awardForm - the form for this Award

Returns:

the new Award

Throws:

IllegalStateException - awardForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - awardForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - awardForm did not originate from getAwardFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateAwards

boolean canUpdateAwards()

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

Compliance:

mandatory - This method must be implemented.

getAwardFormForUpdate

AwardForm getAwardFormForUpdate(Id awardId)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

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

Parameters:

awardId - the Id of the Award

Returns:

the award form

Throws:

NotFoundException - awardId is not found

NullArgumentException - awardId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateAward

void updateAward(AwardForm awardForm)
                 throws OperationFailedException,
                        PermissionDeniedException

Updates an existing award.

Parameters:

awardForm - the form containing the elements to be updated

Throws:

IllegalStateException - awardForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - awardForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - awardForm did not originate from getAwardFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteAwards

boolean canDeleteAwards()

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

Compliance:

mandatory - This method must be implemented.

deleteAward

void deleteAward(Id awardId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Deletes an Award.

Parameters:

awardId - the Id of the Award to remove

Throws:

NotFoundException - awardId not found

NullArgumentException - awardId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageAwardAliases

boolean canManageAwardAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasAward

void aliasAward(Id awardId,
              Id aliasId)
                throws AlreadyExistsException,
                       NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

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

Parameters:

awardId - the Id of an Award

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - awardId not found

NullArgumentException - awardId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.