Interface DirectoryLookupSession

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

This session defines methods for looking up directories in the current directory.

This session defines the following views:

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete result set or is an error condition
  • federated directory view: searches include entries in directories of which this directory is an ancestor
  • isolated directory view: lookups are restricted to entries in this directory only

Generally, the comparative view should be used for most applications as it permits operation even if there is data out of sync. 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 using the plenary view.

  • Method Details

    • getDirectoryId

      Id getDirectoryId()
      Gets the Id of this directory.
      Returns:
      the Id of this directory
      Compliance:
      mandatory - This method must be implemented.

    • getDirectory

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

    • canLookupDirectories

      boolean canLookupDirectories()
      Tests if this user can perform entry 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.

    • useComparativeDirectoryView

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

    • usePlenaryDirectoryView

      void usePlenaryDirectoryView()
      A complete view of the directory 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.

    • useFederatedDirectoryView

      void useFederatedDirectoryView()
      Federates the view for methods in this session. A federated view will include entries in directories which are children of this directory.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedDirectoryView

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

    • getDirectory

      Directory getDirectory(Id directoryId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a specified directory. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Directory may have a different Id than requested such as with a link.
      Parameters:
      directoryId - the Id to the directory
      Returns:
      the directory
      Throws:
      NotFoundException - directoryId is not found
      NullArgumentException - directoryId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getDirectoriesByIds

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

    • getDirectoriesByGenusType

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

    • getDirectoriesByParentGenusType

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

    • getDirectoriesByRecordType

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

    • getDirectoriesByProvider

      DirectoryList getDirectoriesByProvider(Id resourceId) throws OperationFailedException, PermissionDeniedException
      Gets a DirectoryList for the given provider. In plenary mode, the returned list contains all known directories or an error results. Otherwise, the returned list may contain only those directories that are accessible through this session.
      Parameters:
      resourceId - a resource Id
      Returns:
      the returned Directory list
      Throws:
      NullArgumentException - resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getDirectories

      DirectoryList getDirectories() throws OperationFailedException, PermissionDeniedException
      Gets the list of directories inthis directory. In a federated view, this method returns all directories in descendant directories. In plenary mode, the returned list contains all known directories or an error results. Otherwise, the returned list may contain only those directories that are accessible through this session.
      Returns:
      the list of directories in this directory
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.