org.osid.relationship

Interface RelationshipNotificationSession

All Superinterfaces:

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

public interface RelationshipNotificationSession
extends OsidSession

This session defines methods to receive notifications on adds/changes to Relationship objects in this Family. This also includes existing relationships that may appear or disappear due to changes in the Family 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 RelationshipLookupSession.

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeRelationshipNotification(Id notificationId) Acknowledge a relationship notification.
boolean	canRegisterForRelationshipNotifications() Tests if this user can register for Relationship notifications.
Family	getFamily() Gets the Family associated with this session.
Id	getFamilyId() Gets the Family Id associated with this session.
void	registerForChangedRelationship(Id relationshipId) Registers for notification of an updated relationship.
void	registerForChangedRelationships() Registers for notification of updated relationships.
void	registerForChangedRelationshipsByGenusType(Type relationshipGenusType) Register for notifications of updated relationships.
void	registerForChangedRelationshipsForDestination(Id destinationId) Register for notifications of updated relationships to the given destination node.
void	registerForChangedRelationshipsForSource(Id sourceId) Register for notifications of updated relationships from the given source node.
void	registerForDeletedRelationship(Id relationshipId) Registers for notification of a deleted relationship.
void	registerForDeletedRelationships() Registers for notification of deleted relationships.
void	registerForDeletedRelationshipsByGenusType(Type relationshipGenusType) Register for notifications of deleted relationships.
void	registerForDeletedRelationshipsForDestination(Id destinationId) Register for notifications of deleted relationships to the given destination node.
void	registerForDeletedRelationshipsForSource(Id sourceId) Register for notifications of deleted relationships from the given source node.
void	registerForNewRelationships() Register for notifications of new relationships.
void	registerForNewRelationshipsByGenusType(Type relationshipGenusType) Register for notifications of new relationships.
void	registerForNewRelationshipsForDestination(Id destinationId) Register for notifications of new relationships to the given destination.
void	registerForNewRelationshipsForSource(Id sourceId) Register for notifications of new relationships from the given source.
void	reliableRelationshipNotifications() Reliable notifications are desired.
void	unreliableRelationshipNotifications() Unreliable notifications are desired.
void	useFederatedFamilyView() Federates the view for methods in this session.
void	useIsolatedFamilyView() 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

getFamilyId

Id getFamilyId()

Gets the Family Id associated with this session.

Returns:

the Family Id associated with this session

Compliance:

mandatory - This method must be implemented.

getFamily

Family getFamily()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the Family associated with this session.

Returns:

the family

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canRegisterForRelationshipNotifications

boolean canRegisterForRelationshipNotifications()

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

useFederatedFamilyView

void useFederatedFamilyView()

Federates the view for methods in this session. A federated view will include relationships in families which are children of this family in the family hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedFamilyView

void useIsolatedFamilyView()

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

Compliance:

mandatory - This method is must be implemented.

reliableRelationshipNotifications

void reliableRelationshipNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableRelationshipNotifications

void unreliableRelationshipNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeRelationshipNotification

void acknowledgeRelationshipNotification(Id notificationId)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Acknowledge a relationship notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewRelationships

void registerForNewRelationships()
                                 throws OperationFailedException,
                                        PermissionDeniedException

Register for notifications of new relationships. RelationshipReceiver.newRelationships() is invoked when a new Relationship appears in this family.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewRelationshipsForSource

void registerForNewRelationshipsForSource(Id sourceId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Register for notifications of new relationships from the given source. RelationshipReceiver.newRelationships() is invoked when a new Relationship appears for the given peer.

Parameters:

sourceId - the Id of the source to monitor

Throws:

NullArgumentException - sourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewRelationshipsForDestination

void registerForNewRelationshipsForDestination(Id destinationId)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

Register for notifications of new relationships to the given destination. RelationshipReceiver.newRelationships() is invoked when a new Relationship appears for the given peer.

Parameters:

destinationId - the Id of the destination node to monitor

Throws:

NullArgumentException - destinationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewRelationshipsByGenusType

void registerForNewRelationshipsByGenusType(Type relationshipGenusType)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Register for notifications of new relationships. RelationshipReceiver.newRelationships() is invoked when a new Relationship appears for the given peer.

Parameters:

relationshipGenusType - the genus type of the Relationship to monitor

Throws:

NullArgumentException - relationshipGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedRelationships

void registerForChangedRelationships()
                                     throws OperationFailedException,
                                            PermissionDeniedException

Registers for notification of updated relationships. RelationshipReceiver.changedRelationships() is invoked when a relationship in this family is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedRelationshipsForSource

void registerForChangedRelationshipsForSource(Id sourceId)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Register for notifications of updated relationships from the given source node. RelationshipReceiver.changedRelationships() is invoked when a Relationship if changed for the given peer.

Parameters:

sourceId - the Id of the source node to monitor

Throws:

NullArgumentException - sourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedRelationshipsForDestination

void registerForChangedRelationshipsForDestination(Id destinationId)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

Register for notifications of updated relationships to the given destination node. RelationshipReceiver.changedRelationships() is invoked when a Relationship if changed for the given peer.

Parameters:

destinationId - the Id of the destination node to monitor

Throws:

NullArgumentException - destinationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedRelationshipsByGenusType

void registerForChangedRelationshipsByGenusType(Type relationshipGenusType)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

Register for notifications of updated relationships. RelationshipReceiver.changedRelationships() is invoked when a Relationship if changed for the given peer.

Parameters:

relationshipGenusType - the genus type of the Relationship to monitor

Throws:

NullArgumentException - relationshipGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedRelationship

void registerForChangedRelationship(Id relationshipId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Registers for notification of an updated relationship. RelationshipReceiver.changedRelationships() is invoked when the specified relationship in this family is changed.

Parameters:

relationshipId - the Id of the Relationship to monitor

Throws:

NullArgumentException - relationshipId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRelationships

void registerForDeletedRelationships()
                                     throws OperationFailedException,
                                            PermissionDeniedException

Registers for notification of deleted relationships. RelationshipReceiver.deletedRelationships() is invoked when a relationship is deleted or removed from this family.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRelationshipsForSource

void registerForDeletedRelationshipsForSource(Id sourceId)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Register for notifications of deleted relationships from the given source node. RelationshipReceiver.deletedRelationships() is invoked when a Relationship if removed for the given peer.

Parameters:

sourceId - the Id of the source node to monitor

Throws:

NullArgumentException - sourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRelationshipsForDestination

void registerForDeletedRelationshipsForDestination(Id destinationId)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

Register for notifications of deleted relationships to the given destination node. RelationshipReceiver.deletedRelationships() is invoked when a Relationship if removed for the given peer.

Parameters:

destinationId - the Id of the destination node to monitor

Throws:

NullArgumentException - destinationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRelationshipsByGenusType

void registerForDeletedRelationshipsByGenusType(Type relationshipGenusType)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

Register for notifications of deleted relationships. RelationshipReceiver.deletedRelationships() is invoked when a Relationship if removed for the given peer.

Parameters:

relationshipGenusType - the genus type of the Relationship to monitor

Throws:

NullArgumentException - relationshipGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRelationship

void registerForDeletedRelationship(Id relationshipId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Registers for notification of a deleted relationship. RelationshipReceiver.deletedRelationships() is invoked when the specified relationship is deleted or removed from this family.

Parameters:

relationshipId - the Id of the Relationship to monitor

Throws:

NullArgumentException - relationshipId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.