OSID - osid.recipe.DirectionAdminSession Service Interface Definition

Interface	osid.recipe.DirectionAdminSession
Implements	`osid.OsidSession`
Implemented By	`osid.recipe.batch.DirectionBatchAdminSession`
Used By	`osid.recipe.RecipeManager`
Used By	`osid.recipe.RecipeProxyManager`
Description	This session creates, updates, and deletes `Directions`. The data for create and update is provided by the consumer via the form object. `OsidForms` are requested for each create or update and may not be reused. Create and update operations differ in their usage. To create a `Direction`, a `DirectionForm` is requested using `getDirectionFormForCreate()` specifying the desired recipe and record `Types` or none if no record `Types` are needed. The returned `DirectionForm` will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the `DirectionForm` is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each `DirectionForm` corresponds to an attempted transaction. For updates, `DirectionForms` are requested to the `Direction` `Id` that is to be updated using `getDirectionFormForUpdate()`. Similarly, the `DirectionForm` has metadata about the data that can be updated and it can perform validation before submitting the update. The `DirectionForm` can only be used once for a successful update and cannot be reused. The delete operations delete `Directions`. To unmap a `Direction` from the current `Cookbook`, the `DirectionCookbookAssignmentSession` should be used. These delete operations attempt to remove the `Direction` itself thus removing it from all known `Cookbook` catalogs. This session includes an `Id` aliasing mechanism to assign an external `Id` to an internally assigned Id.
Method	getCookbookId
Description	Gets the `Cookbook` `Id` associated with this session.
Return	`osid.id.Id`		the `Cookbook Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getCookbook
Description	Gets the `Cookbook` associated with this session.
Return	`osid.recipe.Cookbook`		the cookbook
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canCreateDirections
Description	Tests if this user can create `Directions`. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a `Direction` 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 `Direction` creation is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateDirectionWithRecordTypes
Description	Tests if this user can create a single `Direction` using the desired record types. While `RecipeManager.getDirectionRecordTypes()` can be used to examine which records are supported, this method tests which record(s) are required for creating a specific `Direction`. Providing an empty array tests if a `Direction` can be created with no records.
Parameters	`osid.type.Type[]`	`directionRecordTypes`	array of direction record types
Return	`boolean`		`true` if `Direction` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`directionRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getDirectionFormForCreate
Description	Gets the direction form for creating new directions. A new form should be requested for each create transaction.
Parameters	`osid.id.Id`	`recipeId`	a recipe `Id`
Parameters	`osid.type.Type[]`	`directionRecordTypes`	array of direction record types
Return	`osid.recipe.DirectionForm`		the direction form
Errors	NOT_FOUND		`recipeId` Is not found
	NULL_ARGUMENT		`recipeId` or `directionRecordTypes` 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	createDirection
Description	Creates a new `Direction`.
Parameters	`osid.recipe.DirectionForm`	`directionForm`	the form for this `Direction`
Return	`osid.recipe.Direction`		the new `Direction`
Errors	ILLEGAL_STATE		`directionForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`directionForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`directionForm` did not originate from `getDirectionFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateDirections
Description	Tests if this user can update `Directions`. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a `Direction` will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.
Return	`boolean`		`false` if `Direction` modification is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getDirectionFormForUpdate
Description	Gets the direction form for updating an existing direction. A new direction form should be requested for each update transaction.
Parameters	`osid.id.Id`	`directionId`	the `Id` of the `Direction`
Return	`osid.recipe.DirectionForm`		the direction form
Errors	NOT_FOUND		`directionId` is not found
	NULL_ARGUMENT		`directionId` is `null`
	OPERATION_FAILED		unable to complete request
Compliance	`mandatory`		This method must be implemented.
Method	updateDirection
Description	Updates an existing direction.
Parameters	`osid.recipe.DirectionForm`	`directionForm`	the form containing the elements to be updated
Errors	ILLEGAL_STATE		`directionForm` already used in an update transaction
	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`directionForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`directionForm` did not originate from `getDirectionFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteDirections
Description	Tests if this user can delete `Directions`. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a `Direction` will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.
Return	`boolean`		`false` if `Direction` deletion is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	deleteDirection
Description	Deletes a `Direction`.
Parameters	`osid.id.Id`	`directionId`	the `Id` of the `Direction` to remove
Errors	NOT_FOUND		`directionId` not found
	NULL_ARGUMENT		`directionId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canManageDirectionAliases
Description	Tests if this user can manage `Id` aliases for `Directions`. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.
Return	`boolean`		`false` if `Direction` aliasing is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	aliasDirection
Description	Adds an `Id` to a `Direction` for the purpose of creating compatibility. The primary `Id` of the `Direction` is determined by the provider. The new `Id` performs as an alias to the primary `Id`. If the alias is a pointer to another direction, it is reassigned to the given direction `Id`.
Parameters	`osid.id.Id`	`directionId`	the `Id` of a `Direction`
Parameters	`osid.id.Id`	`aliasId`	the alias `Id`
Errors	ALREADY_EXISTS		`aliasId` is already assigned
	NOT_FOUND		`directionId` not found
	NULL_ARGUMENT		`directionId` or `aliasId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canManageIngredients
Description	Tests if this user can manage `Ingedredients`. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer sequencing operations to an unauthorized user.
Return	`boolean`		`false` if `Ingredient` management is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateIngredientWithRecordTypes
Description	Tests if this user can create a single `Ingredient` using the desired record types. While `RecipeManager.getIngreientRecordTypes()` can be used to examine which records are supported, this method tests which record(s) are required for creating a specific `Ingredient`. Providing an empty array tests if an `Ingredient` can be created with no records.
Parameters	`osid.type.Type[]`	`ingredientRecordTypes`	array of ingredient record types
Return	`boolean`		`true` if `Ingredient` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`ingredientRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getIngredientFormForCreate
Description	Gets the ingredient form for creating new ingredients. A new form should be requested for each create transaction.
Parameters	`osid.id.Id`	`directionId`	an ingredient `Id`
Parameters	`osid.type.Type[]`	`ingredientRecordTypes`	array of ingredient record types
Return	`osid.recipe.IngredientForm`		the ingredient form
Errors	NOT_FOUND		`directionId` Is not found
	NULL_ARGUMENT		`directionId` or `ingredientRecordTypes` 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	createIngredient
Description	Creates a new `Ingredient`.
Parameters	`osid.recipe.IngredientForm`	`ingredientForm`	the form for this `Ingredient`
Return	`osid.recipe.Ingredient`		the new `Ingredient`
Errors	ILLEGAL_STATE		`ingredientForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`ingredientForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`ingredientForm` did not originate from `geIngredientFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	getIngredientFormForUpdate
Description	Gets the ingredient form for updating an existing ingredient. A new ingredient form should be requested for each update transaction.
Parameters	`osid.id.Id`	`ingredientId`	the `Id` of the `Ingredient`
Return	`osid.recipe.IngredientForm`		the ingredient form
Errors	NOT_FOUND		`ingredientId` is not found
	NULL_ARGUMENT		`ingredientId` is `null`
	OPERATION_FAILED		unable to complete request
Compliance	`mandatory`		This method must be implemented.
Method	updateIngredient
Description	Updates an existing ingredient.
Parameters	`osid.recipe.IngredientForm`	`ingredientForm`	the form containing the elements to be updated
Errors	ILLEGAL_STATE		`ingredientForm` already used in an update transaction
	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`ingredientForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`ingredientForm` did not originate from `getIngredientFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	deleteIngredient
Description	Deletes an `Ingredient`.
Parameters	`osid.id.Id`	`ingredientId`	the `Id` of the `Ingredient` to remove
Errors	NOT_FOUND		`ingredientId` not found
	NULL_ARGUMENT		`ingredientId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canSequenceDirections
Description	Tests if this user can order `Directions`. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer sequencing operations to an unauthorized user.
Return	`boolean`		`false` if `Direction` ordering is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	moveDirectionAhead
Description	Reorders directions in a recipe by moving the specified direction in front of a reference direction.
Parameters	`osid.id.Id`	`directionId`	the `Id` of a `Direction`
	`osid.id.Id`	`recipeId`	the `Id` of a `Recipe`
	`osid.id.Id`	`referenceId`	the reference direction `Id`
Errors	NOT_FOUND		`directionId, recipeId`, or `referenceId` not found or, `directionId` or `referenceId` not related to `recipeId`
	NULL_ARGUMENT		`directionId, recipeId` or `referenceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	moveDirectionBehind
Description	Reorders directions in a recipe by moving the specified direction behind a reference direction.
Parameters	`osid.id.Id`	`directionId`	the `Id` of a `Direction`
	`osid.id.Id`	`recipeId`	the `Id` of a `Recipe`
	`osid.id.Id`	`referenceId`	the reference direction `Id`
Errors	NOT_FOUND		`directionId, recipeId`, or `referenceId` not found or, `directionId` or `referenceId` not related to `recipeId`
	NULL_ARGUMENT		`directionId, recipeId` or `referenceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	orderDirections
Description	Reorders a set of directions in a recipe.
Parameters	`osid.id.Id[]`	`directionIds`	the `Ids` for a set of `Directions`
Parameters	`osid.id.Id`	`recipeId`	the `Id` of a `Recipe`
Errors	NOT_FOUND		`recipeId` not found or, a `directionId` not related to `recipeId`
	NULL_ARGUMENT		`directionIds` or `recipeId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.