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:
Relationships may have an additional records indicated by their
respective record types. The record may not be accessed through a cast of
the Relationship.
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. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getFamilyId()
Family
Id
associated with this
session. Family Id
associated with this sessionmandatory
- This method must be implemented. Family getFamily() throws OperationFailedException, PermissionDeniedException
Family
associated with this session.OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canLookupRelationships()
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. false
if lookup methods are not authorized,
true
otherwisemandatory
- This method must be implemented. void useComparativeRelationshipView()
mandatory
- This method is must be implemented. void usePlenaryRelationshipView()
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.mandatory
- This method is must be implemented. void useFederatedFamilyView()
mandatory
- This method is must be implemented. void useIsolatedFamilyView()
mandatory
- This method is must be implemented. void useEffectiveRelationshipView()
mandatory
- This method is must be implemented. void useAnyEffectiveRelationshipView()
mandatory
- This method is must be implemented. Relationship getRelationship(Id relationshipId) throws NotFoundException, OperationFailedException, PermissionDeniedException
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.relationshipId
- the Id
of the
Relationship
to retrieve Relationship
NotFoundException
- no Relationship
found with the given Id
NullArgumentException
- relationshipId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByIds(IdList relationshipIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
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.relationshipIds
- the list of Ids
to retrieve Relationship list
NotFoundException
- an Id
was not foundNullArgumentException
- relationshipIds
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByGenusType(Type relationshipGenusType) throws OperationFailedException, PermissionDeniedException
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.relationshipGenusType
- a relationship genus type Relationship list
NullArgumentException
- relationshipGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByParentGenusType(Type relationshipGenusType) throws OperationFailedException, PermissionDeniedException
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.relationshipGenusType
- a relationship genus type Relationship list
NullArgumentException
- relationshipGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByRecordType(Type relationshipRecordType) throws OperationFailedException, PermissionDeniedException
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.relationshipRecordType
- a relationship record type RelationshipList
NullArgumentException
- relationshipRecordType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsOnDate(DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.from
- starting dateto
- ending dateInvalidArgumentException
- from is greater than
to
NullArgumentException
- from
or
to
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsForSource(Id sourceId) throws OperationFailedException, PermissionDeniedException
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.sourceId
- a peer Id
NullArgumentException
- sourceId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsForSourceOnDate(Id sourceId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.sourceId
- a peer Id
from
- starting dateto
- ending dateInvalidArgumentException
- from is greater than
to
NullArgumentException
- sourceId, from
,or to
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByGenusTypeForSource(Id sourceId, Type relationshipGenusType) throws OperationFailedException, PermissionDeniedException
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.sourceId
- a peer Id
relationshipGenusType
- a relationship genus typeNullArgumentException
- sourceId
or
relationshipGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByGenusTypeForSourceOnDate(Id sourceId, Type relationshipGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.sourceId
- a peer Id
relationshipGenusType
- a relationship genus typefrom
- starting dateto
- ending dateInvalidArgumentException
- from is greater than
to
NullArgumentException
- sourceId,
relationshipGenusType, from
or to
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsForDestination(Id destinationId) throws OperationFailedException, PermissionDeniedException
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.destinationId
- a peer Id
NullArgumentException
- destinationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsForDestinationOnDate(Id destinationId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.destinationId
- a peer Id
from
- starting dateto
- ending dateInvalidArgumentException
- from is greater than
to
NullArgumentException
- destinationId, from
,or to
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByGenusTypeForDestination(Id destinationId, Type relationshipGenusType) throws OperationFailedException, PermissionDeniedException
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.destinationId
- a peer Id
relationshipGenusType
- a relationship genus typeNullArgumentException
- destinationId
or
relationshipGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByGenusTypeForDestinationOnDate(Id destinationId, Type relationshipGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.destinationId
- a peer Id
relationshipGenusType
- a relationship genus typefrom
- starting dateto
- ending dateInvalidArgumentException
- from is greater than
to
NullArgumentException
- destinationId,
relationshipGenusType, from
or to
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsForPeers(Id sourceId, Id destinationId) throws OperationFailedException, PermissionDeniedException
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.sourceId
- a peer Id
destinationId
- a related peer Id
NullArgumentException
- sourceId
or
destinationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsForPeersOnDate(Id sourceId, Id destinationId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.sourceId
- a peer Id
destinationId
- a related peer Id
from
- starting dateto
- ending dateInvalidArgumentException
- from
is
greater than to
NullArgumentException
- sourceId, destinationId,
from
or to
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByGenusTypeForPeers(Id sourceId, Id destinationId, Type relationshipGenusType) throws OperationFailedException, PermissionDeniedException
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.sourceId
- a peer Id
destinationId
- a related peer Id
relationshipGenusType
- a relationship genus typeNullArgumentException
- sourceId, destinationId,
or relationshipGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationshipsByGenusTypeForPeersOnDate(Id sourceId, Id destinationId, Type relationshipGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.sourceId
- a peer Id
destinationId
- a related peer Id
relationshipGenusType
- a relationship genus typefrom
- starting dateto
- ending dateInvalidArgumentException
- from is greater than
to
NullArgumentException
- sourceId, destinationId,
relationshipGenusType, from
or to
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RelationshipList getRelationships() throws OperationFailedException, PermissionDeniedException
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. Relationships
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.