org.osid.logging

Interface LogNotificationSession

All Superinterfaces:

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

public interface LogNotificationSession
extends OsidSession

This session defines methods to receive notifications on adds/changes to Log 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 Log object itself. Adding and removing entries result in notifications available from the notification session for log entries.

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeLogNotification(Id notificationId) Acknowledge a log notification.
boolean	canRegisterForLogNotifications() Tests if this user can register for Log notifications.
void	registerForChangedLog(Id logId) Registers for notification of an updated log.
void	registerForChangedLogHierarchy() Registers for notification of an updated log hierarchy structure.
void	registerForChangedLogHierarchyForAncestors(Id logId) Log Receiver.changedChildOfLogs() is invoked when the specified node or any of its ancestors experiences a change in its children.
void	registerForChangedLogHierarchyForDescendants(Id logId) Registers for notification of an updated log hierarchy structure.
void	registerForChangedLogs() Registers for notification of updated logs.
void	registerForDeletedLog(Id logId) Registers for notification of a deleted log.
void	registerForDeletedLogs() Registers for notification of deleted logs.
void	registerForNewLogs() Register for notifications of new logs.
void	reliableLogNotifications() Reliable notifications are desired.
void	unreliableLogNotifications() 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

canRegisterForLogNotifications

boolean canRegisterForLogNotifications()

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

reliableLogNotifications

void reliableLogNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableLogNotifications

void unreliableLogNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeLogNotification

void acknowledgeLogNotification(Id notificationId)
                                throws OperationFailedException,
                                       PermissionDeniedException

Acknowledge a log notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewLogs

void registerForNewLogs()
                        throws OperationFailedException,
                               PermissionDeniedException

Register for notifications of new logs. LogReceiver.newLogs() is invoked when a new Log is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedLogs

void registerForChangedLogs()
                            throws OperationFailedException,
                                   PermissionDeniedException

Registers for notification of updated logs. LogReceiver.changedLogs() is invoked when a log is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedLog

void registerForChangedLog(Id logId)
                           throws OperationFailedException,
                                  PermissionDeniedException

Registers for notification of an updated log. LogReceiver.changedLogs() is invoked when the specified log is changed.

Parameters:

logId - the Id of the Log to monitor

Throws:

NullArgumentException - logId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedLogs

void registerForDeletedLogs()
                            throws OperationFailedException,
                                   PermissionDeniedException

Registers for notification of deleted logs. LogReceiver.deletedLogs() is invoked when a log is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedLog

void registerForDeletedLog(Id logId)
                           throws OperationFailedException,
                                  PermissionDeniedException

Registers for notification of a deleted log. LogReceiver.deletedLogs() is invoked when the specified log is deleted.

Parameters:

logId - the Id of the Log to monitor

Throws:

NullArgumentException - logId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedLogHierarchy

void registerForChangedLogHierarchy()
                                    throws OperationFailedException,
                                           PermissionDeniedException

Registers for notification of an updated log hierarchy structure. LogReceiver.changedChildOfLogs() 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.

registerForChangedLogHierarchyForAncestors

void registerForChangedLogHierarchyForAncestors(Id logId)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

Log Receiver.changedChildOfLogs() is invoked when the specified node or any of its ancestors experiences a change in its children.

Parameters:

logId - the Id of the Log node to monitor

Throws:

NullArgumentException - logId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedLogHierarchyForDescendants

void registerForChangedLogHierarchyForDescendants(Id logId)
                                                  throws OperationFailedException,
                                                         PermissionDeniedException

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

Parameters:

logId - the Id of the Log node to monitor

Throws:

NullArgumentException - logId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.