Interface InstructionLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
public interface InstructionLookupSession extends OsidSession

This session defines methods for retrieving instructions.

This lookup session defines several views:

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete result set or is an error condition
  • isolated engine view: All instruction methods in this session operate, retrieve and pertain to instructions defined explicitly in the current engine. Using an isolated view is useful for managing Instructions with the InstructionAdminSession .
  • federated engine view: All instruction lookup methods in this session operate, retrieve and pertain to all instructions defined in this engine and any other instructions implicitly available in this engine through engine inheritence.
  • active instruction view: All instruction lookup methods return active instructions.
  • any status instruction view: instructions of any active or inactive status are returned from methods.

The methods useFederatedEngineView() and useIsolatedEngineView() behave as a radio group and one should be selected before invoking any lookup methods.

Instructions may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the Instructions .

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

    • canLookupInstructions

      boolean canLookupInstructions()
      Tests if this user can perform Instruction lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED . This is intended as a hint to an application that may not offer lookup operations to unauthorized users.
      Returns:
      false if lookup methods are not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • useComparativeInstructionView

      void useComparativeInstructionView()
      The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.
      Compliance:
      mandatory - This method is must be implemented.

    • usePlenaryInstructionView

      void usePlenaryInstructionView()
      A complete view of the Instruction returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.
      Compliance:
      mandatory - This method is must be implemented.

    • useFederatedEngineView

      void useFederatedEngineView()
      Federates the view for methods in this session. A federated view will include instructions in engines which are children of this engine in the engine hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedEngineView

      void useIsolatedEngineView()
      Isolates the view for methods in this session. An isolated view restricts retrievals to this engine only.
      Compliance:
      mandatory - This method is must be implemented.

    • useActiveInstructionView

      void useActiveInstructionView()
      Only active instructions are returned by methods in this session.
      Compliance:
      mandatory - This method is must be implemented.

    • useAnyStatusInstructionView

      void useAnyStatusInstructionView()
      All active and inactive instructions of are returned by methods in this session.
      Compliance:
      mandatory - This method is must be implemented.

    • getInstruction

      Instruction getInstruction(Id instructionId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the Instruction specified by its Id . In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Instruction may have a different Id than requested, such as the case where a duplicate Id was assigned to an Instruction and retained for compatibility. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      instructionId - the Id of the Instruction to retrieve
      Returns:
      the returned Instruction
      Throws:
      NotFoundException - no Instruction found with the given Id
      NullArgumentException - instructionId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsByIds

      InstructionList getInstructionsByIds(IdList instructionIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets an InstructionList corresponding to the given IdList . In plenary mode, the returned list contains all of the instructions specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Instructions may be omitted from the list and may present the elements in any order including returning a unique set. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      instructionIds - the list of Ids to retrieve
      Returns:
      the returned Instruction list
      Throws:
      NotFoundException - an Id was not found
      NullArgumentException - instructionIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsByGenusType

      InstructionList getInstructionsByGenusType(Type instructionGenusType) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList corresponding to the given instruction genus Type which does not include instructions of types derived from the specified Type . In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      instructionGenusType - an instruction genus type
      Returns:
      the returned Instruction list
      Throws:
      NullArgumentException - instructionGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsByParentGenusType

      InstructionList getInstructionsByParentGenusType(Type instructionGenusType) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList corresponding to the given instruction genus Type and include any additional instructions with genus types derived from the specified Type . In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      instructionGenusType - an instruction genus type
      Returns:
      the returned Instruction list
      Throws:
      NullArgumentException - instructionGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsByRecordType

      InstructionList getInstructionsByRecordType(Type instructionRecordType) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList containing the given instruction record Type . In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      instructionRecordType - an instruction record type
      Returns:
      the returned Instruction list
      Throws:
      NullArgumentException - instructionRecordType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsOnDate

      InstructionList getInstructionsOnDate(DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList effective for the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      from - a start date
      to - an end date
      Returns:
      the returned Instruction list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsForAgenda

      InstructionList getInstructionsForAgenda(Id agendaId) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList for the given agenda. In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      agendaId - an agenda Id
      Returns:
      the returned Instruction list
      Throws:
      NullArgumentException - agendaId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsForAgendaOnDate

      InstructionList getInstructionsForAgendaOnDate(Id agendaId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList for the given agenda and effective for the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      agendaId - an agenda Id
      from - a start date
      to - an end date
      Returns:
      the returned Instruction list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - agendaId, from , or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsForCheck

      InstructionList getInstructionsForCheck(Id checkId) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList for the given check. In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      checkId - a check Id
      Returns:
      the returned Instruction list
      Throws:
      NullArgumentException - checkId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsForCheckOnDate

      InstructionList getInstructionsForCheckOnDate(Id checkId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList for the given check and effective for the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      checkId - a check Id
      from - a start date
      to - an end date
      Returns:
      the returned Instruction list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - checkId, from , or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsForAgendaAndCheck

      InstructionList getInstructionsForAgendaAndCheck(Id agendaId, Id checkId) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList for the given agenda and check. In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      agendaId - an agenda Id
      checkId - a check Id
      Returns:
      the returned Instruction list
      Throws:
      NullArgumentException - agendaId or checkId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructionsForAgendaAndCheckOnDate

      InstructionList getInstructionsForAgendaAndCheckOnDate(Id agendaId, Id checkId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets an InstructionList for the given agenda and check and effective for the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known instructions or an error results. Otherwise, the returned list may contain only those instructions that are accessible through this session. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Parameters:
      agendaId - an agenda Id
      checkId - a check Id
      from - a start date
      to - an end date
      Returns:
      the returned Instruction list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - agendaId, checkId, from , or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstructions

      InstructionList getInstructions() throws OperationFailedException, PermissionDeniedException
      Gets all instructions. In plenary mode, the returned list contains all of the instructions, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Instructions may be omitted from the list and may present the elements in any order including returning a unique set. In active mode, instructions are returned that are currently active. In any status mode, active and inactive instructions are returned.
      Returns:
      the returned Instruction list
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.