org.osid.relationship

Interface RelationshipLookupSession

All Superinterfaces:

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

public interface RelationshipLookupSession
extends OsidSession

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 Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupRelationships() Tests if this user can perform Relationship lookups.
Family	getFamily() Gets the Family associated with this session.
Id	getFamilyId() Gets the Family Id associated with this session.
Relationship	getRelationship(Id relationshipId) Gets the Relationship specified by its Id.
RelationshipList	getRelationships() Gets all Relationships.
RelationshipList	getRelationshipsByGenusType(Type relationshipGenusType) Gets a RelationshipList corresponding to the given relationship genus Type which does not include relationships of types derived from the specified Type.
RelationshipList	getRelationshipsByGenusTypeForDestination(Id destinationId, Type relationshipGenusType) Gets a RelationshipList corresponding to the given peer Id and relationship genus Type.
RelationshipList	getRelationshipsByGenusTypeForDestinationOnDate(Id destinationId, Type relationshipGenusType, DateTime from, DateTime to) 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.
RelationshipList	getRelationshipsByGenusTypeForPeers(Id sourceId, Id destinationId, Type relationshipGenusType) Gets a RelationshipList corresponding between the given peer Ids and relationship genus Type.
RelationshipList	getRelationshipsByGenusTypeForPeersOnDate(Id sourceId, Id destinationId, Type relationshipGenusType, DateTime from, DateTime to) Gets a RelationshipList effective during the entire given date range inclusive but not confined to the date range.
RelationshipList	getRelationshipsByGenusTypeForSource(Id sourceId, Type relationshipGenusType) Gets a RelationshipList corresponding to the given peer Id and relationship genus Type.
RelationshipList	getRelationshipsByGenusTypeForSourceOnDate(Id sourceId, Type relationshipGenusType, DateTime from, DateTime to) 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.
RelationshipList	getRelationshipsByIds(IdList relationshipIds) Gets a RelationshipList corresponding to the given IdList.
RelationshipList	getRelationshipsByParentGenusType(Type relationshipGenusType) Gets a RelationshipList corresponding to the given relationship genus Type and include any additional relationships with genus types derived from the specified Type.
RelationshipList	getRelationshipsByRecordType(Type relationshipRecordType) Gets a RelationshipList containing the given relationship record Type.
RelationshipList	getRelationshipsForDestination(Id destinationId) Gets a RelationshipList corresponding to the given peer Id.
RelationshipList	getRelationshipsForDestinationOnDate(Id destinationId, DateTime from, DateTime to) Gets a RelationshipList corresponding to the given peer Id with a starting effective date in the given range inclusive.
RelationshipList	getRelationshipsForPeers(Id sourceId, Id destinationId) Gets a RelationshipList corresponding to the given peer Ids.
RelationshipList	getRelationshipsForPeersOnDate(Id sourceId, Id destinationId, DateTime from, DateTime to) 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.
RelationshipList	getRelationshipsForSource(Id sourceId) Gets a RelationshipList corresponding to the given peer Id.
RelationshipList	getRelationshipsForSourceOnDate(Id sourceId, DateTime from, DateTime to) 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.
RelationshipList	getRelationshipsOnDate(DateTime from, DateTime to) Gets a RelationshipList effective during the entire given date range inclusive but not confined to the date range.
void	useAnyEffectiveRelationshipView() All relationships of any effective dates are returned by all methods in this session.
void	useComparativeRelationshipView() 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	useEffectiveRelationshipView() Only relationships whose effective dates are current are returned by methods in this session.
void	useFederatedFamilyView() Federates the view for methods in this session.
void	useIsolatedFamilyView() Isolates the view for methods in this session.
void	usePlenaryRelationshipView() A complete view of the Relationship 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

getFamilyId

Id getFamilyId()

Gets the Family Id associated with this session.

Returns:

the Family Id associated with this session

Compliance:

mandatory - This method must be implemented.

getFamily

Family getFamily()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the Family associated with this session.

Returns:

the family

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupRelationships

boolean canLookupRelationships()

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.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeRelationshipView

void useComparativeRelationshipView()

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.

usePlenaryRelationshipView

void usePlenaryRelationshipView()

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.

useFederatedFamilyView

void useFederatedFamilyView()

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.

useIsolatedFamilyView

void useIsolatedFamilyView()

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.

useEffectiveRelationshipView

void useEffectiveRelationshipView()

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

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveRelationshipView

void useAnyEffectiveRelationshipView()

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

Compliance:

mandatory - This method is must be implemented.

getRelationship

Relationship getRelationship(Id relationshipId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

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:

relationshipId - the Id of the Relationship to retrieve

Returns:

the returned Relationship

Throws:

NotFoundException - no Relationship found with the given Id

NullArgumentException - relationshipId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByIds

RelationshipList getRelationshipsByIds(IdList relationshipIds)
                                       throws NotFoundException,
                                              OperationFailedException,
                                              PermissionDeniedException

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:

relationshipIds - the list of Ids to retrieve

Returns:

the returned Relationship list

Throws:

NotFoundException - an Id was not found

NullArgumentException - relationshipIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByGenusType

RelationshipList getRelationshipsByGenusType(Type relationshipGenusType)
                                             throws OperationFailedException,
                                                    PermissionDeniedException

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:

relationshipGenusType - a relationship genus type

Returns:

the returned Relationship list

Throws:

NullArgumentException - relationshipGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByParentGenusType

RelationshipList getRelationshipsByParentGenusType(Type relationshipGenusType)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

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:

relationshipGenusType - a relationship genus type

Returns:

the returned Relationship list

Throws:

NullArgumentException - relationshipGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByRecordType

RelationshipList getRelationshipsByRecordType(Type relationshipRecordType)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

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:

relationshipRecordType - a relationship record type

Returns:

the returned RelationshipList

Throws:

NullArgumentException - relationshipRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsOnDate

RelationshipList getRelationshipsOnDate(DateTime from,
                                      DateTime to)
                                        throws OperationFailedException,
                                               PermissionDeniedException

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:

from - starting date

to - ending date

Returns:

the relationships

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.

getRelationshipsForSource

RelationshipList getRelationshipsForSource(Id sourceId)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

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:

sourceId - a peer Id

Returns:

the relationships

Throws:

NullArgumentException - sourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsForSourceOnDate

RelationshipList getRelationshipsForSourceOnDate(Id sourceId,
                                               DateTime from,
                                               DateTime to)
                                                 throws OperationFailedException,
                                                        PermissionDeniedException

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:

sourceId - a peer Id

from - starting date

to - ending date

Returns:

the relationships

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - sourceId, from ,or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByGenusTypeForSource

RelationshipList getRelationshipsByGenusTypeForSource(Id sourceId,
                                                    Type relationshipGenusType)
                                                      throws OperationFailedException,
                                                             PermissionDeniedException

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:

sourceId - a peer Id

relationshipGenusType - a relationship genus type

Returns:

the relationships

Throws:

NullArgumentException - sourceId or relationshipGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByGenusTypeForSourceOnDate

RelationshipList getRelationshipsByGenusTypeForSourceOnDate(Id sourceId,
                                                          Type relationshipGenusType,
                                                          DateTime from,
                                                          DateTime to)
                                                            throws OperationFailedException,
                                                                   PermissionDeniedException

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:

sourceId - a peer Id

relationshipGenusType - a relationship genus type

from - starting date

to - ending date

Returns:

the relationships

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - sourceId, relationshipGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsForDestination

RelationshipList getRelationshipsForDestination(Id destinationId)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

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:

destinationId - a peer Id

Returns:

the relationships

Throws:

NullArgumentException - destinationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsForDestinationOnDate

RelationshipList getRelationshipsForDestinationOnDate(Id destinationId,
                                                    DateTime from,
                                                    DateTime to)
                                                      throws OperationFailedException,
                                                             PermissionDeniedException

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:

destinationId - a peer Id

from - starting date

to - ending date

Returns:

the relationships

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - destinationId, from ,or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByGenusTypeForDestination

RelationshipList getRelationshipsByGenusTypeForDestination(Id destinationId,
                                                         Type relationshipGenusType)
                                                           throws OperationFailedException,
                                                                  PermissionDeniedException

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:

destinationId - a peer Id

relationshipGenusType - a relationship genus type

Returns:

the relationships

Throws:

NullArgumentException - destinationId or relationshipGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByGenusTypeForDestinationOnDate

RelationshipList getRelationshipsByGenusTypeForDestinationOnDate(Id destinationId,
                                                               Type relationshipGenusType,
                                                               DateTime from,
                                                               DateTime to)
                                                                 throws OperationFailedException,
                                                                        PermissionDeniedException

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:

destinationId - a peer Id

relationshipGenusType - a relationship genus type

from - starting date

to - ending date

Returns:

the relationships

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - destinationId, relationshipGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsForPeers

RelationshipList getRelationshipsForPeers(Id sourceId,
                                        Id destinationId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

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:

sourceId - a peer Id

destinationId - a related peer Id

Returns:

the relationships

Throws:

NullArgumentException - sourceId or destinationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsForPeersOnDate

RelationshipList getRelationshipsForPeersOnDate(Id sourceId,
                                              Id destinationId,
                                              DateTime from,
                                              DateTime to)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

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:

sourceId - a peer Id

destinationId - a related peer Id

from - starting date

to - ending date

Returns:

the relationships

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - sourceId, destinationId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByGenusTypeForPeers

RelationshipList getRelationshipsByGenusTypeForPeers(Id sourceId,
                                                   Id destinationId,
                                                   Type relationshipGenusType)
                                                     throws OperationFailedException,
                                                            PermissionDeniedException

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:

sourceId - a peer Id

destinationId - a related peer Id

relationshipGenusType - a relationship genus type

Returns:

the relationships

Throws:

NullArgumentException - sourceId, destinationId, or relationshipGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationshipsByGenusTypeForPeersOnDate

RelationshipList getRelationshipsByGenusTypeForPeersOnDate(Id sourceId,
                                                         Id destinationId,
                                                         Type relationshipGenusType,
                                                         DateTime from,
                                                         DateTime to)
                                                           throws OperationFailedException,
                                                                  PermissionDeniedException

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:

sourceId - a peer Id

destinationId - a related peer Id

relationshipGenusType - a relationship genus type

from - starting date

to - ending date

Returns:

the relationships

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - sourceId, destinationId, relationshipGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelationships

RelationshipList getRelationships()
                                  throws OperationFailedException,
                                         PermissionDeniedException

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.

Returns:

a list of Relationships

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.