org.osid.personnel

Interface RealmNotificationSession

All Superinterfaces:

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

public interface RealmNotificationSession
extends OsidSession

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canRegisterForRealmNotifications() Tests if this user can register for Realm notifications.
void	registerForChangedRealm(Id realmId) Registers for notification of an updated realm.
void	registerForChangedRealms() Registers for notification of updated realms.
void	registerForDeletedRealm(Id realmId) Registers for notification of a deleted realm.
void	registerForDeletedRealmAncestors(Id realmId) Registers for notification of an updated hierarchy structure that removes an ancestor of the specified realm.
void	registerForDeletedRealmDescendants(Id realmId) Registers for notification of an updated hierarchy structure that removes a descendant of the specified realm.
void	registerForDeletedRealms() Registers for notification of deleted realms.
void	registerForNewRealmAncestors(Id realmId) Registers for notification of an updated hierarchy structure that introduces a new ancestor of the specified realm.
void	registerForNewRealmDescendants(Id realmId) Registers for notification of an updated hierarchy structure that introduces a new descendant of the specified realm.
void	registerForNewRealms() Register for notifications of new realms.

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

canRegisterForRealmNotifications

boolean canRegisterForRealmNotifications()

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

registerForNewRealms

void registerForNewRealms()
                          throws OperationFailedException,
                                 PermissionDeniedException

Register for notifications of new realms. RealmReceiver.newRealm() is invoked when a new Realm is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewRealmAncestors

void registerForNewRealmAncestors(Id realmId)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Registers for notification of an updated hierarchy structure that introduces a new ancestor of the specified realm. RealmReceiver.newAncestorRealms() is invoked when the specified realm node gets a new ancestor.

Parameters:

realmId - the Id of the Realm node to monitor

Throws:

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewRealmDescendants

void registerForNewRealmDescendants(Id realmId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Registers for notification of an updated hierarchy structure that introduces a new descendant of the specified realm. RealmReceiver.newDescendantRealm() is invoked when the specified realm node gets a new descendant.

Parameters:

realmId - the Id of the Realm node to monitor

Throws:

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedRealms

void registerForChangedRealms()
                              throws OperationFailedException,
                                     PermissionDeniedException

Registers for notification of updated realms. RealmReceiver.changedRealms() is invoked when a realm is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedRealm

void registerForChangedRealm(Id realmId)
                             throws OperationFailedException,
                                    PermissionDeniedException

Registers for notification of an updated realm. RealmReceiver.changedRealms() is invoked when the specified realm is changed.

Parameters:

realmId - the Id of the Realm to monitor

Throws:

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRealms

void registerForDeletedRealms()
                              throws OperationFailedException,
                                     PermissionDeniedException

Registers for notification of deleted realms. RealmReceiver.deletedRealms() is invoked when a realm is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRealm

void registerForDeletedRealm(Id realmId)
                             throws OperationFailedException,
                                    PermissionDeniedException

Registers for notification of a deleted realm. RealmReceiver.deletedRealms() is invoked when the specified realm is deleted.

Parameters:

realmId - the Id of the Realm to monitor

Throws:

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRealmAncestors

void registerForDeletedRealmAncestors(Id realmId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Registers for notification of an updated hierarchy structure that removes an ancestor of the specified realm. RealmReceiver.deletedAncestorRealm() is invoked when the specified realm node loses an ancestor.

Parameters:

realmId - the Id of the Realm to monitor

Throws:

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedRealmDescendants

void registerForDeletedRealmDescendants(Id realmId)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Registers for notification of an updated hierarchy structure that removes a descendant of the specified realm. RealmReceiver.deletedDescendantRealm() is invoked when the specified realm node loses a descendant.

Parameters:

realmId - the Id of the Realm to monitor

Throws:

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.