org.osid.contact

Interface ContactNotificationSession

All Superinterfaces:

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

public interface ContactNotificationSession
extends OsidSession

This session defines methods to receive notifications on adds/changes to Contact 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
void	acknowledgeContactNotification(Id notificationId) Acknowledge a contact notification.
boolean	canRegisterForContactNotifications() Tests if this user can register for Contact notifications.
AddressBook	getAddressBook() Gets the AddressBook associated with this session.
Id	getAddressBookId() Gets the AddressBook Id associated with this session.
void	registerForChangedContact(Id contactId) Registers for notification of an updated contact.
void	registerForChangedContacts() Registers for notification of updated contacts.
void	registerForChangedContactsByGenusType(Type contactGenusType) Register for notifications of changed contacts for the given contact genus Type.
void	registerForChangedContactsForAddress(Id addressId) Register for notifications of changed contacts for the given address Id.
void	registerForChangedContactsForReference(Id referenceId) Register for notifications of changed contacts for the given reference Id.
void	registerForDeletedContact(Id contactId) Registers for notification of a deleted contact.
void	registerForDeletedContacts() Registers for notification of deleted contacts.
void	registerForDeletedContactsByGenusType(Type contactGenusType) Register for notifications of deleted contacts for the given contact genus Type.
void	registerForDeletedContactsForAddress(Id addressId) Register for notifications of deleted contacts for the given address Id.
void	registerForDeletedContactsForReference(Id referenceId) Register for notifications of deleted contacts for the given reference Id.
void	registerForNewContacts() Register for notifications of new contacts.
void	registerForNewContactsByGenusType(Type contactGenusType) Register for notifications of new contacts for the given genus Type.
void	registerForNewContactsForAddress(Id addressId) Register for notifications of new contacts for the given reference Id.
void	registerForNewContactsForReference(Id referenceId) Register for notifications of new contacts for the given reference Id.
void	reliableContactNotifications() Reliable notifications are desired.
void	unreliableContactNotifications() Unreliable notifications are desired.
void	useFederatedAddressBookView() Federates the view for methods in this session.
void	useIsolatedAddressBookView() 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

getAddressBookId

Id getAddressBookId()

Gets the AddressBook Id associated with this session.

Returns:

the AddressBook Id associated with this session

Compliance:

mandatory - This method must be implemented.

getAddressBook

AddressBook getAddressBook()
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets the AddressBook associated with this session.

Returns:

the address book

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canRegisterForContactNotifications

boolean canRegisterForContactNotifications()

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

useFederatedAddressBookView

void useFederatedAddressBookView()

Federates the view for methods in this session. A federated view will include contacts in address books which are children of this address book in the address book hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedAddressBookView

void useIsolatedAddressBookView()

Isolates the view for methods in this session. An isolated view restricts retrievals to this address book only.

Compliance:

mandatory - This method is must be implemented.

reliableContactNotifications

void reliableContactNotifications()

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

Compliance:

mandatory - This method is must be implemented.

unreliableContactNotifications

void unreliableContactNotifications()

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

Compliance:

mandatory - This method is must be implemented.

acknowledgeContactNotification

void acknowledgeContactNotification(Id notificationId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Acknowledge a contact notification.

Parameters:

notificationId - the Id of the notification

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewContacts

void registerForNewContacts()
                            throws OperationFailedException,
                                   PermissionDeniedException

Register for notifications of new contacts. ContactReceiver.newContacts() is invoked when a new Contact is created.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewContactsByGenusType

void registerForNewContactsByGenusType(Type contactGenusType)
                                       throws OperationFailedException,
                                              PermissionDeniedException

Register for notifications of new contacts for the given genus Type. ContactReceiver.newContacts() is invoked when a new Contact is created.

Parameters:

contactGenusType - the contact genus type to monitor

Throws:

NullArgumentException - contactGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewContactsForReference

void registerForNewContactsForReference(Id referenceId)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Register for notifications of new contacts for the given reference Id. ContactReceiver.newContacts() is invoked when a new Contact is created.

Parameters:

referenceId - the Id of the reference to monitor

Throws:

NullArgumentException - referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewContactsForAddress

void registerForNewContactsForAddress(Id addressId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Register for notifications of new contacts for the given reference Id. ContactReceiver.newContacts() is invoked when a new Contact is created.

Parameters:

addressId - the Id of the address to monitor

Throws:

NullArgumentException - addressId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedContacts

void registerForChangedContacts()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of updated contacts. ContactReceiver.changedContacts() is invoked when a contact is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedContactsByGenusType

void registerForChangedContactsByGenusType(Type contactGenusType)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Register for notifications of changed contacts for the given contact genus Type. ContactReceiver.changedContacts() is invoked when a Contact for the genus type is changed.

Parameters:

contactGenusType - the contact genus type to monitor

Throws:

NullArgumentException - contactGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedContactsForReference

void registerForChangedContactsForReference(Id referenceId)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Register for notifications of changed contacts for the given reference Id. ContactReceiver.changedContacts() is invoked when a Contact for the reference is changed.

Parameters:

referenceId - the Id of the reference to monitor

Throws:

NullArgumentException - referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedContactsForAddress

void registerForChangedContactsForAddress(Id addressId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Register for notifications of changed contacts for the given address Id. ContactReceiver.changedContacts() is invoked when a Contact for the address is changed.

Parameters:

addressId - the Id of the address to monitor

Throws:

NullArgumentException - addressId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedContact

void registerForChangedContact(Id contactId)
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of an updated contact. ContactReceiver.changedContact() is invoked when the specified contact is changed.

Parameters:

contactId - the Id of the Contact to monitor

Throws:

NullArgumentException - contactId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedContacts

void registerForDeletedContacts()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of deleted contacts. ContactReceiver.deletedContacts() is invoked when a contact is deleted.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedContactsByGenusType

void registerForDeletedContactsByGenusType(Type contactGenusType)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Register for notifications of deleted contacts for the given contact genus Type. ContactReceiver.deletedContacts() is invoked when a Contact for the genus type is deleted.

Parameters:

contactGenusType - the contact genus type to monitor

Throws:

NullArgumentException - contactGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedContactsForReference

void registerForDeletedContactsForReference(Id referenceId)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Register for notifications of deleted contacts for the given reference Id. ContactReceiver.deletedContacts() is invoked when a Contact for the reference is deleted.

Parameters:

referenceId - the Id of the reference to monitor

Throws:

NullArgumentException - referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedContactsForAddress

void registerForDeletedContactsForAddress(Id addressId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Register for notifications of deleted contacts for the given address Id. ContactReceiver.deletedContacts() is invoked when a Contact for the address is deleted.

Parameters:

addressId - the Id of the address to monitor

Throws:

NullArgumentException - addressId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedContact

void registerForDeletedContact(Id contactId)
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of a deleted contact. ContactReceiver.deletedContacts() is invoked when the specified contact is deleted.

Parameters:

contactId - the Id of the Contact to monitor

Throws:

NullArgumentException - contactId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.