Interface ResourceAgentSession

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

This session provides methods to retrieve Resource to Agent mappings. An Agent may map to only one Resource while a Resource may map to multiple Agents .

This lookup session defines several views

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete result set or is an error condition

  • Method Details

    • getBinId

      Id getBinId()
      Gets the Bin Id associated with this session.
      Returns:
      the Bin Id associated with this session
      Compliance:
      mandatory - This method must be implemented.

    • getBin

      Bin getBin() throws OperationFailedException, PermissionDeniedException
      Gets the Bin associated with this session.
      Returns:
      the Bin associated with this session
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canLookupResourceAgentMappings

      boolean canLookupResourceAgentMappings()
      Tests if this user can perform lookups of resource/agent mappings. A return of true does not guarantee successful authorization. A return of false indicates that it is known lookup 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 looking up mappings is 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.

    • useFederatedBinView

      void useFederatedBinView()
      Federates the view for methods in this session. A federated view will include resources in bins which are children of this bin in the bin hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedBinView

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

    • useImplicitResourceView

      void useImplicitResourceView()
      Returns the Agents directly mapped to the Resource and any Resource implied by the given Resource through grouping or demographic rules.
      Compliance:
      mandatory - This method is must be implemented.

    • useExplciitResourceView

      void useExplciitResourceView()
      Returns the Agents only directly mapped to the given Resource.
      Compliance:
      mandatory - This method is must be implemented.

    • getResourceIdByAgent

      Id getResourceIdByAgent(Id agentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the Resource Id directly associated with the given agent.
      Parameters:
      agentId - Id of the Agent
      Returns:
      associated resource
      Throws:
      NotFoundException - agentId is not found
      NullArgumentException - agentId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getResourceByAgent

      Resource getResourceByAgent(Id agentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the Resource directly associated with the given agent.
      Parameters:
      agentId - Id of the Agent
      Returns:
      associated resource
      Throws:
      NotFoundException - agentId is not found
      NullArgumentException - agentId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgentIdsByResource

      IdList getAgentIdsByResource(Id resourceId) throws OperationFailedException, PermissionDeniedException
      Gets the list of Agent Ids associated with a Resource . In implicit resource mode, Agents are returns for the given Resource and any Resource implied through grouping or demographic rules. Otherwise, only Agents explicitly mapped to the given Resource are returned.
      Parameters:
      resourceId - Id of a Resource
      Returns:
      list of agent Ids
      Throws:
      NullArgumentException - resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgentsByResource

      AgentList getAgentsByResource(Id resourceId) throws OperationFailedException, PermissionDeniedException
      Gets the list of Agent Ids associated with a Resource . In implicit resource mode, Agents are returns for the given Resource and any Resource implied through grouping or demographic rules. Otherwise, only Agents explicitly mapped to the given Resource are returned.
      Parameters:
      resourceId - Id of a Resource
      Returns:
      list of agents
      Throws:
      NullArgumentException - resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgentIdsByResources

      IdList getAgentIdsByResources(IdList resourceIds) throws OperationFailedException, PermissionDeniedException
      Gets the list of Agent Ids associated with any of the given Resources . In implicit resource mode, Agents are returns for the given Resource and any Resource implied through grouping or demographic rules. Otherwise, only Agents explicitly mapped to the given Resource are returned.
      Parameters:
      resourceIds - Ids of the Resources
      Returns:
      list of agent Ids
      Throws:
      NullArgumentException - resourceIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAgentsByResources

      AgentList getAgentsByResources(IdList resourceIds) throws OperationFailedException, PermissionDeniedException
      Gets the list of Agents associated with any of the given Resources . In implicit resource mode, Agents are returns for the given Resource and any Resource implied through grouping or demographic rules. Otherwise, only Agents explicitly mapped to the given Resource are returned.
      Parameters:
      resourceIds - Ids of the Resources
      Returns:
      list of agents
      Throws:
      NullArgumentException - resourceIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canCheckResourceAgentMappings

      boolean canCheckResourceAgentMappings()
      Tests if this user can perform checks of resource/agent mappings. A return of true does not guarantee successful authorization. A return of false indicates that it is known lookup 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 checking up mappings is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • isAgentForResource

      boolean isAgentForResource(Id agentId, Id resourceId) throws OperationFailedException, PermissionDeniedException
      Tests if the given Agent is associated with the given Resource . In implicit resource mode, the given Resource and any Resource implied through grouping or demographic rules are checked. Otherwise, only the given Resource is checked.
      Parameters:
      agentId - Id of an Agent
      resourceId - Id of a Resource
      Returns:
      true of agentId is associated with the given resourceId , false otherwise
      Throws:
      NullArgumentException - agentId or resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • isAgentForResources

      boolean isAgentForResources(Id agentId, IdList resourceIds) throws OperationFailedException, PermissionDeniedException
      Tests if the given Agent is associated with any of the given Resources . In implicit resource mode, the given Resource and any Resource implied through grouping or demographic rules are checked. Otherwise, only the given Resource is checked.
      Parameters:
      agentId - Id of an Agent
      resourceIds - Ids of the Resources
      Returns:
      true of agentId is associated with any of the given resourceIds , false otherwise
      Throws:
      NullArgumentException - agentId or resourceIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.