org.osid.authentication.keys

Interface KeyNotificationSession

All Superinterfaces:

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

public interface KeyNotificationSession
extends OsidSession

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

The two views defined in this session correspond to the views in the KeyLookupSession.

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledgeKeyNotification(Id notificationId) Acknowledge a key notification.
boolean	canRegisterForKeyNotifications() Tests if this user can register for Key notifications.
Agency	getAgency() Gets the Agency associated with this session.
Id	getAgencyId() Gets the Agency Id associated with this session.
void	registerForChangedKey(Id keyId) Registers for notification of an updated key.
void	registerForChangedKeys() Registers for notification of updated keys.
void	registerForDeletedKey(Id keyId) Registers for notification of a deleted key.
void	registerForDeletedKeys() Registers for notification of deleted keys.
void	registerForNewKeys() Register for notifications of new keys.
void	reliableKeyNotifications() Reliable notifications are desired.
void	unreliableKeyNotifications() Unreliable notifications are desired.
void	useFederatedAgencyView() Federates the view for methods in this session.
void	useIsolatedAgencyView() 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

getAgencyId

Id getAgencyId()

Gets the Agency Id associated with this session.

Returns:

the Agency Id associated with this session

Compliance:

mandatory - This method must be implemented.

getAgency

Agency getAgency()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the Agency associated with this session.

Returns:

the Agency associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canRegisterForKeyNotifications

boolean canRegisterForKeyNotifications()

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

useFederatedAgencyView

void useFederatedAgencyView()

Federates the view for methods in this session. A federated view will include keys in agencies which are children of this agency in the agency hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedAgencyView

void useIsolatedAgencyView()

Isolates the view for methods in this session. An isolated view restricts notifications to this agency only.

Compliance:

mandatory - This method is must be implemented.

reliableKeyNotifications

void reliableKeyNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableKeyNotifications

void unreliableKeyNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeKeyNotification

void acknowledgeKeyNotification(Id notificationId)
                                throws OperationFailedException,
                                       PermissionDeniedException

Acknowledge a key notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewKeys

void registerForNewKeys()
                        throws OperationFailedException,
                               PermissionDeniedException

Register for notifications of new keys. KeyReceiver.newKeys() is invoked when a new Key is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedKeys

void registerForChangedKeys()
                            throws OperationFailedException,
                                   PermissionDeniedException

Registers for notification of updated keys. KeyReceiver.changedKeys() is invoked when an key is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedKey

void registerForChangedKey(Id keyId)
                           throws OperationFailedException,
                                  PermissionDeniedException

Registers for notification of an updated key. KeyReceiver.changedKeys() is invoked when the specified key is changed.

Parameters:

keyId - the Id of the Key to monitor

Throws:

NullArgumentException - keyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedKeys

void registerForDeletedKeys()
                            throws OperationFailedException,
                                   PermissionDeniedException

Registers for notification of deleted keys. KeyReceiver.deletedKeys() is invoked when an key is removed from this agency.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedKey

void registerForDeletedKey(Id keyId)
                           throws OperationFailedException,
                                  PermissionDeniedException

Registers for notification of a deleted key. KeyReceiver.deletedKeys() is invoked when the specified key is removed from this agency.

Parameters:

keyId - the Id of the Key to monitor

Throws:

NullArgumentException - keyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.