Interface InstructionAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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.