org.osid.commenting

Interface BookNotificationSession

All Superinterfaces:

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

public interface BookNotificationSession
extends OsidSession

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

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeBookNotification(Id notificationId) Acknowledge a book notification.
boolean	canRegisterForBookNotifications() Tests if this user can register for Book notifications.
void	registerForChangedBook(Id bookId) Registers for notification of an updated book.
void	registerForChangedBookHierarchy() Registers for notification of an updated book hierarchy structure.
void	registerForChangedBookHierarchyForAncestors(Id bookId) Registers for notification of an updated book hierarchy structure.
void	registerForChangedBookHierarchyForDescendants(Id bookId) Registers for notification of an updated book hierarchy structure.
void	registerForChangedBooks() Registers for notification of updated books.
void	registerForDeletedBook(Id bookId) Registers for notification of a deleted book.
void	registerForDeletedBooks() Registers for notification of deleted books.
void	registerForNewBooks() Register for notifications of new books.
void	reliableBookNotifications() Reliable notifications are desired.
void	unreliableBookNotifications() 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

canRegisterForBookNotifications

boolean canRegisterForBookNotifications()

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

reliableBookNotifications

void reliableBookNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableBookNotifications

void unreliableBookNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeBookNotification

void acknowledgeBookNotification(Id notificationId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Acknowledge a book notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewBooks

void registerForNewBooks()
                         throws OperationFailedException,
                                PermissionDeniedException

Register for notifications of new books. BookReceiver.newBooks() is invoked when a new Book is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedBooks

void registerForChangedBooks()
                             throws OperationFailedException,
                                    PermissionDeniedException

Registers for notification of updated books. BookReceiver.changedBooks() is invoked when a book is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedBook

void registerForChangedBook(Id bookId)
                            throws OperationFailedException,
                                   PermissionDeniedException

Registers for notification of an updated book. BookReceiver.changedBooks() is invoked when the specified book is changed.

Parameters:

bookId - the Id of the Book to monitor

Throws:

NullArgumentException - bookId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedBooks

void registerForDeletedBooks()
                             throws OperationFailedException,
                                    PermissionDeniedException

Registers for notification of deleted books. BookReceiver.deletedBooks() is invoked when a book is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedBook

void registerForDeletedBook(Id bookId)
                            throws OperationFailedException,
                                   PermissionDeniedException

Registers for notification of a deleted book. BookReceiver.deletedBooks() is invoked when the specified book is deleted.

Parameters:

bookId - the Id of the Book to monitor

Throws:

NullArgumentException - bookId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedBookHierarchy

void registerForChangedBookHierarchy()
                                     throws OperationFailedException,
                                            PermissionDeniedException

Registers for notification of an updated book hierarchy structure. BookReceiver.changedChildOfBookss() 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.

registerForChangedBookHierarchyForAncestors

void registerForChangedBookHierarchyForAncestors(Id bookId)
                                                 throws OperationFailedException,
                                                        PermissionDeniedException

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

Parameters:

bookId - the Id of the Book node to monitor

Throws:

NullArgumentException - bookId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedBookHierarchyForDescendants

void registerForChangedBookHierarchyForDescendants(Id bookId)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

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

Parameters:

bookId - the Id of the Book node to monitor

Throws:

NullArgumentException - bookId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.