Interface KeyNotificationSession

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

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

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

  • Method Details

    • getAgencyId

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

    • getAgency

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

    • canRegisterForKeyNotifications

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

    • useFederatedAgencyView

      void useFederatedAgencyView()
      Federates the view for methods in this session. A federated view will include keys in agencies which are children of this agency in the agency hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedAgencyView

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

    • reliableKeyNotifications

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

    • unreliableKeyNotifications

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

    • acknowledgeKeyNotification

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

    • registerForNewKeys

      void registerForNewKeys() throws OperationFailedException, PermissionDeniedException
      Register for notifications of new keys. KeyReceiver.newKeys() is invoked when a new Key is created.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedKeys

      void registerForChangedKeys() throws OperationFailedException, PermissionDeniedException
      Registers for notification of updated keys. KeyReceiver.changedKeys() is invoked when a key is changed.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedKey

      void registerForChangedKey(Id keyId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated key. KeyReceiver.changedKeys() is invoked when the specified key is changed.
      Parameters:
      keyId - the Id of the Key to monitor
      Throws:
      NullArgumentException - keyId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedKeys

      void registerForDeletedKeys() throws OperationFailedException, PermissionDeniedException
      Registers for notification of deleted keys. KeyReceiver.deletedKeys() is invoked when a key is removed from this agency.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedKey

      void registerForDeletedKey(Id keyId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of a deleted key. KeyReceiver.deletedKeys() is invoked when the specified key is removed from this agency.
      Parameters:
      keyId - the Id of the Key to monitor
      Throws:
      NullArgumentException - keyId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.