Interface FileLookupSession

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

This session defines methods for looking up on files 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.

    • canLookupFiles

      boolean canLookupFiles()
      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.

    • useComparativeFileView

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

    • usePlenaryFileView

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

    • getFile

      File getFile(Id fileId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a specified file or alias to the file.
      Parameters:
      fileId - the Id to the file
      Returns:
      the file
      Throws:
      NotFoundException - fileId is not found
      NullArgumentException - fileId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getFilesByIds

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

    • getFilesByGenusType

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

    • getFilesByParentGenusType

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

    • getFilesByRecordType

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

    • getFiles

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