org.osid.course.program

Interface ProgramLookupSession

All Superinterfaces:

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

public interface ProgramLookupSession
extends OsidSession

This session defines methods for retrieving programs. A P rogram is canonical and a ProgramOffering is derived from a Program.

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 course catalog view: All program methods in this session operate, retrieve and pertain to programs defined explicitly in the current course catalog. Using an isolated view is useful for managing Programs with the Program AdminSession.
• federated course catalog view: All program lookup methods in this session operate, retrieve and pertain to all programs defined in this course catalog and any other programs implicitly available in this course catalog through course catalog inheritence.
• active program view: All program lookup methods return active programs.
• any status program view: Programs of any active or inactive status are returned from methods.

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

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupPrograms() Tests if this user can perform Program lookups.
CourseCatalog	getCourseCatalog() Gets the CourseCatalog associated with this session.
Id	getCourseCatalogId() Gets the CourseCatalog Id associated with this session.
Program	getProgram(Id programId) Gets the Program specified by its Id.
ProgramList	getPrograms() Gets all Programs.
ProgramList	getProgramsByCredential(Id credentialId) Gets a ProgramList containing the given creential.
ProgramList	getProgramsByGenusType(Type programGenusType) Gets a ProgramList corresponding to the given program genus Type which does not include programs of types derived from the specified Type.
ProgramList	getProgramsByIds(IdList programIds) Gets a ProgramList corresponding to the given IdList.
ProgramList	getProgramsByParentGenusType(Type programGenusType) Gets a ProgramList corresponding to the given program genus Type and include any additional programs with genus types derived from the specified Type.
ProgramList	getProgramsByRecordType(Type programRecordType) Gets a ProgramList containing the given program record Type.
void	useActiveProgramView() Only active programs are returned by methods in this session.
void	useAnyStatusProgramView() All programs of any active or inactive status are returned by methods in this session.
void	useComparativeProgramView() 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	useFederatedCourseCatalogView() Federates the view for methods in this session.
void	useIsolatedCourseCatalogView() Isolates the view for methods in this session.
void	usePlenaryProgramView() A complete view of the Program 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.

canLookupPrograms

boolean canLookupPrograms()

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

useComparativeProgramView

void useComparativeProgramView()

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.

usePlenaryProgramView

void usePlenaryProgramView()

A complete view of the Program 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 programs in catalogs which are children of this 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.

useActiveProgramView

void useActiveProgramView()

Only active programs are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyStatusProgramView

void useAnyStatusProgramView()

All programs of any active or inactive status are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

getProgram

Program getProgram(Id programId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Gets the Program specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned program may have a different Id than requested, such as the case where a duplicate Id was assigned to a program and retained for compatibility. In active mode, active programs are returned. In any status mode, active and inactive programs are returned.

Parameters:

programId - the Id of the Program to retrieve

Returns:

the returned Program

Throws:

NotFoundException - no program found with the given Id

NullArgumentException - programId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProgramsByIds

ProgramList getProgramsByIds(IdList programIds)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets a ProgramList corresponding to the given IdList. In plenary mode, the returned list contains all of the programs 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 Programs may be omitted from the list and may present the elements in any order including returning a unique set. In active mode, active programs are returned. In any status mode, active and inactive programs are returned.

Parameters:

programIds - the list of Ids to retrieve

Returns:

the returned ProgramList list

Throws:

NotFoundException - an Id was not found

NullArgumentException - programIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProgramsByGenusType

ProgramList getProgramsByGenusType(Type programGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets a ProgramList corresponding to the given program genus Type which does not include programs of types derived from the specified Type. In plenary mode, the returned list contains all known programs or an error results. Otherwise, the returned list may contain only those programs that are accessible through this session. In active mode, active programs are returned. In any status mode, active and inactive programs are returned.

Parameters:

programGenusType - a program genus type

Returns:

the returned ProgramList list

Throws:

NullArgumentException - programGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProgramsByParentGenusType

ProgramList getProgramsByParentGenusType(Type programGenusType)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets a ProgramList corresponding to the given program genus Type and include any additional programs with genus types derived from the specified Type. In plenary mode, the returned list contains all known programs or an error results. Otherwise, the returned list may contain only those programs that are accessible through this session. In active mode, active programs are returned. In any status mode, active and inactive programs are returned.

Parameters:

programGenusType - a program genus type

Returns:

the returned ProgramList list

Throws:

NullArgumentException - programGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProgramsByRecordType

ProgramList getProgramsByRecordType(Type programRecordType)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a ProgramList containing the given program record Type. In plenary mode, the returned list contains all known programs or an error results. Otherwise, the returned list may contain only those programs that are accessible through this session. In active mode, active programs are returned. In any status mode, active and inactive programs are returned.

Parameters:

programRecordType - a program record type

Returns:

the returned ProgramList list

Throws:

NullArgumentException - programRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProgramsByCredential

ProgramList getProgramsByCredential(Id credentialId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a ProgramList containing the given creential. In plenary mode, the returned list contains all known programs or an error results. Otherwise, the returned list may contain only those programs that are accessible through this session. In active mode, active programs are returned. In any status mode, active and inactive programs are returned.

Parameters:

credentialId - a credential Id

Returns:

the returned ProgramList list

Throws:

NullArgumentException - credentialId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPrograms

ProgramList getPrograms()
                        throws OperationFailedException,
                               PermissionDeniedException

Gets all Programs. In plenary mode, the returned list contains all known programs or an error results. Otherwise, the returned list may contain only those programs that are accessible through this session. In active mode, active programs are returned. In any status mode, active and inactive programs are returned.

Returns:

a list of Programs

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.