Interface AgentNotificationSession

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

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

  • 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.

    • canRegisterForAgentNotifications

      boolean canRegisterForAgentNotifications()
      Tests if this user can register for Agent 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 agents 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.

    • reliableAgentNotifications

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

    • unreliableAgentNotifications

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

    • acknowledgeAgentNotification

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

    • registerForNewAgents

      void registerForNewAgents() throws OperationFailedException, PermissionDeniedException
      Register for notifications of new agents. AgentReceiver.newAgents() is invoked when a new Agent is created.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedAgents

      void registerForChangedAgents() throws OperationFailedException, PermissionDeniedException
      Registers for notification of updated agents. AgentReceiver.changedAgents() is invoked when an agent is changed.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForChangedAgent

      void registerForChangedAgent(Id agentId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of an updated agent. AgentReceiver.changedAgents() is invoked when the specified agent is changed.
      Parameters:
      agentId - the Id of the Agent to monitor
      Throws:
      NullArgumentException - agentId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedAgents

      void registerForDeletedAgents() throws OperationFailedException, PermissionDeniedException
      Registers for notification of deleted agents. AgentReceiver.deletedAgents() is invoked when an agent is removed from this agency.
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • registerForDeletedAgent

      void registerForDeletedAgent(Id agentId) throws OperationFailedException, PermissionDeniedException
      Registers for notification of a deleted agent. AgentReceiver.deletedAgents() is invoked when the specified agent is removed from this agency.
      Parameters:
      agentId - the Id of the Agent to monitor
      Throws:
      NullArgumentException - agentId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.