org.osid.control

Interface SystemNotificationSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface SystemNotificationSession
extends OsidSession

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

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeSystemNotification(Id notificationId) Acknowledge a system notification.
boolean	canRegisterForSystemNotifications() Tests if this user can register for System notifications.
void	registerForChangedSystem(Id systemId) Registers for notification of an updated system.
void	registerForChangedSystemHierarchy() Registers for notification of an updated system hierarchy structure.
void	registerForChangedSystemHierarchyForAncestors(Id systemId) Registers for notification of an updated system hierarchy structure.
void	registerForChangedSystemHierarchyForDescendants(Id systemId) Registers for notification of an updated system hierarchy structure.
void	registerForChangedSystems() Registers for notification of updated systems.
void	registerForDeletedSystem(Id systemId) Registers for notification of a deleted system.
void	registerForDeletedSystems() Registers for notification of deleted systems.
void	registerForNewSystems() Register for notifications of new systems.
void	reliableSystemNotifications() Reliable notifications are desired.
void	unreliableSystemNotifications() Unreliable notifications are desired.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

canRegisterForSystemNotifications

boolean canRegisterForSystemNotifications()

Tests if this user can register for System 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.

reliableSystemNotifications

void reliableSystemNotifications()

Reliable notifications are desired. In reliable mode, notifications are to be acknowledged using acknowledgeSystemNotification() .

Compliance:

mandatory - This method is must be implemented.

unreliableSystemNotifications

void unreliableSystemNotifications()

Unreliable notifications are desired. In unreliable mode, notifications do not need to be acknowledged.

Compliance:

mandatory - This method is must be implemented.

acknowledgeSystemNotification

void acknowledgeSystemNotification(Id notificationId)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Acknowledge a system notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewSystems

void registerForNewSystems()
                           throws OperationFailedException,
                                  PermissionDeniedException

Register for notifications of new systems. SystemReceiver.newSystems() is invoked when a new System is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSystems

void registerForChangedSystems()
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of updated systems. SystemReceiver.changedSystems() is invoked when a system is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSystem

void registerForChangedSystem(Id systemId)
                              throws OperationFailedException,
                                     PermissionDeniedException

Registers for notification of an updated system. SystemReceiver.changedSystems() is invoked when the specified system is changed.

Parameters:

systemId - the Id of the System to monitor

Throws:

NullArgumentException - systemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedSystems

void registerForDeletedSystems()
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of deleted systems. SystemReceiver.deletedSystems() is invoked when a system is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedSystem

void registerForDeletedSystem(Id systemId)
                              throws OperationFailedException,
                                     PermissionDeniedException

Registers for notification of a deleted system. SystemReceiver.deletedSystems() is invoked when the specified system is deleted.

Parameters:

systemId - the Id of the System to monitor

Throws:

NullArgumentException - systemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSystemHierarchy

void registerForChangedSystemHierarchy()
                                       throws OperationFailedException,
                                              PermissionDeniedException

Registers for notification of an updated system hierarchy structure. SystemReceiver.changedChildOfSystems() 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.

registerForChangedSystemHierarchyForAncestors

void registerForChangedSystemHierarchyForAncestors(Id systemId)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

Registers for notification of an updated system hierarchy structure. SystemReceiver.changedChildOfSystems() is invoked when the specified node or any of its ancestors experiences a change in its children.

Parameters:

systemId - the Id of the System node to monitor

Throws:

NullArgumentException - systemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedSystemHierarchyForDescendants

void registerForChangedSystemHierarchyForDescendants(Id systemId)
                                                     throws OperationFailedException,
                                                            PermissionDeniedException

Registers for notification of an updated system hierarchy structure. SystemReceiver.changedChildOfSystems() is invoked when the specified node or any of its descendants experiences a change in its children.

Parameters:

systemId - the Id of the System node to monitor

Throws:

NullArgumentException - systemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.