org.osid.authentication

Interface AgentAgencyAssignmentSession

All Superinterfaces:

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

public interface AgentAgencyAssignmentSession
extends OsidSession

This session provides methods to re-assign Agents to Agencies An Agent may map to multiple Agency objects and removing the last reference to an Agent 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	assignAgentToAgency(Id agentId, Id agencyId) Adds an existing Agent to an Agency.
boolean	canAssignAgents() Tests if this user can alter agent/agency mappings.
boolean	canAssignAgentsToAgency(Id agencyId) Tests if this user can alter agent/agency mappings.
IdList	getAssignableAgencyIds(Id agencyId) Gets a list of agencies including and under the given agency node in which any agent can be assigned.
IdList	getAssignableAgencyIdsForAgent(Id agencyId, Id agentId) Gets a list of agencies including and under the given agency node in which a specific agent can be assigned.
void	reassignAgentToAgency(Id agentId, Id fromAgencyId, Id toAgencyId) Moves an Agent from one Agency to another.
void	unassignAgentFromAgency(Id agentId, Id agencyId) Removes an Agent 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

canAssignAgents

boolean canAssignAgents()

Tests if this user can alter agent/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.

canAssignAgentsToAgency

boolean canAssignAgentsToAgency(Id agencyId)

Tests if this user can alter agent/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 agent 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.

getAssignableAgencyIdsForAgent

IdList getAssignableAgencyIdsForAgent(Id agencyId,
                                    Id agentId)
                                      throws OperationFailedException

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

Parameters:

agencyId - the Id of the Agency

agentId - the Id of the Agent

Returns:

list of assignable bin Ids

Throws:

NullArgumentException - agencyId or agentId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

assignAgentToAgency

void assignAgentToAgency(Id agentId,
                       Id agencyId)
                         throws AlreadyExistsException,
                                NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Adds an existing Agent to an Agency.

Parameters:

agentId - the Id of the Agent

agencyId - the Id of the Agency

Throws:

AlreadyExistsException - agentId is already assigned to agencyId

NotFoundException - agentId or agencyId not found

NullArgumentException - agentId or agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

unassignAgentFromAgency

void unassignAgentFromAgency(Id agentId,
                           Id agencyId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Removes an Agent from an Agency.

Parameters:

agentId - the Id of the Agent

agencyId - the Id of the Agency

Throws:

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

NullArgumentException - agentId or agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

reassignAgentToAgency

void reassignAgentToAgency(Id agentId,
                         Id fromAgencyId,
                         Id toAgencyId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Moves an Agent from one Agency to another. Mappings to other Agencies are unaffected.

Parameters:

agentId - the Id of the Agent

fromAgencyId - the Id of the current Agency

toAgencyId - the Id of the destination Agency

Throws:

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

NullArgumentException - agentId, fromAgencyId, or toAgencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.