Interface KeyLookupSession

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

This session provides methods for retrieving Key objects. The Key is associated with an Agent and identified by the Agent Id.

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 key methods in this session operate, retrieve and pertain to keys defined explicitly in the current agency. Using an isolated view is useful for managing keys with the KeyAdminSession.
  • federated agency view: All key methods in this session operate, retrieve and pertain to all keys 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 is data out of sync. 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.

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

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

    • canLookupKeys

      boolean canLookupKeys()
      Tests if this user can lookup Keys . A return of true does not guarantee successful authorization. A return of false indicates that it is known getting a Key will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt to offer key management functions to unauthorized users.
      Returns:
      false if key management is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • useComparativeKeyView

      void useComparativeKeyView()
      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.

    • usePlenaryKeyView

      void usePlenaryKeyView()
      A complete view of the Key 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 keys 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.

    • getKey

      Key getKey(Id keyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the agent key. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Agent via the Key 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:
      keyId - the Id of the Key
      Returns:
      the key
      Throws:
      NotFoundException - keyId is not found or no key exists
      NullArgumentException - keyId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getKeysByIds

      KeyList getKeysByIds(IdList keyIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a KeyList corresponding to the given agent IdList . In plenary mode, the returned list contains all of the keys for 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 Keys may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      keyIds - the list of Ids to retrieve
      Returns:
      the returned Key list
      Throws:
      NotFoundException - an Id was not found
      NullArgumentException - keyIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getKeysByGenusType

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

    • getKeysByParentGenusType

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

    • getKeysByRecordType

      KeyList getKeysByRecordType(Type keyRecordType) throws OperationFailedException, PermissionDeniedException
      Gets a list of keys corresponding to the given key record Type . The set of keys implementing the given record type is returned. In plenary mode, the returned list contains all known keys or an error results. Otherwise, the returned list may contain only those keys that are accessible through this session.
      Parameters:
      keyRecordType - a key record type
      Returns:
      the returned Key list
      Throws:
      NullArgumentException - keyRecordType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getKeyForAgent

      Key getKeyForAgent(Id agentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the agent key.
      Parameters:
      agentId - the Id of the Agent
      Returns:
      the key
      Throws:
      NotFoundException - agentId is not found or no key exists
      NullArgumentException - agentId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getKeys

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