org.osid.authentication

Interface AgencyNotificationSession

All Superinterfaces:

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

public interface AgencyNotificationSession
extends OsidSession

This session defines methods to receive notifications on adds/changes to Agency 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.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canRegisterForAgencyNotifications() Tests if this user can register for Agency notifications.
void	registerForChangedAgencies() Registers for notification of updated agencies.
void	registerForChangedAgency(Id agencyId) Registers for notification of an updated agency.
void	registerForDeletedAgencies() Registers for notification of deleted agencies.
void	registerForDeletedAgency(Id agencyId) Registers for notification of a deleted agency.
void	registerForDeletedAgencyAncestors(Id agencyId) Registers for notification if an ancestor is removed from the specified agency in the agency hierarchy.
void	registerForDeletedAgencyDescendants(Id agencyId) Registers for notification if a descendant is removed from fthe specified agency in the agency hierarchy.
void	registerForNewAgencies() Register for notifications of new agencies.
void	registerForNewAgencyAncestors(Id agencyId) Registers for notification if an ancestor is added to the specified agency in the agency hierarchy.
void	registerForNewAgencyDescendants(Id agencyId) Registers for notification if a descendant is added to the specified agency in the agency hierarchy.

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

canRegisterForAgencyNotifications

boolean canRegisterForAgencyNotifications()

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

registerForNewAgencies

void registerForNewAgencies()
                            throws OperationFailedException,
                                   PermissionDeniedException

Register for notifications of new agencies. AgencyReceiver.newAgency() is invoked when a new Agency is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewAgencyAncestors

void registerForNewAgencyAncestors(Id agencyId)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Registers for notification if an ancestor is added to the specified agency in the agency hierarchy. AgencyReceiver.newAgencyAncestor() is invoked when the specified agency experiences an addition in ancestry.

Parameters:

agencyId - the Id of the agency to monitor

Throws:

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewAgencyDescendants

void registerForNewAgencyDescendants(Id agencyId)
                                     throws OperationFailedException,
                                            PermissionDeniedException

Registers for notification if a descendant is added to the specified agency in the agency hierarchy. AgencyReceiver.newAgencyDescendant() is invoked when the specified agency experiences an addition in descendants.

Parameters:

agencyId - the Id of the agency to monitor

Throws:

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedAgencies

void registerForChangedAgencies()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of updated agencies. AgencyReceiver.changedAgency() is invoked when an agency is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedAgency

void registerForChangedAgency(Id agencyId)
                              throws OperationFailedException,
                                     PermissionDeniedException

Registers for notification of an updated agency. AgencyReceiver.changedAgency() is invoked when the specified agency is changed.

Parameters:

agencyId - the Id of the agency to monitor

Throws:

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedAgencies

void registerForDeletedAgencies()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of deleted agencies. AgencyReceiver.deletedAgency() is invoked when an agency is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedAgency

void registerForDeletedAgency(Id agencyId)
                              throws OperationFailedException,
                                     PermissionDeniedException

Registers for notification of a deleted agency. AgencyReceiver.deletedAgency() is invoked when the specified agency is deleted.

Parameters:

agencyId - the Id of the agency to monitor

Throws:

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedAgencyAncestors

void registerForDeletedAgencyAncestors(Id agencyId)
                                       throws OperationFailedException,
                                              PermissionDeniedException

Registers for notification if an ancestor is removed from the specified agency in the agency hierarchy. AgencyReceiver.deletedAgencyAncestor() is invoked when the specified agency experiences a removal of an ancestor.

Parameters:

agencyId - the Id of the agency to monitor

Throws:

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedAgencyDescendants

void registerForDeletedAgencyDescendants(Id agencyId)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Registers for notification if a descendant is removed from fthe specified agency in the agency hierarchy. AgencyReceiver.deletedAgencyDescednant() is invoked when the specified agency experiences a removal of one of its descendants.

Parameters:

agencyId - the Id of the agency to monitor

Throws:

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.