org.osid.configuration

Interface ValueNotificationSession

All Superinterfaces:

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

public interface ValueNotificationSession
extends OsidSession

This session defines methods to receive notifications on changes to Values. A particular value in a set may have been added or deleted, but all changes appear as a change to a parameter. Once a change notification is received, the new value list can be obtained through the ValueLookupSession. This session is intended for adapters and providers needing to synchronize their state with this service without the use of polling. Notifications are cancelled when this session is closed.

Two views are defined;

• federated: parameters defined in configurations that are a parent of this configuration in the configuration hierarchy are included for notifications
• isolated: notifications are restricted to parameters are defined to within this configuration

The methods federateValuerView() and isolateValueView() behave as a radio group and one should be selected before invoking any lookup methods.

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeValueNotification(Id notificationId) Acknowledge a value notification.
boolean	canRegisterForValueNotifications() Tests if this user can register for Value notifications.
Configuration	getConfiguration() Gets the Configuration associated with this session.
Id	getConfigurationId() Gets the Configuration Id associated with this session.
void	registerForChangedValue(Id valueId) Assigns a callback for notifications of an update to a value in this configuration.
void	registerForChangedValues() Assigns a callback for notification of updated parameter values in this configuration.
void	registerForChangedValuesForParameter(Id parameterId) Assigns a callback for notifications of changed values for the given parameter.
void	registerForDeletedValue(Id valueId) Assigns a callback for notifications of an update to a value in this configuration.
void	registerForDeletedValues() Assigns a callback for notification of deleted values in this configuration.
void	registerForDeletedValuesForParameter(Id parameterId) Assigns a callback for notifications of changed values for the given parameter.
void	registerForNewValues() Assigns a callback for notifications of new values.
void	registerForNewValuesForParameter(Id parameterId) Assigns a callback for notifications of new values for the given parameter.
void	reliableValueNotifications() Reliable notifications are desired.
void	unreliableValueNotifications() Unreliable notifications are desired.
void	useFederatedConfigurationView() Federates the view for methods in this session.
void	useIsolatedConfigurationView() 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

getConfigurationId

Id getConfigurationId()

Gets the Configuration Id associated with this session.

Returns:

the Configuration Id associated with this session

Compliance:

mandatory - This method must be implemented.

getConfiguration

Configuration getConfiguration()
                               throws OperationFailedException,
                                      PermissionDeniedException

Gets the Configuration associated with this session.

Returns:

the Configuration associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canRegisterForValueNotifications

boolean canRegisterForValueNotifications()

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

useFederatedConfigurationView

void useFederatedConfigurationView()

Federates the view for methods in this session. A federated view will include parameters in configurations of which this configuration is a child in the configuration hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedConfigurationView

void useIsolatedConfigurationView()

Isolates the view for methods in this session. An isolated view restricts notifications for parameter values to this configuration only.

Compliance:

mandatory - This method is must be implemented.

reliableValueNotifications

void reliableValueNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableValueNotifications

void unreliableValueNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeValueNotification

void acknowledgeValueNotification(Id notificationId)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Acknowledge a value notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewValues

void registerForNewValues()
                          throws OperationFailedException,
                                 PermissionDeniedException

Assigns a callback for notifications of new values. ValueReceiver.newValues() is invoked when a new Value is added to this configuration.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewValuesForParameter

void registerForNewValuesForParameter(Id parameterId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Assigns a callback for notifications of new values for the given parameter. ValueReceiver.newValues() is invoked when a new Value is added to this configuration.

Parameters:

parameterId - the Id of the Parameter to monitor

Throws:

NullArgumentException - parameterId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedValues

void registerForChangedValues()
                              throws OperationFailedException,
                                     PermissionDeniedException

Assigns a callback for notification of updated parameter values in this configuration. ValueReceiver.changedValues() is invoked when a Value is changed in this configuration.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedValuesForParameter

void registerForChangedValuesForParameter(Id parameterId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Assigns a callback for notifications of changed values for the given parameter. ValueReceiver.changedValues() is invoked when a Value is updated to this configuration.

Parameters:

parameterId - the Id of the Parameter to monitor

Throws:

NullArgumentException - parameterId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedValue

void registerForChangedValue(Id valueId)
                             throws OperationFailedException,
                                    PermissionDeniedException

Assigns a callback for notifications of an update to a value in this configuration. ValueReceiver.changedValues() is invoked when the specified Value is updated in this configuration.

Parameters:

valueId - the Id of the Value to monitor

Throws:

NullArgumentException - valueId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedValues

void registerForDeletedValues()
                              throws OperationFailedException,
                                     PermissionDeniedException

Assigns a callback for notification of deleted values in this configuration. ValueReceiver.changedValues() is invoked when a Value is removed from this configuration.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedValuesForParameter

void registerForDeletedValuesForParameter(Id parameterId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Assigns a callback for notifications of changed values for the given parameter. ValueReceiver.changedValues() is invoked when a Value is removed from this configuration.

Parameters:

parameterId - the Id of the Parameter to monitor

Throws:

NullArgumentException - parameterId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedValue

void registerForDeletedValue(Id valueId)
                             throws OperationFailedException,
                                    PermissionDeniedException

Assigns a callback for notifications of an update to a value in this configuration. ValueReceiver.changedValues() is invoked when the specified Value is removed from this configuration.

Parameters:

valueId - the Id of the Value to monitor

Throws:

NullArgumentException - valueId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.