OSID - osid.ontology.RelevancyLookupSession Service Interface Definition

Interface	osid.ontology.RelevancyLookupSession
Implements	`osid.OsidSession`
Description	This session provides methods for examining subject relevancy. 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 relevancy methods in this session operate, retrieve and pertain to relevancies defined explicitly in the current ontology. Using an isolated view is useful for managing relevancies with the `RelevancyAdminSession.` federated ontology view: All relevancy methods in this session operate, retrieve and pertain to all relevancies defined in this ontology and any other obtologies implicitly available in this ontology through ontology inheritence. effective relevancy view: All relevancy methods return effective relevancies. any effective relevancy view: Both effective and ineffective relevancies are returned.
Method	getOntologyId
Description	Gets the `Ontology` `Id` associated with this session.
Return	`osid.id.Id`		the `Ontology Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getOntology
Description	Gets the `Ontology` associated with this session.
Return	`osid.ontology.Ontology`		the `Ontology` associated with this session
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canLookupRelevancies
Description	Tests if this user can lookup subject relevancies. 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.
Return	`boolean`		`false` if lookup methods are not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	useComparativeRelevancyView
Description	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.
Method	usePlenaryRelevancyView
Description	A complete view of the `Relevancy` 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.
Method	useFederatedOntologyView
Description	Federates the view for methods in this session. A federated view will include relevancies in ontologies which are children of this ontology in the ontology hierarchy.
Compliance	`mandatory`		This method is must be implemented.
Method	useIsolatedOntologyView
Description	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.
Method	useEffectiveRelevancyView
Description	The returns from the lookup methods return only effetive relevancies.
Compliance	`mandatory`		This method is must be implemented.
Method	useAnyEffectiveRelevancyView
Description	Both effective and ineffective relavcnies are returned.
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevancy
Description	Gets the `Relevancy` specified by its `Id.` In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Relevancy` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Relevancy` and retained for compatibility. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`relevancyId`	`Id` of the `Relevancy`
Return	`osid.ontology.Relevancy`		the relevancy
Errors	NOT_FOUND		`relevancyId` not found
	NULL_ARGUMENT		`relevancyId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesByIds
Description	Gets a `RelevancyList` corresponding to the given `IdList.` In plenary mode, the returned list contains all of the relevancies 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 relevancies may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.IdList`	`relevancyIds`	the list of `Ids` to retrieve
Return	`osid.ontology.RelevancyList`		the returned `Relevancy list`
Errors	NOT_FOUND		an `Id was` not found
	NULL_ARGUMENT		`relevancyIds` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesByGenusType
Description	Gets the relevancies for the given relevancy and genus type. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`relevancyGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesByParentGenusType
Description	Gets the relevancies for the given relevancy genus type and include any relevancies with a genus type derived from the specified genus type. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`relevancyGenusTYpe` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesByRecordType
Description	Gets a `RelevancyList` containing the given relevancy record `Type.` In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.type.Type`	`relevancyRecordType`	a relevancy record type
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`relevancyRecordType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesOnDate
Description	Gets a `RelevancyList` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.calendaring.DateTime`	`from`	a starting date
Parameters	`osid.calendaring.DateTime`	`to`	an ending date
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`from` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesByGenusTypeOnDate
Description	Gets a `RelevancyList` of the given genus type and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
	`osid.calendaring.DateTime`	`from`	a starting date
	`osid.calendaring.DateTime`	`to`	an ending date
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`relevancyGenusType, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesForSubject
Description	Gets the `Relevancy` mapped to a subject `Id.` In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Relevancy` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Relevancy` and retained for compatibility. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`subjectId`	the subject `Id`
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`subjectId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesForSubjectOnDate
Description	Gets a `RelevancyList` for the given subject effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`subjectId`	the subject `Id`
	`osid.calendaring.DateTime`	`from`	a starting date
	`osid.calendaring.DateTime`	`to`	an ending date
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`subjectId, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesByGenusTypeForSubject
Description	Gets the `Relevancy` mapped to a subject `Id` and relevancy `genus Type.` Genus `Types` derived from the given genus `Typ` e are included. In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Relevancy` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Relevancy` and retained for compatibility. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`subjectId`	the subject `Id`
Parameters	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`subjectId` or `relevancyGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesByGenusTypeForSubjectOnDate
Description	Gets a `RelevancyList` of the given genus type for the given subject effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`subjectId`	the subject `Id`
	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
	`osid.calendaring.DateTime`	`from`	a starting date
	`osid.calendaring.DateTime`	`to`	an ending date
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`subjectId, relevancyGenusType, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesForSubjects
Description	Gets the relevancies for the given subject `Ids.` In plenary mode, the returned list contains all of the relevancies specified in the subject `Id` list, in the order of the list, including duplicates, or an error results if a relevancy `Id` in the supplied list is not found or inaccessible. Otherwise, inaccessible relevancies may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.IdList`	`subjectIds`	list of subject `Ids`
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`subjectIds` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesForMappedId
Description	Gets the `Relevancy` elements mapped to an `Id.` In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Relevancy` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Relevancy` and retained for compatibility. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`id`	an `Id`
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`id` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesForMappedIdOnDate
Description	Gets a `RelevancyList` for the given mapped `Id` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`id`	an `Id`
	`osid.calendaring.DateTime`	`from`	a starting date
	`osid.calendaring.DateTime`	`to`	an ending date
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`id, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesByGenusTypeForMappedId
Description	Gets the `Relevancy` elements mapped to an `Id` of the given relevancy genus `Type` which includes derived genus `Types.` In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Relevancy` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Relevancy` and retained for compatibility. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`id`	an `Id`
Parameters	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`id` or `relevancyGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesByGenusTypeForMappedIdOnDate
Description	Gets a `RelevancyList` of the given genus type for the given mapped `Id` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`id`	an `Id`
	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
	`osid.calendaring.DateTime`	`from`	a starting date
	`osid.calendaring.DateTime`	`to`	an ending date
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`id, relevancyGenusType, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesForMappedIds
Description	Gets the relevancies for the given mapped `Ids.` In plenary mode, the returned list contains all of the relevancies mapped to the `Id` or an error results if an `Id` in the supplied list is not found or inaccessible. Otherwise, inaccessible relevancies may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.IdList`	`ids`	a list of `Ids`
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`ids` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesForSubjectAndMappedId
Description	Gets the `Relevancy` mapped to a subject and mapped `Id.` In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Relevancy` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Relevancy` and retained for compatibility. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`subjectId`	the subject `Id`
Parameters	`osid.id.Id`	`id`	the mapped `Id`
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`subjectId` or `id` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesForSubjectAndMappedIdOnDate
Description	Gets a `RelevancyList` for the given subject and mapped `Id` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`subjectId`	the subject `Id`
	`osid.id.Id`	`id`	the mapped `Id`
	`osid.calendaring.DateTime`	`from`	a starting date
	`osid.calendaring.DateTime`	`to`	an ending date
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`subjectId, id, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevanciesByGenusTypeForSubjectAndMappedId
Description	Gets the `Relevancy` of the given genus type and mapped to a subject and mapped `Id.` In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Relevancy` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Relevancy` and retained for compatibility. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`subjectId`	the subject `Id`
	`osid.id.Id`	`id`	the mapped `Id`
	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	NULL_ARGUMENT		`subjectId, id` , or `relevancyGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.
Method	getRelevanciesByGenusTypeForSubjectAndMappedIdOnDate
Description	Gets a `RelevancyList` of the given genus type and related to the given subject and mapped `Id` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Parameters	`osid.id.Id`	`subjectId`	the subject `Id`
	`osid.id.Id`	`id`	the mapped `Id`
	`osid.type.Type`	`relevancyGenusType`	relevancy genus type
	`osid.calendaring.DateTime`	`from`	a starting date
	`osid.calendaring.DateTime`	`to`	an ending date
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`subjectId, id, relevancyGenusTYpe, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelevancies
Description	Gets all relevancies. In plenary mode, the returned list contains all known relevancies or an error results. Otherwise, the returned list may contain only those relevancies that are accessible through this session. In effective mode, relevancies are returned that are currently effective. In any effective mode, effective relevancies and those currently expired are returned.
Return	`osid.ontology.RelevancyList`		list of relevancies
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method is must be implemented.