org.osid.hierarchy

Interface HierarchyNotificationSession

All Superinterfaces:

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

public interface HierarchyNotificationSession
extends OsidSession

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canRegisterForHierarchyNotifications() Tests if this user can register for Hierarchy notifications.
void	registerForChangedHierarchies() Registers for notification of updated hierarchies.
void	registerForChangedHierarchy(Id hierarchyId) Registers for notification of an updated hierarchy.
void	registerForDeletedHierarchies() Registers for notification of deleted hierarchies.
void	registerForDeletedHierarchy(Id hierarchyId) Registers for notification of a deleted hierarchy.
void	registerForNewHierarchies() Register for notifications of new hierarchies.

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

canRegisterForHierarchyNotifications

boolean canRegisterForHierarchyNotifications()

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

registerForNewHierarchies

void registerForNewHierarchies()
                               throws OperationFailedException,
                                      PermissionDeniedException

Register for notifications of new hierarchies. HierarchyReceiver.newHierarchy() is invoked when a new Hierarchy is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedHierarchies

void registerForChangedHierarchies()
                                   throws OperationFailedException,
                                          PermissionDeniedException

Registers for notification of updated hierarchies. HierarchyReceiver.changedHierarchy() is invoked when a hierarchy is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedHierarchy

void registerForChangedHierarchy(Id hierarchyId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Registers for notification of an updated hierarchy. HierarchyReceiver.changedHierarchy() is invoked when the specified hierarchy is changed.

Parameters:

hierarchyId - the Id of the hierarchy to monitor

Throws:

NullArgumentException - hierarchyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedHierarchies

void registerForDeletedHierarchies()
                                   throws OperationFailedException,
                                          PermissionDeniedException

Registers for notification of deleted hierarchies. HierarchyReceiver.deletedHierarchy() is invoked when a hierarchy is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedHierarchy

void registerForDeletedHierarchy(Id hierarchyId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Registers for notification of a deleted hierarchy. HierarchyReceiver.deletedHierarchy() is invoked when the specified hierarchy is deleted.

Parameters:

hierarchyId - the Id of the Hierarchy to monitor

Throws:

NullArgumentException - hierarchyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.