org.osid.authentication.keys

Interface KeyAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

KeyBatchAdminSession

public interface KeyAdminSession
extends OsidSession

This session provides methods to creating, updating and deleting Key objects. Keys are managed separately from the Agent. Each Agent maps to a zero or one Key and every Key maps to one Agent.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canCreateKeys() Tests if this user can create Keys.
boolean	canCreateKeyWithRecordTypes(Type[] keyRecordTypes) Tests if this user can create a single Key using the desired record interface types.
boolean	canDeleteKeys() Tests if this user can delete Keys.
boolean	canUpdateKeys() Tests if this user can update Keys.
Key	createKey(KeyForm keyForm) Creates a new Key.
void	deleteKey(Id keyId) Deletes a Key.
Agency	getAgency() Gets the Agency associated with this session.
Id	getAgencyId() Gets the Agency Id associated with this session.
KeyForm	getKeyFormForCreate(Id agentId, Type[] keyRecordTypes) Gets the key form for creating and updating new keys.
KeyForm	getKeyFormForUpdate(Id keyId) Gets the key form for updating an existing key.
void	updateKey(KeyForm keyForm) Updates a key for an agent.

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

getAgencyId

Id getAgencyId()

Gets the Agency Id associated with this session.

Returns:

the Agency Id associated with this session

Compliance:

mandatory - This method must be implemented.

getAgency

Agency getAgency()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the Agency associated with this session.

Returns:

the Agency associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateKeys

boolean canCreateKeys()

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

Returns:

false if Key creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateKeyWithRecordTypes

boolean canCreateKeyWithRecordTypes(Type[] keyRecordTypes)

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

Parameters:

keyRecordTypes - array of key record types

Returns:

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

Throws:

NullArgumentException - keyRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getKeyFormForCreate

KeyForm getKeyFormForCreate(Id agentId,
                          Type[] keyRecordTypes)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Gets the key form for creating and updating new keys. A new form should be requested for each create transaction.

Parameters:

agentId - the Id of the Agent

keyRecordTypes - array of key record types

Returns:

the key form

Throws:

NotFoundException - agentId is not found

NullArgumentException - agentId or keyRecordTypes 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.

createKey

Key createKey(KeyForm keyForm)
              throws OperationFailedException,
                     PermissionDeniedException

Creates a new Key.

Parameters:

keyForm - the form for this Key

Returns:

keyForm already used in a create transaction

Throws:

IllegalStateException - agent already has a key

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - keyForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - keyForm did not originate from getKeyFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateKeys

boolean canUpdateKeys()

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

Returns:

false if key modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getKeyFormForUpdate

KeyForm getKeyFormForUpdate(Id keyId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Gets the key form for updating an existing key.

Parameters:

keyId - the Id of the Key

Returns:

the key form

Throws:

NotFoundException - keyId is not found

NullArgumentException - keyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateKey

void updateKey(KeyForm keyForm)
               throws OperationFailedException,
                      PermissionDeniedException

Updates a key for an agent.

Parameters:

keyForm - the form containing the elements to be updated

Throws:

IllegalStateException - keyForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - keyForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - keyForm did not originate from getKeyFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteKeys

boolean canDeleteKeys()

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

Returns:

false if Key deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteKey

void deleteKey(Id keyId)
               throws NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

Deletes a Key.

Parameters:

keyId - the Id of the Key

Throws:

NotFoundException - a Key was not found identified by the given Id

NullArgumentException - keyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.