org.osid.subscription

Interface PublisherNotificationSession

All Superinterfaces:

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

public interface PublisherNotificationSession
extends OsidSession

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

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgePublisherNotification(Id notificationId) Acknowledge a publisher notification.
boolean	canRegisterForPublisherNotifications() Tests if this user can register for Publisher notifications.
void	registerForChangedPublisher(Id publisherId) Registers for notification of an updated publisher.
void	registerForChangedPublisherHierarchy() Registers for notification of an updated publisher hierarchy structure.
void	registerForChangedPublisherHierarchyForAncestors(Id publisherId) Registers for notification of an updated publisher hierarchy structure.
void	registerForChangedPublisherHierarchyForDescendants(Id publisherId) Registers for notification of an updated publisher hierarchy structure.
void	registerForChangedPublishers() Registers for notification of updated publishers.
void	registerForDeletedPublisher(Id publisherId) Registers for notification of a deleted publisher.
void	registerForDeletedPublishers() Registers for notification of deleted publishers.
void	registerForNewPublishers() Register for notifications of new publishers.
void	reliablePublisherNotifications() Reliable notifications are desired.
void	unreliablePublisherNotifications() 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

canRegisterForPublisherNotifications

boolean canRegisterForPublisherNotifications()

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

reliablePublisherNotifications

void reliablePublisherNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliablePublisherNotifications

void unreliablePublisherNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgePublisherNotification

void acknowledgePublisherNotification(Id notificationId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Acknowledge a publisher notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewPublishers

void registerForNewPublishers()
                              throws OperationFailedException,
                                     PermissionDeniedException

Register for notifications of new publishers. PublisherReceiver.newPublishers() is invoked when a new Publisher is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPublishers

void registerForChangedPublishers()
                                  throws OperationFailedException,
                                         PermissionDeniedException

Registers for notification of updated publishers. PublisherReceiver.changedPublishers() is invoked when a publisher is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPublisher

void registerForChangedPublisher(Id publisherId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Registers for notification of an updated publisher. PublisherReceiver.changedPublishers() is invoked when the specified publisher is changed.

Parameters:

publisherId - the Id of the Publisher to monitor

Throws:

NullArgumentException - publisherId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedPublishers

void registerForDeletedPublishers()
                                  throws OperationFailedException,
                                         PermissionDeniedException

Registers for notification of deleted publishers. PublisherReceiver.deletedPublishers() is invoked when a publisher is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedPublisher

void registerForDeletedPublisher(Id publisherId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Registers for notification of a deleted publisher. PublisherReceiver.deletedPublishers() is invoked when the specified publisher is deleted.

Parameters:

publisherId - the Id of the Publisher to monitor

Throws:

NullArgumentException - publisherId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPublisherHierarchy

void registerForChangedPublisherHierarchy()
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Registers for notification of an updated publisher hierarchy structure. PublishergReceiver.changedChildOfPublishers() 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.

registerForChangedPublisherHierarchyForAncestors

void registerForChangedPublisherHierarchyForAncestors(Id publisherId)
                                                      throws OperationFailedException,
                                                             PermissionDeniedException

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

Parameters:

publisherId - the Id of the Publisher node to monitor

Throws:

NullArgumentException - publisherId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPublisherHierarchyForDescendants

void registerForChangedPublisherHierarchyForDescendants(Id publisherId)
                                                        throws OperationFailedException,
                                                               PermissionDeniedException

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

Parameters:

publisherId - the Id of the Publisher node to monitor

Throws:

NullArgumentException - publisherId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.