org.osid.rules.check

Interface InstructionLookupSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, 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 Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupInstructions() Tests if this user can perform Instruction lookups.
Engine	getEngine() Gets the Engine associated with this session.
Id	getEngineId() Gets the Engine Id associated with this session.
Instruction	getInstruction(Id instructionId) Gets the Instruction specified by its Id.
InstructionList	getInstructions() Gets all instructions.
InstructionList	getInstructionsByGenusType(Type instructionGenusType) Gets an InstructionList corresponding to the given instruction genus Type which does not include instructions of types derived from the specified Type.
InstructionList	getInstructionsByIds(IdList instructionIds) Gets an InstructionList corresponding to the given IdList.
InstructionList	getInstructionsByParentGenusType(Type instructionGenusType) Gets an InstructionList corresponding to the given instruction genus Type and include any additional instructions with genus types derived from the specified Type.
InstructionList	getInstructionsByRecordType(Type instructionRecordType) Gets an InstructionList containing the given instruction record Type.
InstructionList	getInstructionsForAgenda(Id agendaId) Gets an InstructionList for the given agenda.
InstructionList	getInstructionsForAgendaAndCheck(Id agendaId, Id checkId) Gets an InstructionList for the given agenda and check.
InstructionList	getInstructionsForAgendaAndCheckOnDate(Id agendaId, Id checkId, DateTime from, DateTime to) 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.
InstructionList	getInstructionsForAgendaOnDate(Id agendaId, DateTime from, DateTime to) Gets an InstructionList for the given agenda and effective for the entire given date range inclusive but not confined to the date range.
InstructionList	getInstructionsForCheck(Id checkId) Gets an InstructionList for the given check.
InstructionList	getInstructionsForCheckOnDate(Id checkId, DateTime from, DateTime to) Gets an InstructionList for the given check and effective for the entire given date range inclusive but not confined to the date range.
InstructionList	getInstructionsOnDate(DateTime from, DateTime to) Gets an InstructionList effective for the entire given date range inclusive but not confined to the date range.
void	useActiveInstructionView() Only active instructions are returned by methods in this session.
void	useAnyStatusInstructionView() All active and inactive instructions of are returned by methods in this session.
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.
void	useFederatedEngineView() Federates the view for methods in this session.
void	useIsolatedEngineView() Isolates the view for methods in this session.
void	usePlenaryInstructionView() A complete view of the Instruction returns is desired.

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.

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.

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.