org.osid.metering

Interface UtilityNotificationSession

All Superinterfaces:

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

public interface UtilityNotificationSession
extends OsidSession

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canRegisterForUtilityNotifications() Tests if this user can register for Utility notifications.
void	registerForChangedUtilities() Registers for notification of updated utilities.
void	registerForChangedUtility(Id utilityId) Registers for notification of an updated utility.
void	registerForDeletedUtilities() Registers for notification of deleted utilities.
void	registerForDeletedUtility(Id utilityId) Registers for notification of a deleted utility.
void	registerForDeletedUtilityAncestors(Id utilityId) Registers for notification of an updated hierarchy structure that removes an ancestor of the specified utility.
void	registerForDeletedUtilityDescendants(Id utilityId) Registers for notification of an updated hierarchy structure that removes a descendant of the specified utility.
void	registerForNewUtilities() Register for notifications of new utilities.
void	registerForNewUtilityAncestors(Id utilityId) Registers for notification of an updated hierarchy structure that introduces a new ancestor of the specified utility.
void	registerForNewUtilityDescendants(Id utilityId) Registers for notification of an updated hierarchy structure that introduces a new descendant of the specified utility.

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

canRegisterForUtilityNotifications

boolean canRegisterForUtilityNotifications()

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

registerForNewUtilities

void registerForNewUtilities()
                             throws OperationFailedException,
                                    PermissionDeniedException

Register for notifications of new utilities. UtilityReceiver.newUtilities() is invoked when a new Utility is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewUtilityAncestors

void registerForNewUtilityAncestors(Id utilityId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Registers for notification of an updated hierarchy structure that introduces a new ancestor of the specified utility. UtilityReceiver.newAncestorUtility() is invoked when the specified utility node gets a new ancestor.

Parameters:

utilityId - the Id of the Utility node to monitor

Throws:

NullArgumentException - utilityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewUtilityDescendants

void registerForNewUtilityDescendants(Id utilityId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Registers for notification of an updated hierarchy structure that introduces a new descendant of the specified utility. UtilityReceiver.newDescendantUtility() is invoked when the specified utility node gets a new descendant.

Parameters:

utilityId - the Id of the Utility node to monitor

Throws:

NullArgumentException - utilityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedUtilities

void registerForChangedUtilities()
                                 throws OperationFailedException,
                                        PermissionDeniedException

Registers for notification of updated utilities. UtilityReceiver.changedUtilities() is invoked when a utility is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedUtility

void registerForChangedUtility(Id utilityId)
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of an updated utility. UtilityReceiver.changedUtilities() is invoked when the specified utility is changed.

Parameters:

utilityId - the Id of the Utility to monitor

Throws:

NullArgumentException - utilityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedUtilities

void registerForDeletedUtilities()
                                 throws OperationFailedException,
                                        PermissionDeniedException

Registers for notification of deleted utilities. UtilityReceiver.deletedUtilities() is invoked when a utility is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedUtility

void registerForDeletedUtility(Id utilityId)
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of a deleted utility. UtilityReceiver.deletedUtilities() is invoked when the specified utility is deleted.

Parameters:

utilityId - the Id of the Utility to monitor

Throws:

NullArgumentException - utilityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedUtilityAncestors

void registerForDeletedUtilityAncestors(Id utilityId)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Registers for notification of an updated hierarchy structure that removes an ancestor of the specified utility. UtilityReceiver.deletedAncestor() is invoked when the specified utility node loses an ancestor.

Parameters:

utilityId - the Id of the Utility node to monitor

Throws:

NullArgumentException - utilityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedUtilityDescendants

void registerForDeletedUtilityDescendants(Id utilityId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Registers for notification of an updated hierarchy structure that removes a descendant of the specified utility. UtilityReceiver.deletedDescendant() is invoked when the specified utility node loses a descendant.

Parameters:

utilityId - the Id of the Utility node to monitor

Throws:

NullArgumentException - utilityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.