Interface EntryNotificationSession

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

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

Like all OsidSessions, EntryNotificationSessions are dedicated to single processing threads and a single authenticated user.

  • Method Details

    • getDictionaryId

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

    • getDictionary

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

    • canRegisterForEntryNotifications

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

    • useFederatedDictionaryView

      void useFederatedDictionaryView()
      Federates the view for methods in this session. A federated view will include entries from parent dictionaries in the dictionary hierarchy.
      Compliance:
      mandatory - This method must be implemented.

    • useIsolatedDictionaryView

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

    • reliableEntryNotifications

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

    • unreliableEntryNotifications

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

    • acknowledgeEntryNotification

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

    • registerForNewEntries

      void registerForNewEntries() throws OperationFailedException, PermissionDeniedException
      Registers for notifications of new entries. EntryReceiver.newEntries() is invoked when a new Entry is created.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForNewEntriesByKeyTypeAndValueType

      void registerForNewEntriesByKeyTypeAndValueType(Type keyType, Type valueType) throws OperationFailedException, PermissionDeniedException
      Registers for notifications of new entries by key and value types. EntryReceiver.newEntries() is invoked when a new Entry is created.
      Parameters:
      keyType - the entry key type
      valueType - the entry key type
      Throws:
      NullArgumentException - keyType or valueType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedEntries

      void registerForChangedEntries() throws OperationFailedException, PermissionDeniedException
      Regsiters for notification of updated entries. EntryReceiver.changedEntries() is invoked when an Entry is changed.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedEntriesByKeyTypeAndValueType

      void registerForChangedEntriesByKeyTypeAndValueType(Type keyType, Type valueType) throws OperationFailedException, PermissionDeniedException
      Registers for notifications of an update to entries by key and value type. EntryReceiver.changedEntries() is invoked when the specified Entry is changed.
      Parameters:
      keyType - the entry key type
      valueType - the entry key type
      Throws:
      NullArgumentException - keyType or valueType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedEntry

      void registerForChangedEntry(Id entryId) throws OperationFailedException, PermissionDeniedException
      Registers for notifications of an update to an Entry. EntryReceiver.changedEntries() is invoked when the specified Entry is changed.
      Parameters:
      entryId - the entry Id
      Throws:
      NullArgumentException - entryId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedEntries

      void registerForDeletedEntries() throws OperationFailedException, PermissionDeniedException
      Registers for notification of deleted dictionaries. EntryReceiver.deletedEntries() is invoked when the specified Entry is deleted.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedEntriesByKeyTypeAndValueType

      void registerForDeletedEntriesByKeyTypeAndValueType(Type keyType, Type valueTYpe) throws OperationFailedException, PermissionDeniedException
      Registers for notifications of a deleted entries by key and value type. EntryReceiver.deletedEntries() is invoked when the specified Entry is removed from this dictionary.
      Parameters:
      keyType - the entry key type
      valueTYpe - the entry key type
      Throws:
      NullArgumentException - keyType or valueType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedEntry

      void registerForDeletedEntry(Id entryId) throws OperationFailedException, PermissionDeniedException
      Registers for notifications of a deleted Entry. EntryReceiver.deletedEntries() is invoked when the specified Entry is removed from this dictionary.
      Parameters:
      entryId - the entry Id
      Throws:
      NullArgumentException - entryId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.