Interface HierarchyStructureNotificationSession

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

This session defines methods to receive notifications on adds/changes to a hierarchical structure. 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.

Notifications are triggered with changes to the structure of a hierarchy. For notifications of changes to the Hierarchy object use HierarchyNotificationSession .

  • Method Details

    • getHierarchyId

      Id getHierarchyId()
      Gets the hierarchy Id associated with this session.
      Returns:
      the hierarchy Id associated with this session
      Compliance:
      mandatory - This method must be implemented.

    • getHierarchy

      Hierarchy getHierarchy() throws OperationFailedException, PermissionDeniedException
      Gets the Hierarchy associated with this session.
      Returns:
      the Hierarchy associated with this session
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canRegisterForHierarchyStructureNotifications

      boolean canRegisterForHierarchyStructureNotifications()
      Tests if this user can register for Hierarchy node 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.

    • reliableHierarchyStructureNotifications

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

    • unreliableHierarchyStructureNotifications

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

    • acknowledgeHierarchyStructureNotification

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

    • registerForNewHierarchyNodes

      void registerForNewHierarchyNodes() throws OperationFailedException, PermissionDeniedException
      Register for notifications of new hierarchy nodes. HierarchyStructureReceiver.newNodes() is invoked when a new Hierarchy node is added.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedHierarchyNodes

      void registerForDeletedHierarchyNodes() throws OperationFailedException, PermissionDeniedException
      Registers for notification of deleted hierarchy nodes. HierarchyStructureReceiver.deletedNodes() is invoked when a hierarchy ndoe is deleted.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedHierarchyNode

      void registerForDeletedHierarchyNode(Id nodeId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of a deleted hierarchy node. HierarchyStructureReceiver.deletedNodes() is invoked when the specified hierarchy node is deleted.
      Parameters:
      nodeId - the Id of the Hierarchy node to monitor
      Throws:
      NullArgumentException - nodeId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedHierarchy

      void registerForChangedHierarchy() throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated hierarchy structure. HierarchyStructureReceiver.changedChildOfNodes() is invoked when a node experiences a change in its children.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedHierarchyForAncestors

      void registerForChangedHierarchyForAncestors(Id nodeId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated hierarchy structure. HierarchyStructureReceiver.changedChildOfNodes() is invoked when the specified node or any of its descendants experiences a change in its children.
      Parameters:
      nodeId - the Id of the node to monitor
      Throws:
      NullArgumentException - nodeId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedHierarchyForDescendants

      void registerForChangedHierarchyForDescendants(Id nodeId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated hierarchy structure. HierarchyStructureReceiver.changedChildOfNodes() is invoked when the specified node or any of its descendants experiences a change in its children.
      Parameters:
      nodeId - the Id of the node to monitor
      Throws:
      NullArgumentException - nodeId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.