org.osid.authentication.keys

Interface KeyAgencyAssignmentSession

All Superinterfaces:

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

public interface KeyAgencyAssignmentSession
extends OsidSession

This session provides methods to re-assign Keys to Agencies An Key may map to multiple Agency objects and removing the last reference to an Key is the equivalent of deleting it. Each Agency may have its own authorizations governing who is allowed to operate on it.

Moving or adding a reference of an Ageny to another Agency is not a copy operation (eg: does not change its Id ).

Method Summary

Methods

Modifier and Type	Method and Description
void	assignKeyToAgency(Id keyId, Id agencyId) Adds an existing Key to an Agency.
boolean	canAssignKeys() Tests if this user can alter key/agency mappings.
boolean	canAssignKeysToAgency(Id agencyId) Tests if this user can alter key/agency mappings.
IdList	getAssignableAgencyIds(Id agencyId) Gets a list of agencies including and under the given agency node in which any key can be assigned.
IdList	getAssignableAgencyIdsForKey(Id agencyId, Id keyId) Gets a list of agencies including and under the given agency node in which a specific key can be assigned.
void	reassignKeyToAgency(Id keyId, Id fromAgencyId, Id toAgencyId) Moves a Key from one Agency to another.
void	unassignKeyFromAgency(Id keyId, Id agencyId) Removes an Key from an Agency.

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

canAssignKeys

boolean canAssignKeys()

Tests if this user can alter key/agency mappings. A return of true does not guarantee successful authorization. A return of false indicates that it is known mapping methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer lookup operations to unauthorized users.

Returns:

false if mapping is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canAssignKeysToAgency

boolean canAssignKeysToAgency(Id agencyId)

Tests if this user can alter key/agency mappings. A return of true does not guarantee successful authorization. A return of false indicates that it is known mapping methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer lookup operations to unauthorized users.

Parameters:

agencyId - the Id of the Agency

Returns:

false if mapping is not authorized, true otherwise

Throws:

NullArgumentException - agencyId is null

Compliance:

mandatory - This method must be implemented.

getAssignableAgencyIds

IdList getAssignableAgencyIds(Id agencyId)
                              throws OperationFailedException

Gets a list of agencies including and under the given agency node in which any key can be assigned.

Parameters:

agencyId - the Id of the Agency

Returns:

list of assignable agency Ids

Throws:

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

getAssignableAgencyIdsForKey

IdList getAssignableAgencyIdsForKey(Id agencyId,
                                  Id keyId)
                                    throws OperationFailedException

Gets a list of agencies including and under the given agency node in which a specific key can be assigned.

Parameters:

agencyId - the Id of the Agency

keyId - the Id of the Key

Returns:

list of assignable bin Ids

Throws:

NullArgumentException - agencyId or keyId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

assignKeyToAgency

void assignKeyToAgency(Id keyId,
                     Id agencyId)
                       throws AlreadyExistsException,
                              NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Adds an existing Key to an Agency.

Parameters:

keyId - the Id of the Key

agencyId - the Id of the Agency

Throws:

AlreadyExistsException - keyId is already assigned to agencyId

NotFoundException - keyId or agencyId not found

NullArgumentException - keyId or agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

unassignKeyFromAgency

void unassignKeyFromAgency(Id keyId,
                         Id agencyId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Removes an Key from an Agency.

Parameters:

keyId - the Id of the Key

agencyId - the Id of the Agency

Throws:

NotFoundException - keyId or agencyId not found or keyId not assigned to agencyId

NullArgumentException - keyId or agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

reassignKeyToAgency

void reassignKeyToAgency(Id keyId,
                       Id fromAgencyId,
                       Id toAgencyId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Moves a Key from one Agency to another. Mappings to other Agencies are unaffected.

Parameters:

keyId - the Id of the Key

fromAgencyId - the Id of the current Agency

toAgencyId - the Id of the destination Agency

Throws:

NotFoundException - keyId, fromAgencyId, or toAgencyId not found or keyId not mapped to fromAgencyId

NullArgumentException - keyId, fromAgencyId, or toAgencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.