org.osid.filing

Interface DirectoryLookupSession

All Superinterfaces:

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

Methods

Modifier and Type	Method and Description
boolean	canLookupDirectories() Tests if this user can perform entry lookups.
DirectoryList	getDirectories() Gets the list of directories inthis directory.
DirectoryList	getDirectoriesByGenusType(Type dircetoryGenusType) Gets a DirectoryList corresponding to the given directory genus Type which does not include directories of genus types derived from the specified Type.
DirectoryList	getDirectoriesByIds(IdList directoryIds) Gets a DirectoryList corresponding to the given IdList.
DirectoryList	getDirectoriesByParentGenusType(Type directoryGenusType) Gets a DirectoryList corresponding to the given directory genus Type and include any additional directories with genus types derived from the specified Type.
DirectoryList	getDirectoriesByProvider(Id resourceId) Gets a DirectoryList for the given provider.
DirectoryList	getDirectoriesByRecordType(Type directoryRecordType) Gets a DirectoryList corresponding to the given directory record Type.
Directory	getDirectory() Gets the directory associated with this session.
Directory	getDirectory(Id directoryId) Gets a specified directory.
Id	getDirectoryId() Gets the Id of this directory.
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.
void	useFederatedDirectoryView() Federates the view for methods in this session.
void	useIsolatedDirectoryView() Isolates the view for methods in this session.
void	usePlenaryDirectoryView() A complete view of the directory 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.

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.