OSID - osid.filing.DirectoryAdminSession Service Interface Definition

Interface	osid.filing.DirectoryAdminSession
Implements	`osid.OsidSession`
Used By	`osid.filing.FilingManager`
Used By	`osid.filing.FilingProxyManager`
Description	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	getDirectoryId
Description	Gets the `Id` of this directory.
Return	`osid.id.Id`		the `Id` of this directory
Compliance	`mandatory`		This method must be implemented.
Method	getDirectory
Description	Gets the directory associated with this session.
Return	`osid.filing.Directory`		the directory associated with this session
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canModifyDirectory
Description	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.
Return	`boolean`		`false` if modifying this directory is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	overwrite
Description	Overwrite files if a destination pathname exists and is a file.
Compliance	`mandatory`		This method is must be implemented.
Method	canCreateFileWithRecordTypes
Description	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	`osid.type.Type[]`	`fileRecordTypes`	array of file record types
Return	`boolean`		`true` if `File` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`fileRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getFileFormForCreate
Description	Gets the file form for creating new files. A new form should be requested for each create transaction.
Parameters	`string`	`name`	name of a file
Parameters	`osid.type.Type[]`	`fileRecordTypes`	array of file record types
Return	`osid.filing.FileForm`		the file form
Errors	ALREADY_EXISTS		`name` already exists as a file in this direrctory and `overwrite()` is `false`
	INVALID_ARGUMENT		`name` is invalid
	NULL_ARGUMENT		`name` or `fileRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	createFile
Description	Creates a new file in this directory.
Parameters	`osid.filing.FileForm`	`fileForm`	the file form
Return	`osid.filing.File`		the new file
Errors	ILLEGAL_STATE		`fileForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`fileForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`fileForm` did not originate from `getFileFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	getFileFormForUpdate
Description	Gets the file form for updating an existing files. A new file form should be requested for each update transaction.
Parameters	`osid.id.Id`	`fileId`	`Id` of the file to update
Return	`osid.filing.FileForm`		the file form
Errors	NOT_FOUND		`fileId` is not found
	NULL_ARGUMENT		`fileId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	updateFile
Description	Updates an existing file.
Parameters	`osid.filing.FileForm`	`fileForm`	the form containing the elements to be updated
Errors	ILLEGAL_STATE		`fileForm` already used in an update transaction
	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`fileForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`fileForm` did not originate from `getFileFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	deleteFile
Description	Deletes a file.
Parameters	`osid.id.Id`	`fileId`	the `Id` of the file to delete
Errors	NOT_FOUND		`fileId` is not found
	NULL_ARGUMENT		`fileId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canCreateDirectoryWithRecordTypes
Description	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	`osid.type.Type[]`	`directoryRecordTypes`	array of directory record types
Return	`boolean`		`true` if `Directory` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`directoryRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getDirectoryFormForCreate
Description	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	`string`	`name`	the name of a subdirectory in this directory
Parameters	`osid.type.Type[]`	`directoryRecordTypes`	array of directory record types
Return	`osid.filing.DirectoryForm`		the directory form
Errors	ALREADY_EXISTS		directory already exists and `overwrite()` is false
	INVALID_ARGUMENT		`name` is invalid
	NULL_ARGUMENT		`name` or `directoryRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	createDirectory
Description	Creates a new directory.
Parameters	`osid.filing.DirectoryForm`	`directoryForm`	the directory form
Return	`osid.filing.Directory`		the new directory
Errors	ILLEGAL_STATE		`directoryForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`directoryForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`directoryForm` did not originate from `getDirectoryFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	getDirectoryFormForUpdate
Description	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	`osid.id.Id`	`directoryId`	`Id` of the directory to update
Return	`osid.filing.DirectoryForm`		the directory form
Errors	NOT_FOUND		`directoryId` is not found
	NULL_ARGUMENT		`directoryId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	updateDirectory
Description	Updates an existing directory.
Parameters	`osid.filing.DirectoryForm`	`directoryForm`	the form containing the elements to be updated
Errors	ILLEGAL_STATE		`directoryForm` already used in an update transaction
	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`directoryForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`directoryForm` did not originate from `getDirectoryFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	deleteDirectory
Description	Deletes a directory in this directory. The directory to remove must be empty.
Parameters	`osid.id.Id`	`directoryId`	the `Id` of the directory to delete
Errors	NOT_FOUND		`directoryId` is not found
	NULL_ARGUMENT		`directoryId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	clearDirectory
Description	Deletes all files and subdirectories within the given directory.
Parameters	`osid.id.Id`	`directoryId`	the `Id` of the directory to delete
Errors	NOT_FOUND		`directoryId` is not found
	NULL_ARGUMENT		`directoryId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.