org.osid.filing

Interface DirectoryAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface DirectoryAdminSession
extends OsidSession

This session creates and removes files and directories under the directory associated with this session.

The view of the administrative methods defined in this session is determined by the provider. For an instance of this session where no path has been specified, it may not be parallel to the DirectoryLookupSession. For example, a default DirectoryLookupSession may view the entire directory hierarchy while the default DirectoryAdminSession uses an isolated Directory to create new entries. Another scenario is a federated provider who does not wish to permit administrative operations for the federation unaware.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canCreateDirectoryWithRecordTypes(Type[] directoryRecordTypes) Tests if this user can create a single Directory using the desired record types.
boolean	canCreateFileWithRecordTypes(Type[] fileRecordTypes) Tests if this user can create a single File using the desired record types.
boolean	canModifyDirectory() Tests if this user can create or remove entries in this directory.
void	clearDirectory(Id directoryId) Deletes all files and subdirectories within the given directory.
Directory	createDirectory(DirectoryForm directoryForm) Creates a new directory.
File	createFile(FileForm fileForm) Creates a new file in this directory.
void	deleteDirectory(Id directoryId) Deletes a directory in this directory.
void	deleteFile(Id fileId) Deletes a file.
Directory	getDirectory() Gets the directory associated with this session.
DirectoryForm	getDirectoryFormForCreate(java.lang.String name, Type[] directoryRecordTypes) Gets the file form for creating new directories.
DirectoryForm	getDirectoryFormForUpdate(Id directoryId) Gets the directory form for updating an existing files.
Id	getDirectoryId() Gets the Id of this directory.
FileForm	getFileFormForCreate(java.lang.String name, Type[] fileRecordTypes) Gets the file form for creating new files.
FileForm	getFileFormForUpdate(Id fileId) Gets the file form for updating an existing files.
void	overwrite() Overwrite files if a destination pathname exists and is a file.
void	updateDirectory(DirectoryForm directoryForm) Updates an existing directory.
void	updateFile(FileForm fileForm) Updates an existing file.

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.

canModifyDirectory

boolean canModifyDirectory()

Tests if this user can create or remove entries in this directory. A return of true does not guarantee successful authorization. A return of false indicates that it is known modifying this directory will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer create operations to an unauthorized user.

Returns:

false if modifying this directory is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

overwrite

void overwrite()

Overwrite files if a destination pathname exists and is a file.

Compliance:

mandatory - This method is must be implemented.

canCreateFileWithRecordTypes

boolean canCreateFileWithRecordTypes(Type[] fileRecordTypes)

Tests if this user can create a single File using the desired record types. While FilingManager.getFileRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific File. Providing an empty array tests if a File can be created with no records.

Parameters:

fileRecordTypes - array of file record types

Returns:

true if File creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - fileRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getFileFormForCreate

FileForm getFileFormForCreate(java.lang.String name,
                            Type[] fileRecordTypes)
                              throws AlreadyExistsException,
                                     OperationFailedException,
                                     PermissionDeniedException

Gets the file form for creating new files. A new form should be requested for each create transaction.

Parameters:

name - name of a file

fileRecordTypes - array of file record types

Returns:

the file form

Throws:

AlreadyExistsException - name already exists as a file in this direrctory and overwrite() is false

InvalidArgumentException - name is invalid

NullArgumentException - name or fileRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createFile

File createFile(FileForm fileForm)
                throws OperationFailedException,
                       PermissionDeniedException

Creates a new file in this directory.

Parameters:

fileForm - the file form

Returns:

the new file

Throws:

IllegalStateException - fileForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - fileForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - fileForm did not originate from getFileFormForCreate()

Compliance:

mandatory - This method must be implemented.

getFileFormForUpdate

FileForm getFileFormForUpdate(Id fileId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Gets the file form for updating an existing files. A new file form should be requested for each update transaction.

Parameters:

fileId - Id of the file to update

Returns:

the file form

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.

updateFile

void updateFile(FileForm fileForm)
                throws OperationFailedException,
                       PermissionDeniedException

Updates an existing file.

Parameters:

fileForm - the form containing the elements to be updated

Throws:

IllegalStateException - fileForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - fileForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - fileForm did not originate from getFileFormForUpdate()

Compliance:

mandatory - This method must be implemented.

deleteFile

void deleteFile(Id fileId)
                throws NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

Deletes a file.

Parameters:

fileId - the Id of the file to delete

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.

canCreateDirectoryWithRecordTypes

boolean canCreateDirectoryWithRecordTypes(Type[] directoryRecordTypes)

Tests if this user can create a single Directory using the desired record types. While FilingManager.getDiectoryRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Directory. Providing an empty array tests if a Directory can be created with no records.

Parameters:

directoryRecordTypes - array of directory record types

Returns:

true if Directory creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - directoryRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getDirectoryFormForCreate

DirectoryForm getDirectoryFormForCreate(java.lang.String name,
                                      Type[] directoryRecordTypes)
                                        throws AlreadyExistsException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets the file form for creating new directories. A new form should be requested for each create transaction. This method is used for creating new Directories where only the Directory Type is known.

Parameters:

name - the name of a subdirectory in this directory

directoryRecordTypes - array of directory record types

Returns:

the directory form

Throws:

AlreadyExistsException - directory already exists and overwrite() is false

InvalidArgumentException - name is invalid

NullArgumentException - name or directoryRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createDirectory

Directory createDirectory(DirectoryForm directoryForm)
                          throws OperationFailedException,
                                 PermissionDeniedException

Creates a new directory.

Parameters:

directoryForm - the directory form

Returns:

the new directory

Throws:

IllegalStateException - directoryForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - directoryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - directoryForm did not originate from getDirectoryFormForCreate()

Compliance:

mandatory - This method must be implemented.

getDirectoryFormForUpdate

DirectoryForm getDirectoryFormForUpdate(Id directoryId)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets the directory form for updating an existing files. A new directory form should be requested for each update transaction. This method is used when the Directory to be updated is known and is desired to access any metadata specific to the Directory being updated.

Parameters:

directoryId - Id of the directory to update

Returns:

the directory form

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.

updateDirectory

void updateDirectory(DirectoryForm directoryForm)
                     throws OperationFailedException,
                            PermissionDeniedException

Updates an existing directory.

Parameters:

directoryForm - the form containing the elements to be updated

Throws:

IllegalStateException - directoryForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - directoryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - directoryForm did not originate from getDirectoryFormForUpdate()

Compliance:

mandatory - This method must be implemented.

deleteDirectory

void deleteDirectory(Id directoryId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Deletes a directory in this directory. The directory to remove must be empty.

Parameters:

directoryId - the Id of the directory to delete

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.

clearDirectory

void clearDirectory(Id directoryId)
                    throws NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Deletes all files and subdirectories within the given directory.

Parameters:

directoryId - the Id of the directory to delete

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.