org.osid.ontology

Interface SubjectLookupSession

All Superinterfaces:

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

public interface SubjectLookupSession
extends OsidSession

This session provides methods for retrieving Subject s.

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 set or is an error condition
• isolated ontology view: All subject methods in this session operate, retrieve and pertain to subjects defined explicitly in the current ontology. Using an isolated view is useful for managing subjects with the SubjectAdminSession.
• federated ontology view: All subject methods in this session operate, retrieve and pertain to all subjects defined in this ontology and any other ontologies implicitly available in this ontology through ontology inheritence.

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupSubjects() Tests if this user can perform Subject lookups.
Ontology	getOntology() Gets the Ontology associated with this session.
Id	getOntologyId() Gets the Ontology Id associated with this session.
Subject	getSubject(Id subjectId) Gets the Subject specified by its Id.
SubjectList	getSubjects() Gets all Subjects.
SubjectList	getSubjectsByGenusType(Type subjectGenusType) Gets a SubjectList corresponding to the given subject genus Type which does not include subjects of genus types derived from the specified Type.
SubjectList	getSubjectsByIds(IdList subjectIds) Gets a SubjectList corresponding to the given IdList.
SubjectList	getSubjectsByParentGenusType(Type subjectGenusType) Gets a SubjectList corresponding to the given subject genus Type and include any additional subject with genus types derived from the specified Type.
SubjectList	getSubjectsByRecordType(Type subjectRecordType) Gets a SubjectList containing the given term record Type.
void	useComparativeSubjectView() 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	useFederatedOntologyView() Federates the view for methods in this session.
void	useIsolatedOntologyView() Isolates the view for methods in this session.
void	usePlenarySubjectView() A complete view of the Subject 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

getOntologyId

Id getOntologyId()

Gets the Ontology Id associated with this session.

Returns:

the Ontology Id associated with this session

Compliance:

mandatory - This method must be implemented.

getOntology

Ontology getOntology()
                     throws OperationFailedException,
                            PermissionDeniedException

Gets the Ontology associated with this session.

Returns:

the Ontology associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupSubjects

boolean canLookupSubjects()

Tests if this user can perform Subject 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 opt not to offer lookup operations to unauthorized users.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeSubjectView

void useComparativeSubjectView()

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.

usePlenarySubjectView

void usePlenarySubjectView()

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

useFederatedOntologyView

void useFederatedOntologyView()

Federates the view for methods in this session. A federated view will include subjects in ontologies which are children of this ontology in the ontology hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedOntologyView

void useIsolatedOntologyView()

Isolates the view for methods in this session. An isolated view restricts lookups to this ontology only.

Compliance:

mandatory - This method is must be implemented.

getSubject

Subject getSubject(Id subjectId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

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

Parameters:

subjectId - Id of the Subject

Returns:

the subject

Throws:

NotFoundException - subjectId not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getSubjectsByIds

SubjectList getSubjectsByIds(IdList subjectIds)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets a SubjectList corresponding to the given IdList. In plenary mode, the returned list contains all of the subjects 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 Subjects may be omitted from the list and may present the elements in any order including returning a unique set.

Parameters:

subjectIds - the list of Ids to retrieve

Returns:

the returned Subject list

Throws:

NotFoundException - an Id was not found

NullArgumentException - subjectIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getSubjectsByGenusType

SubjectList getSubjectsByGenusType(Type subjectGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets a SubjectList corresponding to the given subject genus Type which does not include subjects of genus types derived from the specified Type. In plenary mode, the returned list contains all known subjects or an error results. Otherwise, the returned list may contain only those subjects that are accessible through this session.

Parameters:

subjectGenusType - a subject genus type

Returns:

the returned Subject list

Throws:

NullArgumentException - subjectGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getSubjectsByParentGenusType

SubjectList getSubjectsByParentGenusType(Type subjectGenusType)
                                         throws OperationFailedException,
                                                PermissionDeniedException

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

Parameters:

subjectGenusType - a subject genus type

Returns:

the returned Subject list

Throws:

NullArgumentException - subjectGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getSubjectsByRecordType

SubjectList getSubjectsByRecordType(Type subjectRecordType)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a SubjectList containing the given term record Type. In plenary mode, the returned list contains all known subjects or an error results. Otherwise, the returned list may contain only those subjects that are accessible through this session.

Parameters:

subjectRecordType - a subject record type

Returns:

the returned Subject list

Throws:

NullArgumentException - subjectRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getSubjects

SubjectList getSubjects()
                        throws OperationFailedException,
                               PermissionDeniedException

Gets all Subjects. In plenary mode, the returned list contains all known subjects or an error results. Otherwise, the returned list may contain only those subjects that are accessible through this session.

Returns:

a SubjectList

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.