Interface AgentLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
public interface AgentLookupSession extends OsidSession

This session provides methods for retrieving Agent objects. The Agent represents the authenticated entity. Agents generally map to resources although this isn't always the case.

This session defines two sets of views which offer differing behaviors when retrieving multiple objects.

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete and ordered result set or is an error condition
  • isolated agency view: All agent methods in this session operate, retrieve and pertain to agents defined explicitly in the current agency. Using an isolated view is useful for managing agents with the AgentAdminSession.
  • federated agency view: All agent methods in this session operate, retrieve and pertain to all agents defined in this agency and any other agents implicitly available in this agency through agency inheritence.

Generally, the comparative view should be used for most applications as it permits operation even if there a particular element is inaccessible. For example, a hierarchy output can be plugged into a lookup method to retrieve all objects known to a hierarchy, but it may not be necessary to break execution if a node from the hierarchy no longer exists. However, some administrative applications may need to know whether it had retrieved an entire set of objects and may sacrifice some interoperability for the sake of precision.

Agents may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the Agent .

  • Method Details

    • 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.

    • canLookupAgents

      boolean canLookupAgents()
      Tests if this user can perform Agent lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all 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.
      Returns:
      false if lookup methods are not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • useComparativeAgentView

      void useComparativeAgentView()
      The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.
      Compliance:
      mandatory - This method is must be implemented.

    • usePlenaryAgentView

      void usePlenaryAgentView()
      A complete view of the Agent returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.
      Compliance:
      mandatory - This method is must be implemented.

    • useFederatedAgencyView

      void useFederatedAgencyView()
      Federates the view for methods in this session. A federated view will include agents in agencies which are children of this agency in the agency hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedAgencyView

      void useIsolatedAgencyView()
      Isolates the view for methods in this session. An isolated view restricts lookups to this agency only.
      Compliance:
      mandatory - This method is must be implemented.

    • getAgent

      Agent getAgent(Id agentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the Agent specified by its Id . In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Agent may have a different Id than requested, such as the case where a duplicate Id was assigned to an Agent and retained for compatibility.
      Parameters:
      agentId - the Id of an Agent
      Returns:
      the returned Agent
      Throws:
      NotFoundException - no Agent found with the given Id
      NullArgumentException - agentId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgentsByIds

      AgentList getAgentsByIds(IdList agentIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets an AgentList corresponding to the given IdList . In plenary mode, the returned list contains all of the agents specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Agents may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      agentIds - a list of agent Ids
      Returns:
      the returned Agent list
      Throws:
      NotFoundException - an Id was not found
      NullArgumentException - agentIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgentsByGenusType

      AgentList getAgentsByGenusType(Type agentGenusType) throws OperationFailedException, PermissionDeniedException
      Gets an AgentList corresponding to the given agent genus Type which does not include agents of genus types derived from the specified Type . In plenary mode, the returned list contains all known agents or an error results. Otherwise, the returned list may contain only those agents that are accessible through this session.
      Parameters:
      agentGenusType - an agent genus type
      Returns:
      the returned Agent list
      Throws:
      NullArgumentException - agentGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgentsByParentGenusType

      AgentList getAgentsByParentGenusType(Type agentGenusType) throws OperationFailedException, PermissionDeniedException
      Gets an AgentList corresponding to the given agent genus Type and include any additional agents with genus types derived from the specified Type . In plenary mode, the returned list contains all known agents or an error results. Otherwise, the returned list may contain only those agents that are accessible through this session.
      Parameters:
      agentGenusType - an agent genus type
      Returns:
      the returned Agent list
      Throws:
      NullArgumentException - agentGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgentsByRecordType

      AgentList getAgentsByRecordType(Type agentRecordType) throws OperationFailedException, PermissionDeniedException
      Gets an AgentList containing the given agent record Type . In plenary mode, the returned list contains all known agents or an error results. Otherwise, the returned list may contain only those agents that are accessible through this session.
      Parameters:
      agentRecordType - an agent record type
      Returns:
      the returned Agent list
      Throws:
      NullArgumentException - agentRecordType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgents

      AgentList getAgents() throws OperationFailedException, PermissionDeniedException
      Gets all Agents . In plenary mode, the returned list contains all known agents or an error results. Otherwise, the returned list may contain only those agents that are accessible through this session.
      Returns:
      a list of Agents
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.