Interface RelationshipLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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.