org.osid.course.syllabus

Interface DocetLookupSession

All Superinterfaces:

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

public interface DocetLookupSession
extends OsidSession

This session provides methods for retrieving Docet objects. The Docet represents a collection of syllabi.

This session defines views that offer differing behaviors when retrieving multiple objects.

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete view or is an error condition
• isolated course catalog view: All docet methods in this session operate, retrieve and pertain to docetsdefined explicitly in the current course catalog. Using an isolated view is useful for managing docetswith the DocetAdminSession.
• federated course catalog view: All docet lookup methods in this session operate, retrieve and pertain to all docetsdefined in this course catalog and any other course catalogs implicitly available in this course catalog through course catalog inheritence.
• effective docet view: All docet lookup methods return docets where the current date falls in between the effective dates inclusive.
• any effective docet view: Docets of any effective date are returned from methods.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupDocets() Tests if this user can perform Docet lookups.
CourseCatalog	getCourseCatalog() Gets the CourseCatalog associated with this session.
Id	getCourseCatalogId() Gets the CourseCatalog Id associated with this session.
Docet	getDocet(Id docetId) Gets the Docet specified by its Id.
DocetList	getDocets() Gets all Docets.
DocetList	getDocetsByGenusType(Type docetGenusType) Gets an DocetList corresponding to the given docet genus Type which does not include docetsof genus types derived from the specified Type.
DocetList	getDocetsByIds(IdList docetIds) Gets an DocetList corresponding to the given IdList.
DocetList	getDocetsByParentGenusType(Type docetGenusType) Gets an DocetList corresponding to the given docet genus Type and include any additional docetswith genus types derived from the specified Type.
DocetList	getDocetsByRecordType(Type docetRecordType) Gets an DocetList containing the given docet record Type.
DocetList	getDocetsForActivityUnit(Id activityUnitId) Gets an DocetList for the given activity unit Id.
DocetList	getDocetsForActivityUnitOnDate(Id activityUnitId, DateTime from, DateTime to) Gets an DocetList for an activity unit effective sduring the entire given date range inclusive but not confined to the date range.
DocetList	getDocetsForModule(Id moduleId) Gets an DocetList for the given module Id.
DocetList	getDocetsForModuleAndActivityUnit(Id moduleId, Id activityUnitId) Gets an DocetList for the given module and activity unit .
DocetList	getDocetsForModuleAndActivityUnitOnDate(Id moduleId, Id activityUnitId, DateTime from, DateTime to) Gets an DocetList for a module and activity unit effective during the entire given date range inclusive but not confined to the date range.
DocetList	getDocetsForModuleOnDate(Id moduleId, DateTime from, DateTime to) Gets an DocetList for a module effective during the entire given date range inclusive but not confined to the date range.
DocetList	getDocetsOnDate(DateTime from, DateTime to) Gets an DocetList effective sduring the entire given date range inclusive but not confined to the date range.
void	useAnyEffectiveDocetView() All docets of any effective dates are returned by all methods in this session.
void	useComparativeDocetView() 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	useEffectiveDocetView() Only docets whose effective dates are current are returned by methods in this session.
void	useFederatedCourseCatalogView() Federates the view for methods in this session.
void	useIsolatedCourseCatalogView() Isolates the view for methods in this session.
void	usePlenaryDocetView() A complete view of the Docet 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

getCourseCatalogId

Id getCourseCatalogId()

Gets the CourseCatalog Id associated with this session.

Returns:

the CourseCatalog Id associated with this session

Compliance:

mandatory - This method must be implemented.

getCourseCatalog

CourseCatalog getCourseCatalog()
                               throws OperationFailedException,
                                      PermissionDeniedException

Gets the CourseCatalog associated with this session.

Returns:

the course catalog

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupDocets

boolean canLookupDocets()

Tests if this user can perform Docet 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.

useComparativeDocetView

void useComparativeDocetView()

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.

usePlenaryDocetView

void usePlenaryDocetView()

A complete view of the Docet 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.

useFederatedCourseCatalogView

void useFederatedCourseCatalogView()

Federates the view for methods in this session. A federated view will include docetsin course catalogs which are children of this course catalog in the course catalog hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedCourseCatalogView

void useIsolatedCourseCatalogView()

Isolates the view for methods in this session. An isolated view restricts retrievals to this course catalog only.

Compliance:

mandatory - This method is must be implemented.

useEffectiveDocetView

void useEffectiveDocetView()

Only docets whose effective dates are current are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveDocetView

void useAnyEffectiveDocetView()

All docets of any effective dates are returned by all methods in this session.

Compliance:

mandatory - This method is must be implemented.

getDocet

Docet getDocet(Id docetId)
               throws NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

Gets the Docet specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Docet may have a different Id than requested, such as the case where a duplicate Id was assigned to an Docet and retained for compatibility. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

docetId - Id of the Docet

Returns:

the docet

Throws:

NotFoundException - docetId not found

NullArgumentException - docetId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getDocetsByIds

DocetList getDocetsByIds(IdList docetIds)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Gets an DocetList corresponding to the given IdList. In plenary mode, the returned list contains all of the docetsspecified 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 Docets may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

docetIds - the list of Ids to retrieve

Returns:

the returned Docet list

Throws:

NotFoundException - an Id was not found

NullArgumentException - docetIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsByGenusType

DocetList getDocetsByGenusType(Type docetGenusType)
                               throws OperationFailedException,
                                      PermissionDeniedException

Gets an DocetList corresponding to the given docet genus Type which does not include docetsof genus types derived from the specified Type. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

docetGenusType - a docet genus type

Returns:

the returned Docet list

Throws:

NullArgumentException - docetGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsByParentGenusType

DocetList getDocetsByParentGenusType(Type docetGenusType)
                                     throws OperationFailedException,
                                            PermissionDeniedException

Gets an DocetList corresponding to the given docet genus Type and include any additional docetswith genus types derived from the specified Type. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

docetGenusType - a docet genus type

Returns:

the returned Docet list

Throws:

NullArgumentException - docetGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsByRecordType

DocetList getDocetsByRecordType(Type docetRecordType)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets an DocetList containing the given docet record Type. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

docetRecordType - a docet record type

Returns:

the returned Docet list

Throws:

NullArgumentException - docetRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsOnDate

DocetList getDocetsOnDate(DateTime from,
                        DateTime to)
                          throws OperationFailedException,
                                 PermissionDeniedException

Gets an DocetList effective sduring the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

from - s atsrting date

to - an ending date

Returns:

the returned Docet 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.

getDocetsForModule

DocetList getDocetsForModule(Id moduleId)
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets an DocetList for the given module Id. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

moduleId - a module Id

Returns:

the returned Docet list

Throws:

NullArgumentException - moduleId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsForModuleOnDate

DocetList getDocetsForModuleOnDate(Id moduleId,
                                 DateTime from,
                                 DateTime to)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets an DocetList for a module effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

moduleId - a module Id

from - s atsrting date

to - an ending date

Returns:

the returned Docet list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - moduleId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsForActivityUnit

DocetList getDocetsForActivityUnit(Id activityUnitId)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets an DocetList for the given activity unit Id. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

activityUnitId - an activity unit Id

Returns:

the returned Docet list

Throws:

NullArgumentException - activityUnitId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsForActivityUnitOnDate

DocetList getDocetsForActivityUnitOnDate(Id activityUnitId,
                                       DateTime from,
                                       DateTime to)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets an DocetList for an activity unit effective sduring the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

activityUnitId - an activity unit Id

from - s atsrting date

to - an ending date

Returns:

the returned Docet list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - activityUnitId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsForModuleAndActivityUnit

DocetList getDocetsForModuleAndActivityUnit(Id moduleId,
                                          Id activityUnitId)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Gets an DocetList for the given module and activity unit . In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

moduleId - a module Id

activityUnitId - an activity unit Id

Returns:

the returned Docet list

Throws:

NullArgumentException - moduleId or activityUnitId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocetsForModuleAndActivityUnitOnDate

DocetList getDocetsForModuleAndActivityUnitOnDate(Id moduleId,
                                                Id activityUnitId,
                                                DateTime from,
                                                DateTime to)
                                                  throws OperationFailedException,
                                                         PermissionDeniedException

Gets an DocetList for a module and activity unit effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Parameters:

moduleId - a module Id

activityUnitId - an activity unit Id

from - s atsrting date

to - an ending date

Returns:

the returned Docet list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - moduleId, activityUnitId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDocets

DocetList getDocets()
                    throws OperationFailedException,
                           PermissionDeniedException

Gets all Docets. In plenary mode, the returned list contains all known docetsor an error results. Otherwise, the returned list may contain only those docets that are accessible through this session. In effective mode, docets are returned that are currently effective. In any effective mode, effective docets and those currently expired are returned.

Returns:

a list of Docets

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.