Interface ValueNotificationSession

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

This session defines methods to receive notifications on changes to Values . A particular value in a set may have been added or deleted, but all changes appear as a change to a parameter. Once a change notification is received, the new value list can be obtained through the ValueLookupSession . This session is intended for adapters and providers needing to synchronize their state with this service without the use of polling. Notifications are cancelled when this session is closed.

Two views are defined;

  • federated: parameters defined in configurations that are a parent of this configuration in the configuration hierarchy are included for notifications
  • isolated: notifications are restricted to parameters are defined to within this configuration

The methods federateValuerView() and isolateValueView() behave as a radio group and one should be selected before invoking any lookup methods.

  • Method Details

    • getConfigurationId

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

    • getConfiguration

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

    • canRegisterForValueNotifications

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

    • useFederatedConfigurationView

      void useFederatedConfigurationView()
      Federates the view for methods in this session. A federated view will include parameters in configurations of which this configuration is a child in the configuration hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedConfigurationView

      void useIsolatedConfigurationView()
      Isolates the view for methods in this session. An isolated view restricts notifications for parameter values to this configuration only.
      Compliance:
      mandatory - This method is must be implemented.

    • reliableValueNotifications

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

    • unreliableValueNotifications

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

    • acknowledgeValueNotification

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

    • registerForNewValues

      void registerForNewValues() throws OperationFailedException, PermissionDeniedException
      Assigns a callback for notifications of new values. ValueReceiver.newValues() is invoked when a new Value is added to this configuration.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForNewValuesForParameter

      void registerForNewValuesForParameter(Id parameterId) throws OperationFailedException, PermissionDeniedException
      Assigns a callback for notifications of new values for the given parameter. ValueReceiver.newValues() is invoked when a new Value is added to this configuration.
      Parameters:
      parameterId - the Id of the Parameter to monitor
      Throws:
      NullArgumentException - parameterId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedValues

      void registerForChangedValues() throws OperationFailedException, PermissionDeniedException
      Assigns a callback for notification of updated parameter values in this configuration. ValueReceiver.changedValues() is invoked when a Value is changed in this configuration.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedValuesForParameter

      void registerForChangedValuesForParameter(Id parameterId) throws OperationFailedException, PermissionDeniedException
      Assigns a callback for notifications of changed values for the given parameter. ValueReceiver.changedValues() is invoked when a Value is updated to this configuration.
      Parameters:
      parameterId - the Id of the Parameter to monitor
      Throws:
      NullArgumentException - parameterId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedValue

      void registerForChangedValue(Id valueId) throws OperationFailedException, PermissionDeniedException
      Assigns a callback for notifications of an update to a value in this configuration. ValueReceiver.changedValues() is invoked when the specified Value is updated in this configuration.
      Parameters:
      valueId - the Id of the Value to monitor
      Throws:
      NullArgumentException - valueId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedValues

      void registerForDeletedValues() throws OperationFailedException, PermissionDeniedException
      Assigns a callback for notification of deleted values in this configuration. ValueReceiver.changedValues() is invoked when a Value is removed from this configuration.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedValuesForParameter

      void registerForDeletedValuesForParameter(Id parameterId) throws OperationFailedException, PermissionDeniedException
      Assigns a callback for notifications of changed values for the given parameter. ValueReceiver.changedValues() is invoked when a Value is removed from this configuration.
      Parameters:
      parameterId - the Id of the Parameter to monitor
      Throws:
      NullArgumentException - parameterId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedValue

      void registerForDeletedValue(Id valueId) throws OperationFailedException, PermissionDeniedException
      Assigns a callback for notifications of an update to a value in this configuration. ValueReceiver.changedValues() is invoked when the specified Value is removed from this configuration.
      Parameters:
      valueId - the Id of the Value to monitor
      Throws:
      NullArgumentException - valueId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.