org.osid.configuration

Interface ParameterNotificationSession

All Superinterfaces:

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

public interface ParameterNotificationSession
extends OsidSession

This session defines methods to receive notifications on adds/changes to Configurations and their properties. 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 federateParameterView() and isolateParameterView() 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	acknowledgeParameterNotification(Id notificationId) Acknowledge a parameter notification.
boolean	canRegisterForParameterNotifications() Tests if this user can register for Parameter notifications.
Configuration	getConfiguration() Gets the Configuration associated with this session.
Id	getConfigurationId() Gets the Configuration Id associated with this session.
void	registerForChangedParameter(Id parameterId) Assigns a callback for notifications of an update to a parameter.
void	registerForChangedParameters() Assigns a callback for notification of updated parameters.
void	registerForDeletedParameter(Id parameterId) Assigns a callback for notifications of a deleted parameter.
void	registerForDeletedParameters() Assigns a callback for notification of deleted parameters.
void	registerForNewParameters() Assigns a callback for notifications of new parameters.
void	reliableParameterNotifications() Reliable notifications are desired.
void	unreliableParameterNotifications() 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.

canRegisterForParameterNotifications

boolean canRegisterForParameterNotifications()

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

reliableParameterNotifications

void reliableParameterNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableParameterNotifications

void unreliableParameterNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeParameterNotification

void acknowledgeParameterNotification(Id notificationId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Acknowledge a parameter notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewParameters

void registerForNewParameters()
                              throws OperationFailedException,
                                     PermissionDeniedException

Assigns a callback for notifications of new parameters. ParameterReceiver.newParameters() is invoked when a new Parameter is added to this configuration.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedParameters

void registerForChangedParameters()
                                  throws OperationFailedException,
                                         PermissionDeniedException

Assigns a callback for notification of updated parameters. ParameterReceiver.changedParameters() is invoked when a Parameter is changed in this configuration.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedParameter

void registerForChangedParameter(Id parameterId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Assigns a callback for notifications of an update to a parameter. ParamaterReceiver.changedParameters() is invoked when the specified Parameter is changed in 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.

registerForDeletedParameters

void registerForDeletedParameters()
                                  throws OperationFailedException,
                                         PermissionDeniedException

Assigns a callback for notification of deleted parameters. ParameterReceiver.deletedParamaters() is invoked when a Parameter is deleted or removed from this configuration.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedParameter

void registerForDeletedParameter(Id parameterId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Assigns a callback for notifications of a deleted parameter. ParameterReceiver.deletedParameters() is invoked when the specified Parameter is deleted or 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.