Interface RelationshipNotificationSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
public interface RelationshipNotificationSession extends OsidSession

This session defines methods to receive notifications on adds/changes to Relationship objects in this Family . This also includes existing relationships that may appear or disappear due to changes in the Family hierarchy, This session is intended for consumers needing to synchronize their state with this service without the use of polling. Notifications are cancelled when this session is closed.

The two views defined in this session correspond to the views in the RelationshipLookupSession .

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

    • canRegisterForRelationshipNotifications

      boolean canRegisterForRelationshipNotifications()
      Tests if this user can register for Relationship notifications. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer notification operations.
      Returns:
      false if notification methods are not authorized, true otherwise
      Compliance:
      mandatory - This method 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 notifications to this family only.
      Compliance:
      mandatory - This method is must be implemented.

    • reliableRelationshipNotifications

      void reliableRelationshipNotifications()
      Reliable notifications are desired. In reliable mode, notifications are to be acknowledged using acknowledgeRelationshipNotification() .
      Compliance:
      mandatory - This method is must be implemented.

    • unreliableRelationshipNotifications

      void unreliableRelationshipNotifications()
      Unreliable notifications are desired. In unreliable mode, notifications do not need to be acknowledged.
      Compliance:
      mandatory - This method is must be implemented.

    • acknowledgeRelationshipNotification

      void acknowledgeRelationshipNotification(Id notificationId) throws OperationFailedException, PermissionDeniedException
      Acknowledge a relationship notification.
      Parameters:
      notificationId - the Id of the notification
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForNewRelationships

      void registerForNewRelationships() throws OperationFailedException, PermissionDeniedException
      Register for notifications of new relationships. RelationshipReceiver.newRelationships() is invoked when a new Relationship appears in this family.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForNewRelationshipsForSource

      void registerForNewRelationshipsForSource(Id sourceId) throws OperationFailedException, PermissionDeniedException
      Register for notifications of new relationships from the given source. RelationshipReceiver.newRelationships() is invoked when a new Relationship appears for the given peer.
      Parameters:
      sourceId - the Id of the source to monitor
      Throws:
      NullArgumentException - sourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForNewRelationshipsForDestination

      void registerForNewRelationshipsForDestination(Id destinationId) throws OperationFailedException, PermissionDeniedException
      Register for notifications of new relationships to the given destination. RelationshipReceiver.newRelationships() is invoked when a new Relationship appears for the given peer.
      Parameters:
      destinationId - the Id of the destination node to monitor
      Throws:
      NullArgumentException - destinationId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForNewRelationshipsByGenusType

      void registerForNewRelationshipsByGenusType(Type relationshipGenusType) throws OperationFailedException, PermissionDeniedException
      Register for notifications of new relationships. RelationshipReceiver.newRelationships() is invoked when a new Relationship appears for the given peer.
      Parameters:
      relationshipGenusType - the genus type of the Relationship to monitor
      Throws:
      NullArgumentException - relationshipGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedRelationships

      void registerForChangedRelationships() throws OperationFailedException, PermissionDeniedException
      Registers for notification of updated relationships. RelationshipReceiver.changedRelationships() is invoked when a relationship in this family is changed.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedRelationshipsForSource

      void registerForChangedRelationshipsForSource(Id sourceId) throws OperationFailedException, PermissionDeniedException
      Register for notifications of updated relationships from the given source node. RelationshipReceiver.changedRelationships() is invoked when a Relationship if changed for the given peer.
      Parameters:
      sourceId - the Id of the source node to monitor
      Throws:
      NullArgumentException - sourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedRelationshipsForDestination

      void registerForChangedRelationshipsForDestination(Id destinationId) throws OperationFailedException, PermissionDeniedException
      Register for notifications of updated relationships to the given destination node. RelationshipReceiver.changedRelationships() is invoked when a Relationship if changed for the given peer.
      Parameters:
      destinationId - the Id of the destination node to monitor
      Throws:
      NullArgumentException - destinationId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedRelationshipsByGenusType

      void registerForChangedRelationshipsByGenusType(Type relationshipGenusType) throws OperationFailedException, PermissionDeniedException
      Register for notifications of updated relationships. RelationshipReceiver.changedRelationships() is invoked when a Relationship if changed for the given peer.
      Parameters:
      relationshipGenusType - the genus type of the Relationship to monitor
      Throws:
      NullArgumentException - relationshipGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedRelationship

      void registerForChangedRelationship(Id relationshipId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated relationship. RelationshipReceiver.changedRelationships() is invoked when the specified relationship in this family is changed.
      Parameters:
      relationshipId - the Id of the Relationship to monitor
      Throws:
      NullArgumentException - relationshipId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedRelationships

      void registerForDeletedRelationships() throws OperationFailedException, PermissionDeniedException
      Registers for notification of deleted relationships. RelationshipReceiver.deletedRelationships() is invoked when a relationship is deleted or removed from this family.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedRelationshipsForSource

      void registerForDeletedRelationshipsForSource(Id sourceId) throws OperationFailedException, PermissionDeniedException
      Register for notifications of deleted relationships from the given source node. RelationshipReceiver.deletedRelationships() is invoked when a Relationship if removed for the given peer.
      Parameters:
      sourceId - the Id of the source node to monitor
      Throws:
      NullArgumentException - sourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedRelationshipsForDestination

      void registerForDeletedRelationshipsForDestination(Id destinationId) throws OperationFailedException, PermissionDeniedException
      Register for notifications of deleted relationships to the given destination node. RelationshipReceiver.deletedRelationships() is invoked when a Relationship if removed for the given peer.
      Parameters:
      destinationId - the Id of the destination node to monitor
      Throws:
      NullArgumentException - destinationId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedRelationshipsByGenusType

      void registerForDeletedRelationshipsByGenusType(Type relationshipGenusType) throws OperationFailedException, PermissionDeniedException
      Register for notifications of deleted relationships. RelationshipReceiver.deletedRelationships() is invoked when a Relationship if removed for the given peer.
      Parameters:
      relationshipGenusType - the genus type of the Relationship to monitor
      Throws:
      NullArgumentException - relationshipGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedRelationship

      void registerForDeletedRelationship(Id relationshipId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of a deleted relationship. RelationshipReceiver.deletedRelationships() is invoked when the specified relationship is deleted or removed from this family.
      Parameters:
      relationshipId - the Id of the Relationship to monitor
      Throws:
      NullArgumentException - relationshipId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.