OSID - osid.relationship.RelationshipLookupSession Service Interface Definition

Interface	osid.relationship.RelationshipLookupSession
Implements	`osid.OsidSession`
Description	This session defines methods for retrieving relationships. A `Relationship` is mapped to two OSID `Ids.` 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 federated family view: includes relationships in families which are children of this family in the family hierarchy isolated family view: restricts lookups to this family only effective relationship view: Relationship methods return only relationships currently in effect. any effective relationship view: Relationship methods return both effective and ineffective relationships. Relationships may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the `Relationship.`
Method	getFamilyId
Description	Gets the `Family` `Id` associated with this session.
Return	`osid.id.Id`		the `Family Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getFamily
Description	Gets the `Family` associated with this session.
Return	`osid.relationship.Family`		the family
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canLookupRelationships
Description	Tests if this user can perform `Relationship` 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.
Return	`boolean`		`false` if lookup methods are not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	useComparativeRelationshipView
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	usePlenaryRelationshipView
Description	A complete view of the `Relationship` 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	useFederatedFamilyView
Description	Federates the view for methods in this session. A federated view will include relationships in families which are children of this family in the family hierarchy.
Compliance	`mandatory`		This method is must be implemented.
Method	useIsolatedFamilyView
Description	Isolates the view for methods in this session. An isolated view restricts retrievals to this family only.
Compliance	`mandatory`		This method is must be implemented.
Method	useEffectiveRelationshipView
Description	Only relationships whose effective dates are current are returned by methods in this session.
Compliance	`mandatory`		This method is must be implemented.
Method	useAnyEffectiveRelationshipView
Description	All relationships of any effective dates are returned by all methods in this session.
Compliance	`mandatory`		This method is must be implemented.
Method	getRelationship
Description	Gets the `Relationship` specified by its `Id.` In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Relationship` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Relationship` and retained for compatibility. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`relationshipId`	the `Id` of the `Relationship` to retrieve
Return	`osid.relationship.Relationship`		the returned `Relationship`
Errors	NOT_FOUND		no `Relationship` found with the given `Id`
	NULL_ARGUMENT		`relationshipId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByIds
Description	Gets a `RelationshipList` corresponding to the given `IdList.` In plenary mode, the returned list contains all of the relationships 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 `Relationships` may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.IdList`	`relationshipIds`	the list of `Ids` to retrieve
Return	`osid.relationship.RelationshipList`		the returned `Relationship list`
Errors	NOT_FOUND		an `Id` was not found
	NULL_ARGUMENT		`relationshipIds` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByGenusType
Description	Gets a `RelationshipList` corresponding to the given relationship genus `Type` which does not include relationships of types derived from the specified `Type.` In plenary mode, the returned list contains all known relationships or an error results. Otherwise, the returned list may contain only those relationships that are accessible through this session. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.type.Type`	`relationshipGenusType`	a relationship genus type
Return	`osid.relationship.RelationshipList`		the returned `Relationship list`
Errors	NULL_ARGUMENT		`relationshipGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByParentGenusType
Description	Gets a `RelationshipList` corresponding to the given relationship genus `Type` and include any additional relationships with genus types derived from the specified `Type.` In plenary mode, the returned list contains all known relationships or an error results. Otherwise, the returned list may contain only those relationships that are accessible through this session. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.type.Type`	`relationshipGenusType`	a relationship genus type
Return	`osid.relationship.RelationshipList`		the returned `Relationship list`
Errors	NULL_ARGUMENT		`relationshipGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByRecordType
Description	Gets a `RelationshipList` containing the given relationship record `Type.` In plenary mode, the returned list contains all known relationships or an error results. Otherwise, the returned list may contain only those relationships that are accessible through this session. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.type.Type`	`relationshipRecordType`	a relationship record type
Return	`osid.relationship.RelationshipList`		the returned `RelationshipList`
Errors	NULL_ARGUMENT		`relationshipRecordType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsOnDate
Description	Gets a `RelationshipList` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all of the relationships corresponding to date or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective in addition to being effective during the given dates. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.calendaring.DateTime`	`from`	starting date
Parameters	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.relationship.RelationshipList`		the relationships
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	getRelationshipsForSource
Description	Gets a `RelationshipList` corresponding to the given peer `Id.` In plenary mode, the returned list contains all of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`sourceId`	a peer `Id`
Return	`osid.relationship.RelationshipList`		the relationships
Errors	NULL_ARGUMENT		`sourceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsForSourceOnDate
Description	Gets a `RelationshipList` corresponding to the given peer `Id` and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective in addition to being effective during the given dates. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`sourceId`	a peer `Id`
	`osid.calendaring.DateTime`	`from`	starting date
	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.relationship.RelationshipList`		the relationships
Errors	INVALID_ARGUMENT		`from is greater than to`
	NULL_ARGUMENT		`sourceId, from` ,or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByGenusTypeForSource
Description	Gets a `RelationshipList` corresponding to the given peer `Id` and relationship genus `Type. Relationships` of any genus derived from the given genus are returned. In plenary mode, the returned list contains all of the relationships corresponding to the given peer, including duplicates, or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`sourceId`	a peer `Id`
Parameters	`osid.type.Type`	`relationshipGenusType`	a relationship genus type
Return	`osid.relationship.RelationshipList`		the relationships
Errors	NULL_ARGUMENT		`sourceId` or `relationshipGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByGenusTypeForSourceOnDate
Description	Gets a `RelationshipList` corresponding to the given peer `Id` and relationship 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 of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective in addition to being effective during the given dates. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`sourceId`	a peer `Id`
	`osid.type.Type`	`relationshipGenusType`	a relationship genus type
	`osid.calendaring.DateTime`	`from`	starting date
	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.relationship.RelationshipList`		the relationships
Errors	INVALID_ARGUMENT		`from is greater than to`
	NULL_ARGUMENT		`sourceId, relationshipGenusType, from` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsForDestination
Description	Gets a `RelationshipList` corresponding to the given peer `Id.` In plenary mode, the returned list contains all of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`destinationId`	a peer `Id`
Return	`osid.relationship.RelationshipList`		the relationships
Errors	NULL_ARGUMENT		`destinationId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsForDestinationOnDate
Description	Gets a `RelationshipList` corresponding to the given peer `Id` with a starting effective date in the given range inclusive. In plenary mode, the returned list contains all of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`destinationId`	a peer `Id`
	`osid.calendaring.DateTime`	`from`	starting date
	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.relationship.RelationshipList`		the relationships
Errors	INVALID_ARGUMENT		`from is greater than to`
	NULL_ARGUMENT		`destinationId, from` ,or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByGenusTypeForDestination
Description	Gets a `RelationshipList` corresponding to the given peer `Id` and relationship genus `Type. Relationships` of any genus derived from the given genus are returned. In plenary mode, the returned list contains all of the relationships corresponding to the given peer, including duplicates, or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`destinationId`	a peer `Id`
Parameters	`osid.type.Type`	`relationshipGenusType`	a relationship genus type
Return	`osid.relationship.RelationshipList`		the relationships
Errors	NULL_ARGUMENT		`destinationId` or `relationshipGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByGenusTypeForDestinationOnDate
Description	Gets a `RelationshipList` corresponding to the given peer `Id` and relationship 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 of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective in addition to being effective during the given dates. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`destinationId`	a peer `Id`
	`osid.type.Type`	`relationshipGenusType`	a relationship genus type
	`osid.calendaring.DateTime`	`from`	starting date
	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.relationship.RelationshipList`		the relationships
Errors	INVALID_ARGUMENT		`from is greater than to`
	NULL_ARGUMENT		`destinationId, relationshipGenusType, from` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsForPeers
Description	Gets a `RelationshipList` corresponding to the given peer `Ids.` In plenary mode, the returned list contains all of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`sourceId`	a peer `Id`
Parameters	`osid.id.Id`	`destinationId`	a related peer `Id`
Return	`osid.relationship.RelationshipList`		the relationships
Errors	NULL_ARGUMENT		`sourceId` or `destinationId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsForPeersOnDate
Description	Gets a `RelationshipList` corresponding to the given peer `Ids` and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all of the relationships corresponding to the given peer set or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective in addition to being effective during the given dates. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`sourceId`	a peer `Id`
	`osid.id.Id`	`destinationId`	a related peer `Id`
	`osid.calendaring.DateTime`	`from`	starting date
	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.relationship.RelationshipList`		the relationships
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`sourceId, destinationId, from` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByGenusTypeForPeers
Description	Gets a `RelationshipList` corresponding between the given peer `Ids` and relationship genus `Type. Relationships` of any genus derived from the given genus are returned. In plenary mode, the returned list contains all of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`sourceId`	a peer `Id`
	`osid.id.Id`	`destinationId`	a related peer `Id`
	`osid.type.Type`	`relationshipGenusType`	a relationship genus type
Return	`osid.relationship.RelationshipList`		the relationships
Errors	NULL_ARGUMENT		`sourceId, destinationId,` or `relationshipGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipsByGenusTypeForPeersOnDate
Description	Gets a `RelationshipList` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all of the relationships corresponding to the given peer set or an error results if a relationship is inaccessible. Otherwise, inaccessible `Relationships` may be omitted from the list. In effective mode, relationships are returned that are currently effective in addition to being effective during the given dates. In any effective mode, effective relationships and those currently expired are returned.
Parameters	`osid.id.Id`	`sourceId`	a peer `Id`
	`osid.id.Id`	`destinationId`	a related peer `Id`
	`osid.type.Type`	`relationshipGenusType`	a relationship genus type
	`osid.calendaring.DateTime`	`from`	starting date
	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.relationship.RelationshipList`		the relationships
Errors	INVALID_ARGUMENT		`from is greater than to`
	NULL_ARGUMENT		`sourceId, destinationId, relationshipGenusType, from` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getRelationships
Description	Gets all `Relationships.` In plenary mode, the returned list contains all known relationships or an error results. Otherwise, the returned list may contain only those relationships that are accessible through this session. In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.
Return	`osid.relationship.RelationshipList`		a list of `Relationships`
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.