org.osid.recipe

Interface DirectionAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

DirectionBatchAdminSession

public interface DirectionAdminSession
extends OsidSession

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 Summary

Methods

Modifier and Type	Method and Description
void	aliasDirection(Id directionId, Id aliasId) Adds an Id to a Direction for the purpose of creating compatibility.
boolean	canCreateDirections() Tests if this user can create Directions.
boolean	canCreateDirectionWithRecordTypes(Type[] directionRecordTypes) Tests if this user can create a single Direction using the desired record types.
boolean	canCreateIngredientWithRecordTypes(Type[] ingredientRecordTypes) Tests if this user can create a single Ingredient using the desired record types.
boolean	canDeleteDirections() Tests if this user can delete Directions.
boolean	canManageDirectionAliases() Tests if this user can manage Id aliases for Directions.
boolean	canManageIngredients() Tests if this user can manage Ingedredients.
boolean	canSequenceDirections() Tests if this user can order Directions.
boolean	canUpdateDirections() Tests if this user can update Directions.
Direction	createDirection(DirectionForm directionForm) Creates a new Direction.
Ingredient	createIngredient(IngredientForm ingredientForm) Creates a new Ingredient.
void	deleteDirection(Id directionId) Deletes a Direction.
void	deleteIngredient(Id ingredientId) Deletes an Ingredient.
Cookbook	getCookbook() Gets the Cookbook associated with this session.
Id	getCookbookId() Gets the Cookbook Id associated with this session.
DirectionForm	getDirectionFormForCreate(Id recipeId, Type[] directionRecordTypes) Gets the direction form for creating new directions.
DirectionForm	getDirectionFormForUpdate(Id directionId) Gets the direction form for updating an existing direction.
IngredientForm	getIngredientFormForCreate(Id directionId, Type[] ingredientRecordTypes) Gets the ingredient form for creating new ingredients.
IngredientForm	getIngredientFormForUpdate(Id ingredientId) Gets the ingredient form for updating an existing ingredient.
void	moveDirectionAhead(Id directionId, Id recipeId, Id referenceId) Reorders directions in a recipe by moving the specified direction in front of a reference direction.
void	moveDirectionBehind(Id directionId, Id recipeId, Id referenceId) Reorders directions in a recipe by moving the specified direction behind a reference direction.
void	orderDirections(Id[] directionIds, Id recipeId) Reorders a set of directions in a recipe.
void	updateDirection(DirectionForm directionForm) Updates an existing direction.
void	updateIngredient(IngredientForm ingredientForm) Updates an existing ingredient.

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

getCookbookId

Id getCookbookId()

Gets the Cookbook Id associated with this session.

Returns:

the Cookbook Id associated with this session

Compliance:

mandatory - This method must be implemented.

getCookbook

Cookbook getCookbook()
                     throws OperationFailedException,
                            PermissionDeniedException

Gets the Cookbook associated with this session.

Returns:

the cookbook

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateDirections

boolean canCreateDirections()

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.

Returns:

false if Direction creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateDirectionWithRecordTypes

boolean canCreateDirectionWithRecordTypes(Type[] directionRecordTypes)

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:

directionRecordTypes - array of direction record types

Returns:

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

Throws:

NullArgumentException - directionRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getDirectionFormForCreate

DirectionForm getDirectionFormForCreate(Id recipeId,
                                      Type[] directionRecordTypes)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets the direction form for creating new directions. A new form should be requested for each create transaction.

Parameters:

recipeId - a recipe Id

directionRecordTypes - array of direction record types

Returns:

the direction form

Throws:

NotFoundException - recipeId Is not found

NullArgumentException - recipeId or directionRecordTypes 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.

createDirection

Direction createDirection(DirectionForm directionForm)
                          throws OperationFailedException,
                                 PermissionDeniedException

Creates a new Direction.

Parameters:

directionForm - the form for this Direction

Returns:

the new Direction

Throws:

IllegalStateException - directionForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - directionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - directionForm did not originate from getDirectionFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateDirections

boolean canUpdateDirections()

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.

Returns:

false if Direction modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getDirectionFormForUpdate

DirectionForm getDirectionFormForUpdate(Id directionId)
                                        throws NotFoundException,
                                               OperationFailedException

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

Parameters:

directionId - the Id of the Direction

Returns:

the direction form

Throws:

NotFoundException - directionId is not found

NullArgumentException - directionId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

updateDirection

void updateDirection(DirectionForm directionForm)
                     throws OperationFailedException,
                            PermissionDeniedException

Updates an existing direction.

Parameters:

directionForm - the form containing the elements to be updated

Throws:

IllegalStateException - directionForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - directionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - directionForm did not originate from getDirectionFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteDirections

boolean canDeleteDirections()

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.

Returns:

false if Direction deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteDirection

void deleteDirection(Id directionId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Deletes a Direction.

Parameters:

directionId - the Id of the Direction to remove

Throws:

NotFoundException - directionId not found

NullArgumentException - directionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageDirectionAliases

boolean canManageDirectionAliases()

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.

Returns:

false if Direction aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasDirection

void aliasDirection(Id directionId,
                  Id aliasId)
                    throws AlreadyExistsException,
                           NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

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:

directionId - the Id of a Direction

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - directionId not found

NullArgumentException - directionId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageIngredients

boolean canManageIngredients()

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.

Returns:

false if Ingredient management is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateIngredientWithRecordTypes

boolean canCreateIngredientWithRecordTypes(Type[] ingredientRecordTypes)

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:

ingredientRecordTypes - array of ingredient record types

Returns:

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

Throws:

NullArgumentException - ingredientRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getIngredientFormForCreate

IngredientForm getIngredientFormForCreate(Id directionId,
                                        Type[] ingredientRecordTypes)
                                          throws NotFoundException,
                                                 OperationFailedException,
                                                 PermissionDeniedException

Gets the ingredient form for creating new ingredients. A new form should be requested for each create transaction.

Parameters:

directionId - an ingredient Id

ingredientRecordTypes - array of ingredient record types

Returns:

the ingredient form

Throws:

NotFoundException - directionId Is not found

NullArgumentException - directionId or ingredientRecordTypes 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.

createIngredient

Ingredient createIngredient(IngredientForm ingredientForm)
                            throws OperationFailedException,
                                   PermissionDeniedException

Creates a new Ingredient.

Parameters:

ingredientForm - the form for this Ingredient

Returns:

the new Ingredient

Throws:

IllegalStateException - ingredientForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - ingredientForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - ingredientForm did not originate from geIngredientFormForCreate()

Compliance:

mandatory - This method must be implemented.

getIngredientFormForUpdate

IngredientForm getIngredientFormForUpdate(Id ingredientId)
                                          throws NotFoundException,
                                                 OperationFailedException

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

Parameters:

ingredientId - the Id of the Ingredient

Returns:

the ingredient form

Throws:

NotFoundException - ingredientId is not found

NullArgumentException - ingredientId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

updateIngredient

void updateIngredient(IngredientForm ingredientForm)
                      throws OperationFailedException,
                             PermissionDeniedException

Updates an existing ingredient.

Parameters:

ingredientForm - the form containing the elements to be updated

Throws:

IllegalStateException - ingredientForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - ingredientForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - ingredientForm did not originate from getIngredientFormForUpdate()

Compliance:

mandatory - This method must be implemented.

deleteIngredient

void deleteIngredient(Id ingredientId)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Deletes an Ingredient.

Parameters:

ingredientId - the Id of the Ingredient to remove

Throws:

NotFoundException - ingredientId not found

NullArgumentException - ingredientId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canSequenceDirections

boolean canSequenceDirections()

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.

Returns:

false if Direction ordering is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

moveDirectionAhead

void moveDirectionAhead(Id directionId,
                      Id recipeId,
                      Id referenceId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Reorders directions in a recipe by moving the specified direction in front of a reference direction.

Parameters:

directionId - the Id of a Direction

recipeId - the Id of a Recipe

referenceId - the reference direction Id

Throws:

NotFoundException - directionId, recipeId, or referenceId not found or, directionId or referenceId not related to recipeId

NullArgumentException - directionId, recipeId or referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

moveDirectionBehind

void moveDirectionBehind(Id directionId,
                       Id recipeId,
                       Id referenceId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Reorders directions in a recipe by moving the specified direction behind a reference direction.

Parameters:

directionId - the Id of a Direction

recipeId - the Id of a Recipe

referenceId - the reference direction Id

Throws:

NotFoundException - directionId, recipeId, or referenceId not found or, directionId or referenceId not related to recipeId

NullArgumentException - directionId, recipeId or referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

orderDirections

void orderDirections(Id[] directionIds,
                   Id recipeId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Reorders a set of directions in a recipe.

Parameters:

directionIds - the Ids for a set of Directions

recipeId - the Id of a Recipe

Throws:

NotFoundException - recipeId not found or, a directionId not related to recipeId

NullArgumentException - directionIds or recipeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.