org.osid.topology.path

Interface PathNotificationSession

All Superinterfaces:

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

public interface PathNotificationSession
extends OsidSession

This session defines methods to receive notifications on adds/changes to Path objects in this Graph. This also includes existing paths that may appear or disappear due to changes in the Graph hierarchy, 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.

The two views defined in this session correspond to the views in the PathLookupSession.

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgePathNotification(Id notificationId) Acknowledge a path notification.
boolean	canRegisterForPathNotifications() Tests if this user can register for Path notifications.
Graph	getGraph() Gets the Graph associated with this session.
Id	getGraphId() Gets the Graph Id associated with this session.
void	registerForChangedPath(Id pathId) Registers for notification of an updated path.
void	registerForChangedPaths() Registers for notification of updated paths.
void	registerForChangedPathsByGenusType(Type pathGenusType) Registers for notification of updated paths of the given genus type.
void	registerForChangedPathsForEndingNode(Id nodeId) Registers for notification of updated paths to the given node.
void	registerForChangedPathsForStartingNode(Id nodeId) Registers for notification of updated paths from the given node.
void	registerForDeletedPath(Id pathId) Registers for notification of a deleted path.
void	registerForDeletedPaths() Registers for notification of deleted paths.
void	registerForDeletedPathsByGenusType(Type pathGenusType) Registers for notification of deleted paths of the given genus type.
void	registerForDeletedPathsForEndingNode(Id nodeId) Register for notifications of removed paths to the given node.
void	registerForDeletedPathsForStartingNode(Id nodeId) Register for notifications of removed paths from the given node.
void	registerForNewPaths() Register for notifications of new paths.
void	registerForNewPathsByGenusType(Type pathGenusType) Register for notifications of new paths of the given genus type.
void	registerForNewPathsForEndingNode(Id nodeId) Register for notifications of new paths to the given node.
void	registerForNewPathsForStartingNode(Id nodeId) Register for notifications of new paths from the given node.
void	reliablePathNotifications() Reliable notifications are desired.
void	unreliablePathNotifications() Unreliable notifications are desired.
void	useFederatedGraphView() Federates the view for methods in this session.
void	useIsolatedGraphView() Isolates the view for methods in this session.

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

getGraphId

Id getGraphId()

Gets the Graph Id associated with this session.

Returns:

the Graph Id associated with this session

Compliance:

mandatory - This method must be implemented.

getGraph

Graph getGraph()
               throws OperationFailedException,
                      PermissionDeniedException

Gets the Graph associated with this session.

Returns:

the graph

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canRegisterForPathNotifications

boolean canRegisterForPathNotifications()

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

useFederatedGraphView

void useFederatedGraphView()

Federates the view for methods in this session. A federated view will include paths in graphs which are children of this graph in the graph hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedGraphView

void useIsolatedGraphView()

Isolates the view for methods in this session. An isolated view restricts notifications to this graph only.

Compliance:

mandatory - This method is must be implemented.

reliablePathNotifications

void reliablePathNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliablePathNotifications

void unreliablePathNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgePathNotification

void acknowledgePathNotification(Id notificationId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Acknowledge a path notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewPaths

void registerForNewPaths()
                         throws OperationFailedException,
                                PermissionDeniedException

Register for notifications of new paths. PathReceiver.newPaths() is invoked when a new Path appears in this graph.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewPathsByGenusType

void registerForNewPathsByGenusType(Type pathGenusType)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Register for notifications of new paths of the given genus type. PathReceiver.newPaths() is invoked when a new Path is connected to the specified location.

Parameters:

pathGenusType - a path genus type

Throws:

NullArgumentException - pathGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewPathsForStartingNode

void registerForNewPathsForStartingNode(Id nodeId)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Register for notifications of new paths from the given node. PathReceiver.newPaths() is invoked when a new Path is connected to the specified location.

Parameters:

nodeId - the Id of the Node to monitor

Throws:

NullArgumentException - nodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewPathsForEndingNode

void registerForNewPathsForEndingNode(Id nodeId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Register for notifications of new paths to the given node. PathReceiver.newPaths() is invoked when a new Path is connected to the specified location.

Parameters:

nodeId - the Id of the Node to monitor

Throws:

NullArgumentException - nodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPaths

void registerForChangedPaths()
                             throws OperationFailedException,
                                    PermissionDeniedException

Registers for notification of updated paths. PathReceiver.changedPaths() is invoked when a path in this graph is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPathsByGenusType

void registerForChangedPathsByGenusType(Type pathGenusType)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Registers for notification of updated paths of the given genus type. PathReceiver.changedPaths() is invoked when a path in this graph is changed.

Parameters:

pathGenusType - a path genus type

Throws:

NullArgumentException - pathGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPathsForStartingNode

void registerForChangedPathsForStartingNode(Id nodeId)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Registers for notification of updated paths from the given node. PathReceiver.changedPaths() is invoked when a path in this graph is changed.

Parameters:

nodeId - the Id of the Node to monitor

Throws:

NullArgumentException - nodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPathsForEndingNode

void registerForChangedPathsForEndingNode(Id nodeId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Registers for notification of updated paths to the given node. PathReceiver.changedPaths() is invoked when a path in this graph is changed.

Parameters:

nodeId - the Id of the Node to monitor

Throws:

NullArgumentException - nodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedPath

void registerForChangedPath(Id pathId)
                            throws OperationFailedException,
                                   PermissionDeniedException

Registers for notification of an updated path. PathReceiver.changedPaths() is invoked when the specified path in this graph is changed.

Parameters:

pathId - the Id of the Path to monitor

Throws:

NullArgumentException - pathId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedPaths

void registerForDeletedPaths()
                             throws OperationFailedException,
                                    PermissionDeniedException

Registers for notification of deleted paths. PathReceiver.deletedPaths() is invoked when a path is deleted or removed from this graph.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedPathsByGenusType

void registerForDeletedPathsByGenusType(Type pathGenusType)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Registers for notification of deleted paths of the given genus type. PathReceiver.deletedPatsh() is invoked when a path is deleted or removed from this graph.

Parameters:

pathGenusType - a path genus type

Throws:

NullArgumentException - pathGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedPathsForStartingNode

void registerForDeletedPathsForStartingNode(Id nodeId)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Register for notifications of removed paths from the given node. PathReceiver.deletedPaths() is invoked when a new Path is removed from the specified location.

Parameters:

nodeId - the Id of the Node to monitor

Throws:

NullArgumentException - nodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedPathsForEndingNode

void registerForDeletedPathsForEndingNode(Id nodeId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Register for notifications of removed paths to the given node. PathReceiver.deletedPaths() is invoked when a new Path is removed from the specified location.

Parameters:

nodeId - the Id of the Node to monitor

Throws:

NullArgumentException - nodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedPath

void registerForDeletedPath(Id pathId)
                            throws OperationFailedException,
                                   PermissionDeniedException

Registers for notification of a deleted path. PathReceiver.deletedPaths() is invoked when the specified path is deleted or removed from this graph.

Parameters:

pathId - the Id of the Path to monitor

Throws:

NullArgumentException - pathId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.