org.osid.filing

Interface FileLookupSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, 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 Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupFiles() Tests if this user can perform entry lookups.
Directory	getDirectory() Gets the directory associated with this session.
Id	getDirectoryId() Gets the Id of this directory.
File	getFile(Id fileId) Gets a specified file or alias to the file.
FileList	getFiles() Gets the list of files and aliases to files in this directory.
FileList	getFilesByGenusType(Type fileGenusType) Gets a FileList corresponding to the given file genus Type which does not include files of genus types derived from the specified Type.
FileList	getFilesByIds(IdList fileIds) Gets a FileList corresponding to the given IdList.
FileList	getFilesByParentGenusType(Type fileGenusType) Gets a FileList corresponding to the given file genus Type and include any additional files with genus types derived from the specified Type.
FileList	getFilesByRecordType(Type fileRecordType) Gets a FileList corresponding to the given file record Type.
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.
void	useFederatedDirectoryView() Federates the view for methods in this session.
void	useIsolatedDirectoryView() Isolates the view for methods in this session.
void	usePlenaryFileView() A complete view of the file returns is desired.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

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.