org.osid.search

Interface EngineNotificationSession

All Superinterfaces:

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

public interface EngineNotificationSession
extends OsidSession

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

Notifications are triggered with changes to the Engine object itself. Adding and removing search result in notifications available from the notification session for search.

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeEngineNotification(Id notificationId) Acknowledge an engine notification.
boolean	canRegisterForEngineNotifications() Tests if this user can register for Engine notifications.
void	registerForChangedEngine(Id engineId) Registers for notification of an updated engine.
void	registerForChangedEngineHierarchy() Registers for notification of an updated engine hierarchy structure.
void	registerForChangedEngineHierarchyForAncestors(Id engineId) Registers for notification of an updated engine hierarchy structure.
void	registerForChangedEngineHierarchyForDescendants(Id engineId) Registers for notification of an updated engine hierarchy structure.
void	registerForChangedEngines() Registers for notification of updated engines.
void	registerForDeletedEngine(Id engineId) Registers for notification of a deleted engine.
void	registerForDeletedEngines() Registers for notification of deleted engines.
void	registerForNewEngines() Register for notifications of new engines.
void	reliableEngineNotifications() Reliable notifications are desired.
void	unreliableEngineNotifications() 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

canRegisterForEngineNotifications

boolean canRegisterForEngineNotifications()

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

reliableEngineNotifications

void reliableEngineNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableEngineNotifications

void unreliableEngineNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeEngineNotification

void acknowledgeEngineNotification(Id notificationId)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Acknowledge an engine notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewEngines

void registerForNewEngines()
                           throws OperationFailedException,
                                  PermissionDeniedException

Register for notifications of new engines. EngineReceiver.newEngine() is invoked when a new Engine is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedEngines

void registerForChangedEngines()
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of updated engines. EngineReceiver.changedEngine() is invoked when an engine is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedEngine

void registerForChangedEngine(Id engineId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Registers for notification of an updated engine. EngineReceiver.changedEngine() is invoked when the specified engine is changed.

Parameters:

engineId - the Id of the Engine to monitor

Throws:

NotFoundException - an engine was not found identified by the given Id

NullArgumentException - engineId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedEngines

void registerForDeletedEngines()
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of deleted engines. EngineReceiver.deletedEngine() is invoked when an engine is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedEngine

void registerForDeletedEngine(Id engineId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Registers for notification of a deleted engine. EngineReceiver.deletedEngine() is invoked when the specified engine is deleted.

Parameters:

engineId - the Id of the Engine to monitor

Throws:

NotFoundException - an engine was not found identified by the given Id

NullArgumentException - engineId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedEngineHierarchy

void registerForChangedEngineHierarchy()
                                       throws OperationFailedException,
                                              PermissionDeniedException

Registers for notification of an updated engine hierarchy structure. EngineReceiver.changedChildOfEngines() 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.

registerForChangedEngineHierarchyForAncestors

void registerForChangedEngineHierarchyForAncestors(Id engineId)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

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

Parameters:

engineId - the Id of the Engine node to monitor

Throws:

NullArgumentException - engineId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedEngineHierarchyForDescendants

void registerForChangedEngineHierarchyForDescendants(Id engineId)
                                                     throws OperationFailedException,
                                                            PermissionDeniedException

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

Parameters:

engineId - the Id of the Engine node to monitor

Throws:

NullArgumentException - engineId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.