com.pramati.bfly.das.contacts.helper
Class AddressBook

java.lang.Object
  com.pramati.bfly.das.contacts.helper.AddressBook

public class AddressBook
extends Object

AddressBook is a collection of a Dekoh user's Contacts. Contacts can be added/deleted/updated to an AdrressBook.

AddressBook for a Dekoh user can be obtained by invoking AddressBook.getAddressBookForUser(DesktopUser).

One way to obtain the DesktopUser is by invoking SessionUtil.getLoggedInDesktopUser(request) with a request Object. This request should be part of the Session, in which user has logged into this Dekoh Desktop.

Since:

15 Jun, 2007

Method Summary

Contact	addContact(Contact contact) Adds a new contact to this desktopUser's AddressBook with given Contact instance.
Contact	addContact(String contactId) Equivalent to calling AddressBook.addContact(com.pramati.bfly.das.contacts.persistence.Contact) after creating Contact instance with given contactId.
void	deleteContact(Contact contact) Deletes an existing Contact from this Dekoh user's AddressBook.
static AddressBook	getAddressBookForUser(DesktopUser desktopUser) Gets the AddressBook of given DekohUser.
List	getAllContacts()
Contact	getContactInfoForUser(String contactId) Retrieves the Contact information for the given contact Id.
List	getContactsForTag(String tagName)
List	getTags()
void	inviteUser(String contactId) Sends an invitation to contactId to register with Dekoh network and become mutual contacts.
Contact	updateContact(Contact contact) Updates the user profile of an existing contact in DesktopUser's AddressBook.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getAddressBookForUser

public static AddressBook getAddressBookForUser(DesktopUser desktopUser)

Gets the AddressBook of given DekohUser. Instance of DesktopUser who is currently logged in can be obtained by invoking SessionUtil.getLoggedInDesktopUser(request) method.

Parameters:

desktopUser - DekohUser for whom the addressBook is needed. Cannot be null. This needs to be a valid DekohUser, i.e should be a registered DekohUser with a valid dekohId.

Returns:

AddressBook instance for Adding/Deleting/Updating Contacts.

addContact

public Contact addContact(String contactId)
                   throws ContactsException,
                          CASNotReachableException,
                          UserOfflineException,
                          ForbiddenException

Equivalent to calling AddressBook.addContact(com.pramati.bfly.das.contacts.persistence.Contact) after creating Contact instance with given contactId.

Parameters:

contactId - email address or Dekoh User Id of the contact to add. It is assumed to be an email address, if this string has one '@' and a '.' in string following '@'.

Returns:

Contact instance representing the newly added contact.

Throws:

ContactsException

CASNotReachableException

UserOfflineException

ForbiddenException

addContact

public Contact addContact(Contact contact)
                   throws ContactsException,
                          CASNotReachableException,
                          UserOfflineException,
                          ForbiddenException

Adds a new contact to this desktopUser's AddressBook with given Contact instance. After successful adding and synchronising with central server, a Contact object representing this contact is returned.

ContactsListener.contactAdded listener callbacks are given after successful adding the contact.

Parameters:

contact - contact object with details like displayName, firstName, lastName etc. For mapping this contact to an dekoh account ContactIdName is used.

Returns:

Contact instance representing the newly added contact.

Throws:

ContactsException - If unable to add a contact. one of the following could be the reasons for getting this exception

• contactId null or empty.
• loggedin user is not a valid registered DekohUser. Only DekohUsers who have registered and got a valid dekohid can add Contacts.
• some exception on central server while adding the contact.

UserOfflineException - If User is logged into Dekoh Desktop in offline mode.

CASNotReachableException - If for any reason, Central server is not reachable.

ForbiddenException - If the authenticated Session from central server on this DekohDesktop has expired. Desktop user should logoff and login again, before trying any other contacts operation.

inviteUser

public void inviteUser(String contactId)
                throws ContactsException,
                       CASNotReachableException,
                       UserOfflineException,
                       ForbiddenException

Sends an invitation to contactId to register with Dekoh network and become mutual contacts.

Parameters:

contactId - email address or Dekoh User Id of the contact to invite. It is assumed to be an email address, if this string has one '@' and a '.' in string following '@'.

Throws:

ContactsException - If unable to add a contact. one of the following could be the reasons for getting this exception

• contactId null or empty.
• loggedin user is not a valid registered DekohUser. Only DekohUsers who have registered and got a valid dekohid can add Contacts.
• some exception on central server while adding the contact.

UserOfflineException - If User is logged into Dekoh Desktop in offline mode.

CASNotReachableException - If for any reason, Central server is not reachable.

ForbiddenException - If the authenticated Session from central server on this DekohDesktop has expired. Desktop user should logoff and login again, before trying any other contacts operation.

updateContact

public Contact updateContact(Contact contact)
                      throws ContactsException,
                             CASNotReachableException,
                             UserOfflineException,
                             ForbiddenException

Updates the user profile of an existing contact in DesktopUser's AddressBook.

ContactsListener.contactUpdated listener callback are given after successful inviting and updating the contact.

Parameters:

contact - Contact containing the information to be updated.

Returns:

Contact instance representing the updated contact.

Throws:

ContactsException - If unable to update a contact. one of the following could be the reasons for getting this exception

• Not an existing Contact
• some exception on central server while adding the contact.

UserOfflineException - If User is logged into Dekoh Desktop in offline mode.

CASNotReachableException - If for any reason, Central server is not reachable.

ForbiddenException - If the authenticated Session from central server on this DekohDesktop has expired. Desktop user should logoff and login again, before trying any other contacts operation.

deleteContact

public void deleteContact(Contact contact)
                   throws ContactsException,
                          CASNotReachableException,
                          UserOfflineException,
                          ForbiddenException

Deletes an existing Contact from this Dekoh user's AddressBook. Deleted contact cannot access any shared Dekoh applications from this user's Dekoh installations.

ContactsListener.contactDeleted listener callback is invoked after successfully deleting the Contact.

Parameters:

contact - Contact to be deleted.

Throws:

ContactsException - If no such Contact exists in this dekoh user's AddressBook.

UserOfflineException - If User is logged into Dekoh Desktop in offline mode.

CASNotReachableException - If for any reason, Central server is not reachable.

ForbiddenException - If the authenticated Session from central server on this DekohDesktop has expired. Desktop user should logoff and login again, before trying any other contacts operation.

getContactInfoForUser

public Contact getContactInfoForUser(String contactId)

Retrieves the Contact information for the given contact Id.

Parameters:

contactId - ContactId is the dekoh user id or the email address with which this Dekoh user used to add this contact.

Returns:

Contact, if there exists a contact with given ContactId. else would return null.

getAllContacts

public List getAllContacts()

Returns:

list of all contacts added to this Dekoh user's AddressBook, or an empty list if no contacts were added.

getContactsForTag

public List getContactsForTag(String tagName)

Parameters:

tagName - tag which this Dekoh user used to group related contacts.

Returns:

list of Contacts tagged with tagName by this Dekoh User. or an empty list, if no contact was tagged with given tagName.

getTags

public List getTags()

Returns:

list of all the tag names used by this Dekoh user to group the contacts in the adrres book, or empty list, if no tags were defined.