Interface UtilityNotificationSession

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

This session defines methods to receive notifications on adds/changes to Utility objects. 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 Utility object itself. Adding and removing entries result in notifications available from the notification session for meters.

  • Method Details

    • canRegisterForUtilityNotifications

      boolean canRegisterForUtilityNotifications()
      Tests if this user can register for Utility 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.

    • registerForNewUtilities

      void registerForNewUtilities() throws OperationFailedException, PermissionDeniedException
      Register for notifications of new utilities. UtilityReceiver.newUtilities() is invoked when a new Utility is created.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForNewUtilityAncestors

      void registerForNewUtilityAncestors(Id utilityId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated hierarchy structure that introduces a new ancestor of the specified utility. UtilityReceiver.newAncestorUtility() is invoked when the specified utility node gets a new ancestor.
      Parameters:
      utilityId - the Id of the Utility node to monitor
      Throws:
      NullArgumentException - utilityId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForNewUtilityDescendants

      void registerForNewUtilityDescendants(Id utilityId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated hierarchy structure that introduces a new descendant of the specified utility. UtilityReceiver.newDescendantUtility() is invoked when the specified utility node gets a new descendant.
      Parameters:
      utilityId - the Id of the Utility node to monitor
      Throws:
      NullArgumentException - utilityId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedUtilities

      void registerForChangedUtilities() throws OperationFailedException, PermissionDeniedException
      Registers for notification of updated utilities. UtilityReceiver.changedUtilities() is invoked when a utility is changed.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedUtility

      void registerForChangedUtility(Id utilityId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated utility. UtilityReceiver.changedUtilities() is invoked when the specified utility is changed.
      Parameters:
      utilityId - the Id of the Utility to monitor
      Throws:
      NullArgumentException - utilityId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedUtilities

      void registerForDeletedUtilities() throws OperationFailedException, PermissionDeniedException
      Registers for notification of deleted utilities. UtilityReceiver.deletedUtilities() is invoked when a utility is deleted.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedUtility

      void registerForDeletedUtility(Id utilityId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of a deleted utility. UtilityReceiver.deletedUtilities() is invoked when the specified utility is deleted.
      Parameters:
      utilityId - the Id of the Utility to monitor
      Throws:
      NullArgumentException - utilityId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedUtilityAncestors

      void registerForDeletedUtilityAncestors(Id utilityId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated hierarchy structure that removes an ancestor of the specified utility. UtilityReceiver.deletedAncestor() is invoked when the specified utility node loses an ancestor.
      Parameters:
      utilityId - the Id of the Utility node to monitor
      Throws:
      NullArgumentException - utilityId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedUtilityDescendants

      void registerForDeletedUtilityDescendants(Id utilityId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated hierarchy structure that removes a descendant of the specified utility. UtilityReceiver.deletedDescendant() is invoked when the specified utility node loses a descendant.
      Parameters:
      utilityId - the Id of the Utility node to monitor
      Throws:
      NullArgumentException - utilityId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • acknowledgeUtilityNotification

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

    • registerForChangedUtilityHierarchy

      void registerForChangedUtilityHierarchy() throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated utility hierarchy structure. UtilityReceiver.changedChildOfUtilities() 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.

    • registerForChangedUtilityHierarchyForAncestors

      void registerForChangedUtilityHierarchyForAncestors(Id utilityId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated utility hierarchy structure. UtilityReceiver.changedChildOfUtilities() is invoked when a node experiences a change in its children.
      Parameters:
      utilityId - the Id of the Utility node to monitor
      Throws:
      NullArgumentException - utilityId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedUtilityHierarchyForDescendants

      void registerForChangedUtilityHierarchyForDescendants(Id utilityId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated utility hierarchy structure. UtilityReceiver.changedChildOfUtilities() is invoked when a node experiences a change in its children.
      Parameters:
      utilityId - the Id of the Utility node to monitor
      Throws:
      NullArgumentException - utilityId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.