org.osid.rules.check

Interface InstructionAdminSession

All Superinterfaces:

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

public interface InstructionAdminSession
extends OsidSession

This session creates, updates, and deletes Instructions. 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 an Instruction, an InstructionForm is requested using getInstructionFormForCreate() specifying the desired agenda, check, and record Types or none if no record Types are needed. The returned InstructionForm 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 InstructionForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each InstructionForm corresponds to an attempted transaction.

For updates, InstructionForms are requested to the Instruction Id that is to be updated using getInstructionFormForUpdate(). Similarly, the InstructionForm has metadata about the data that can be updated and it can perform validation before submitting the update. The InstructionForm can only be used once for a successful update and cannot be reused.

The delete operations delete Instructions. To unmap an Instruction from the current Engine, the InstructionEngineAssignmentSession should be used. These delete operations attempt to remove the Instruction itself thus removing it from all known Engine 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	aliasInstruction(Id instructionId, Id aliasId) Adds an Id to an Instruction for the purpose of creating compatibility.
boolean	canCreateInstructions() Tests if this user can create Instructions.
boolean	canCreateInstructionWithRecordTypes(Type[] instructionRecordTypes) Tests if this user can create a single Instruction using the desired record types.
boolean	canDeleteInstructions() Tests if this user can delete Instructions.
boolean	canManageInstructionAliases() Tests if this user can manage Id aliases for Instructions.
boolean	canSequenceInstructions() Tests if this user can order Instructions.
boolean	canUpdateInstructions() Tests if this user can update Instructions.
Instruction	createInstruction(InstructionForm instructionForm) Creates a new Instruction.
void	deleteInstruction(Id instructionId) Deletes an Instruction.
Engine	getEngine() Gets the Engine associated with this session.
Id	getEngineId() Gets the Engine Id associated with this session.
InstructionForm	getInstructionFormForCreate(Id agendaId, Id checkId, Type[] instructionRecordTypes) Gets the instruction form for creating new instructions.
InstructionForm	getInstructionFormForUpdate(Id instructionId) Gets the instruction form for updating an existing instruction.
void	moveInstructionAhead(Id instructionId, Id agendaId, Id referenceId) Reorders instructions in an agenda by moving the specified instruction in front of a reference instruction.
void	moveInstructionBehind(Id instructionId, Id agendaId, Id referenceId) Reorders instructions in an agenda by moving the specified instruction behind a reference instruction.
void	orderInstructions(Id[] instructionIds, Id agendaId) Reorders a set of instructions in an agenda.
void	updateInstruction(InstructionForm instructionForm) Updates an existing instruction.

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

getEngineId

Id getEngineId()

Gets the Engine Id associated with this session.

Returns:

the Engine Id associated with this session

Compliance:

mandatory - This method must be implemented.

getEngine

Engine getEngine()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the Engine associated with this session.

Returns:

the engine

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateInstructions

boolean canCreateInstructions()

Tests if this user can create Instructions. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating an Instruction 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 Instruction creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateInstructionWithRecordTypes

boolean canCreateInstructionWithRecordTypes(Type[] instructionRecordTypes)

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

Parameters:

instructionRecordTypes - array of instruction record types

Returns:

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

Throws:

NullArgumentException - instructionRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getInstructionFormForCreate

InstructionForm getInstructionFormForCreate(Id agendaId,
                                          Id checkId,
                                          Type[] instructionRecordTypes)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

Gets the instruction form for creating new instructions. A new form should be requested for each create transaction.

Parameters:

agendaId - an agenda Id

checkId - a check Id

instructionRecordTypes - array of instruction record types

Returns:

the instruction form

Throws:

NotFoundException - agendaId or checkId is not found

NullArgumentException - agendaId, checkId, or instructionRecordTypes 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.

createInstruction

Instruction createInstruction(InstructionForm instructionForm)
                              throws OperationFailedException,
                                     PermissionDeniedException

Creates a new Instruction.

Parameters:

instructionForm - the form for this Instruction

Returns:

the new Instruction

Throws:

IllegalStateException - instructionForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - i nstructionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - instructionForm did not orginate from getInstructionFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateInstructions

boolean canUpdateInstructions()

Tests if this user can update Instructions. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating an Instruction 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 Instruction modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getInstructionFormForUpdate

InstructionForm getInstructionFormForUpdate(Id instructionId)
                                            throws NotFoundException,
                                                   OperationFailedException

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

Parameters:

instructionId - the Id of the Instruction

Returns:

the instruction form

Throws:

NotFoundException - instructionId is not found

NullArgumentException - instructionId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

updateInstruction

void updateInstruction(InstructionForm instructionForm)
                       throws OperationFailedException,
                              PermissionDeniedException

Updates an existing instruction.

Parameters:

instructionForm - the form containing the elements to be updated

Throws:

IllegalStateException - instructionForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - instructionId or instructionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - instructionForm did not orginate from getInstructionFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteInstructions

boolean canDeleteInstructions()

Tests if this user can delete Instructions. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Instruction 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 Instruction deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteInstruction

void deleteInstruction(Id instructionId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Deletes an Instruction.

Parameters:

instructionId - the Id of the Instruction to remove

Throws:

NotFoundException - instructionId not found

NullArgumentException - instructionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageInstructionAliases

boolean canManageInstructionAliases()

Tests if this user can manage Id aliases for Instructions. 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 Instruction aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasInstruction

void aliasInstruction(Id instructionId,
                    Id aliasId)
                      throws AlreadyExistsException,
                             NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Adds an Id to an Instruction for the purpose of creating compatibility. The primary Id of the Instruction is determined by the provider. The new Id performs as an alias to the primary Id . If the alias is a pointer to another instruction, it is reassigned to the given instruction Id.

Parameters:

instructionId - the Id of an Instruction

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - instructionId not found

NullArgumentException - instructionId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canSequenceInstructions

boolean canSequenceInstructions()

Tests if this user can order Instructions. A return of true does not guarantee successful authorization. A return of false indicates that it is known sequencing operations 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 Instruction ordering is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

moveInstructionAhead

void moveInstructionAhead(Id instructionId,
                        Id agendaId,
                        Id referenceId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Reorders instructions in an agenda by moving the specified instruction in front of a reference instruction.

Parameters:

instructionId - the Id of an Instruction

agendaId - the Id of an Agenda

referenceId - the reference instruction Id

Throws:

NotFoundException - instructionId, agendaId, or referenceId not found or, instructionId or referenceId not related to agendaId

NullArgumentException - instructionId, agendaId or referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

moveInstructionBehind

void moveInstructionBehind(Id instructionId,
                         Id agendaId,
                         Id referenceId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Reorders instructions in an agenda by moving the specified instruction behind a reference instruction.

Parameters:

instructionId - the Id of an Instruction

agendaId - the Id of an Agenda

referenceId - the reference instruction Id

Throws:

NotFoundException - instructionId, agendaId, or referenceId not found or, instructionId or referenceId not related to agendaId

NullArgumentException - instructionId, agendaId or referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

orderInstructions

void orderInstructions(Id[] instructionIds,
                     Id agendaId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Reorders a set of instructions in an agenda.

Parameters:

instructionIds - the Ids for a set of Instructions

agendaId - the Id of an Agenda

Throws:

NotFoundException - agendaId not found or, an instructionId not related to agendaId

NullArgumentException - instructionIds or agendaId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.