Interface ConferralAdminSession

All Superinterfaces:

AutoCloseable, Closeable, OsidSession, OsidSession

All Known Subinterfaces:

ConferralBatchAdminSession

public interface ConferralAdminSession
extends OsidSession

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

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

The delete operations delete Conferrals . To unmap a Conferral from the current Academy , the ConferralAcademyAssignmentSession should be used. These delete operations attempt to remove the Conferral 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

Modifier and Type	Method	Description
void	aliasConferral(Id conferralId, Id aliasId)	Adds an Id to a Conferral for the purpose of creating compatibility.
boolean	canCreateConferrals()	Tests if this user can create conferrals.
boolean	canCreateConferralWithRecordTypes(Type[] conferralRecordTypes)	Tests if this user can create a single Conferral using the desired record types.
boolean	canDeleteConferrals()	Tests if this user can delete conferrals.
boolean	canManageConferralAliases()	Tests if this user can manage Id aliases for Conferrals A return of true does not guarantee successful authorization.
boolean	canUpdateConferrals()	Tests if this user can update conferrals.
Conferral	createConferral(ConferralForm conferralForm)	Creates a new Conferral .
void	deleteConferral(Id conferralId)	Deletes a Conferral .
Academy	getAcademy()	Gets the Academy associated with this session.
Id	getAcademyId()	Gets the Academy Id associated with this session.
ConferralForm	getConferralFormForCreate(Id awardId, Id resourceId, Type[] conferralRecordTypes)	Gets the conferral form for creating new conferrals.
ConferralForm	getConferralFormForUpdate(Id conferralId)	Gets the conferral form for updating an existing conferral.
void	updateConferral(ConferralForm conferralForm)	Updates an existing conferral.

Methods inherited from interface Closeable

close

Methods inherited from interface OsidSession

close

Modifier and Type	Method	Description
void	close()	Close this session.

Methods inherited from interface OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Modifier and Type	Method	Description
Agent	getAuthenticatedAgent()	Gets the agent authenticated to this session.
Id	getAuthenticatedAgentId()	Gets the Id of the agent authenticated to this session.
BigDecimal	getClockRate()	Gets the rate of the service clock.
Date	getDate()	Gets the service date which may be the current date or the effective date in which this session exists.
Agent	getEffectiveAgent()	Gets the effective agent in use by this session.
Id	getEffectiveAgentId()	Gets the Id of the effective agent in use by this session.
Type	getFormatType()	Gets the DisplayText format Type preference in effect for this session.
Locale	getLocale()	Gets the locale indicating the localization preferences in effect for this session.
boolean	isAuthenticated()	Tests if an agent is authenticated to this session.
Transaction	startTransaction()	Starts a new transaction for this sesson.
boolean	supportsTransactions()	Tests for the availability of transactions.

Method Details

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.

canCreateConferrals

boolean canCreateConferrals()

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

Compliance:

mandatory - This method must be implemented.

canCreateConferralWithRecordTypes

boolean canCreateConferralWithRecordTypes(Type[] conferralRecordTypes)

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

Parameters:

conferralRecordTypes - array of conferral record types

Returns:

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

Throws:

NullArgumentException - conferralRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getConferralFormForCreate

ConferralForm getConferralFormForCreate(Id awardId,
 Id resourceId,
 Type[] conferralRecordTypes)
                                 throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the conferral form for creating new conferrals. A new form should be requested for each create transaction.

Parameters:

awardId - the Id for the award

resourceId - the Id for the recipient

conferralRecordTypes - array of conferral record types

Returns:

the conferral form

Throws:

NotFoundException - awardId or resourceId is not found

NullArgumentException - awardId, resourceId , or conferralRecordTypes 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.

createConferral

Conferral createConferral(ConferralForm conferralForm)
                   throws OperationFailedException,
PermissionDeniedException

Creates a new Conferral .

Parameters:

conferralForm - the form for this Conferral

Returns:

the new Conferral

Throws:

IllegalStateException - conferralForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - conferralForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - conferralForm did not originate from getConferralFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateConferrals

boolean canUpdateConferrals()

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

Compliance:

mandatory - This method must be implemented.

getConferralFormForUpdate

ConferralForm getConferralFormForUpdate(Id conferralId)
                                 throws NotFoundException,
OperationFailedException,
PermissionDeniedException

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

Parameters:

conferralId - the Id of the Conferral

Returns:

the conferral form

Throws:

NotFoundException - conferralId is not found

NullArgumentException - conferralId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateConferral

void updateConferral(ConferralForm conferralForm)
              throws OperationFailedException,
PermissionDeniedException

Updates an existing conferral.

Parameters:

conferralForm - the form containing the elements to be updated

Throws:

IllegalStateException - conferralForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - conferralForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - conferralForm did not originate from getConferralFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteConferrals

boolean canDeleteConferrals()

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

Compliance:

mandatory - This method must be implemented.

deleteConferral

void deleteConferral(Id conferralId)
              throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Deletes a Conferral .

Parameters:

conferralId - the Id of the Conferral to remove

Throws:

NotFoundException - conferralId not found

NullArgumentException - conferralId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageConferralAliases

boolean canManageConferralAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasConferral

void aliasConferral(Id conferralId,
 Id aliasId)
             throws AlreadyExistsException,
NotFoundException,
OperationFailedException,
PermissionDeniedException

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

Parameters:

conferralId - the Id of a Conferral

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - conferralId not found

NullArgumentException - conferralId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.