com.pramati.bfly.das.contacts.persistence
Class ContactsManager

java.lang.Object
  com.pramati.bfly.das.contacts.persistence.ContactsManager

public class ContactsManager
extends Object

Manager class for Adding/Deleting/Updating Contacts information. ContactsManager.getContactsManager() will return an Signleton instance of this class.

Every operation on Contactmanager is synced with centralServer, so that ContactInformation is always updated.

Dekoh uses derby database for persisting the contact information on Dekoh Desktops, and persists the information under "$Dekoh_Installation_Dir/server/user-data/Personal_Server/contacts/db". If the driver class "org.apache.derby.jdbc.EmbeddedDriver" is missing, or users doesn't have permissions to persist the information on above specified directory, invoking ContactsManager.getContactsManager() would throw an IllegalStateException.

Every Contact object is refered with a ContactId which could be the emailAddress or the DekohId, with which the contact is added. A usecase when Contact Id is automatiaclly updated with Dekoh user Id is, if a Contact is added using Email Address as ContactId, and that Contact is already registered with dekoh, and shared an Application to the user who added him as a contact.

Since:

14 Feb, 2007

Method Summary

Contact	addContact(String accountId, String loggedInUserDekohId, String authenticatedCookie, Contact contact) API To add a new contact using Contact instance.
Contact	addContact(String accountId, String loggedInUserDekohId, String authenticatedCookie, String contactId) API To add a new contact with an EmailAddress or Dekoh User Id.
void	deleteContact(String accountId, String loggedInUserDekohId, String authenticatedCookie, String contactKey) API to delete a Contact.
Contact	getContact(String accountId, String emailIdOrDekohId) To get the Contact details for the user Account 'accountId', with Contact Id as 'emailIdorDekohId'.
List	getContacts(String accountId) Api to get the list of contacts defined for given user.
List	getContactsForTag(String accountId, String tagName) Get all contacts of user with accountId 'accountId', who are tagged with the given 'tagName'.
static ContactsManager	getContactsManager()
Set	getIncomingUserAliases(HttpServletRequest request) API to know the Contacts who are making the remote request, i.e request made to a Dekoh Desktop through Dekoh Network.
static Contact	getPublicContact()
List	getTags(String accountId) API to get the list of tags defined by passed user AccountId.
static boolean	isPublicContact(Contact contact)
static boolean	isPublicContact(String contactKey)
void	refresh(String accountId, String dekohId, String authenticatedCookie) To refresh the Dekoh Desktop Contacts, and sync with central server.
boolean	registerContactsListener(ContactsListener contactsListener) For registering a ContactsListener, for giving callbacks when Contact Addition/Deletion/Updation event occurs.
void	shutdown() To shutdown the Contacts local database.
boolean	unregisterContactsListener(ContactsListener contactsListener) For unregistering a ContactsListener.
Contact	updateContact(String accountId, String loggedInUserDekohId, String authenticatedCookie, Contact contact) API for updating an existing contact.

Methods inherited from class java.lang.Object

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

Method Detail

getContactsManager

public static ContactsManager getContactsManager()

registerContactsListener

public boolean registerContactsListener(ContactsListener contactsListener)

For registering a ContactsListener, for giving callbacks when Contact Addition/Deletion/Updation event occurs.

Parameters:

contactsListener - ContactsListener instance which gets callbacks when a share/unshare event occurs.

Returns:

true if contactsListener is successfully registered.

unregisterContactsListener

public boolean unregisterContactsListener(ContactsListener contactsListener)

For unregistering a ContactsListener.

Parameters:

contactsListener - ContactsListener instance for which no more callbacks are needed when Contact Addition/Deletion/Updation event occurs.

Returns:

true if contactsListener is successfully registered. would return false, if user tries to deregister a non registered listener.

addContact

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

API To add a new contact with an EmailAddress or Dekoh User Id. A request is made to central server, and after getting a suucess message from central server, contact information is persisted on to the Dekoh Desktop. If a Contact already exists with given ContactId in user's Contacts List, the existing Contact is returned.

ContactsListener.contactAdded listener callback is invoked after successful addition of contact. Listeners are invoked even if this api is invoked on an already existing contact.

Parameters:

accountId - LoggedIn user's AccountId.

loggedInUserDekohId - LoggedIn user's Dekoh Id.

authenticatedCookie - Authenticated cookie of the logged in user. This is needed for authenticating and authorizing the logged in user on the central server, before returning the requested information.

contactId - EmailAddress or Dekoh User Id of the contact to add. It is assumed an Email Address, if it has all the email Contraints, i.e having one '@' and a '.' after '@'

Returns:

Contact instance representing the new contact added.

Throws:

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

• contactId null or empty.
• Not a valid DekohId i.e no user is registered with given dekohId.
• some exception on central server while adding the contact.

UserOfflineException - If authenticatedCookie is null. When user is logged in locally because of no internet connectivity, authenticatedCookie would be set to null. So it is assumed in this api that, if authenticatedCookie is passed as null, user should have logged in locally. so cant do any contact operations.

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

ForbiddenException - If the authenticatedCookie is not a valid cookie.

addContact

public Contact addContact(String accountId,
                          String loggedInUserDekohId,
                          String authenticatedCookie,
                          Contact contact)
                   throws ContactsException,
                          CASNotReachableException,
                          UserOfflineException,
                          ForbiddenException

API To add a new contact using Contact instance. A request is made to central server, and after getting a suucess message from central server, contact information is persisted on to the Dekoh Desktop. If a Contact already exists with given ContactId in users Contacts List, the existing Contact is returned.

ContactsListener.contactAdded listener callback is invoked after successful addition of contact. Listeners are invoked even if this api is invoked on an already existing contact.

Parameters:

accountId - LoggedIn user's AccountId.

loggedInUserDekohId - LoggedIn user's Dekoh Id.

authenticatedCookie - Authenticated cookie of the logged in user. This is needed for authenticating and authorizing the logged in user on the central server, before returning the requested information.

contact - A Contact Object having contacts details like displayName, firstName, lastName etc. For Mapping to an Account for this Contact, ContactIdName is used.

Returns:

Contact instance representing the new contact added.

Throws:

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

• contact.getContactIdName() null or empty.
• Not a valid Dekoh User Id i.e no user is registered with given Dekoh User Id.
• some exception on central server while adding the contact.

UserOfflineException - If authenticatedCookie is null. When user is logged in locally because of no internet connectivity, authenticatedCookie would be set to null. So it is assumed in this api that, if authenticatedCookie is passed as null, user should have logged in locally. so cant do any contact operations.

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

ForbiddenException - If the authenticatedCookie is not a valid cookie.

updateContact

public Contact updateContact(String accountId,
                             String loggedInUserDekohId,
                             String authenticatedCookie,
                             Contact contact)
                      throws ContactsException,
                             CASNotReachableException,
                             UserOfflineException,
                             ForbiddenException

API for updating an existing contact. Passed Contact should be an existing Contact before updating. If this API is invoked on a Contact, who is not in loggedIn user's ContactsList, a ContactsException is triggered.

ContactsListener.contactUpdated listener callback is invoked after successfully updating the Contact.

Parameters:

accountId - LoggedIn user's AccountId.

loggedInUserDekohId - LoggedIn user's Dekoh Id.

authenticatedCookie - Authenticated cookie of the logged in user. This is needed for authenticating and authorizing the logged in user on the central server, before returning the requested information.

contact - Contact instance representing the updated contact.

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

• contact.getContactIdName() null or empty.
• No Contact exists with given ContactIdName
• some exception on central server while adding the contact.

UserOfflineException - If authenticatedCookie is null. When user is logged in locally because of no internet connectivity, authenticatedCookie would be set to null. So it is assumed in this api that, if authenticatedCookie is passed as null, user should have logged in locally. so cant do any contact operations.

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

ForbiddenException - If the authenticatedCookie is not a valid cookie.

deleteContact

public void deleteContact(String accountId,
                          String loggedInUserDekohId,
                          String authenticatedCookie,
                          String contactKey)
                   throws ContactsException,
                          CASNotReachableException,
                          UserOfflineException,
                          ForbiddenException

API to delete a Contact. ContactKet passed should be a valid ContactKey, i.e should be existing Contacts ContactKey.

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

Parameters:

accountId - LoggedIn user's AccountId.

loggedInUserDekohId - LoggedIn user's Dekoh Id.

authenticatedCookie - Authenticated cookie of the logged in user. This is needed for authenticating and authorizing the logged in user on the central server, before returning the requested information.

contactKey - ContactKey representing the contact to be deleted.

Throws:

ContactsException - If no Contact Exists with given ContactKey.

UserOfflineException - If authenticatedCookie is null. When user is logged in locally because of no internet connectivity, authenticatedCookie would be set to null. So it is assumed in this api that, if authenticatedCookie is passed as null, user should have logged in locally. so cant do any contact operations.

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

ForbiddenException - If the authenticatedCookie is not a valid cookie.

refresh

public void refresh(String accountId,
                    String dekohId,
                    String authenticatedCookie)
             throws ContactsException,
                    CASNotReachableException,
                    UserOfflineException,
                    ForbiddenException

To refresh the Dekoh Desktop Contacts, and sync with central server. ContactsListener.contactsRefreshed(ContactEvent) ContactsListener.contactsRefreshed} listener callback is invoked after successfully refreshing the contacts on Dekoh Desktop.

Parameters:

accountId - LoggedIn user's AccountId.

dekohId - LoggedIn user's Dekoh Id.

authenticatedCookie - Authenticated cookie of the logged in user. This is needed for authenticating and authorizing the logged in user on the central server, before returning the requested information.

Throws:

ContactsException - If no Contact Exists with given ContactKey.

UserOfflineException - If authenticatedCookie is null. When user is logged in locally because of no internet connectivity, authenticatedCookie would be set to null. So it is assumed in this api that, if authenticatedCookie is passed as null, user should have logged in locally. so cant do any contact operations.

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

ForbiddenException - If the authenticatedCookie is not a valid cookie.

getContact

public Contact getContact(String accountId,
                          String emailIdOrDekohId)

To get the Contact details for the user Account 'accountId', with Contact Id as 'emailIdorDekohId'.

Parameters:

accountId - LoggedIn user's AccountId.

emailIdOrDekohId - ContactId with which a contact is added.

Returns:

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

getContactsForTag

public List getContactsForTag(String accountId,
                              String tagName)

Get all contacts of user with accountId 'accountId', who are tagged with the given 'tagName'.

Parameters:

accountId - LoggedIn user's AccountId.

tagName - tag name

Returns:

list of Contacts having Tag as 'tagName'. should return an empty list, if no contacts is tagged with given tagName.

getTags

public List getTags(String accountId)

API to get the list of tags defined by passed user AccountId. invoking getContactsForTag would return the Contacts for whom these tags are applied for.

Parameters:

accountId - LoggedIn user's AccountId.

Returns:

List of tagNames defined. would retun empty list, if no tags are defined by the passed account.

getContacts

public List getContacts(String accountId)

Api to get the list of contacts defined for given user.

Parameters:

accountId - LoggedIn user's AccountId.

Returns:

List of contacts for logged in user. would return empty list if no contacts are defined.

getIncomingUserAliases

public Set getIncomingUserAliases(HttpServletRequest request)

API to know the Contacts who are making the remote request, i.e request made to a Dekoh Desktop through Dekoh Network.

If the application is shared to DekohNetwork or to All, then a Non Contact can access an Application on a user Dekoh Desktop. In such cases, if the incoming user is not in the DekohDesktop contacts List, this API would return an empty list.

Parameters:

request - HttpServletRequest from central server onto the Dekoh Desktop for accessing shared pages.

Returns:

List of Contacts who are accessing.

getPublicContact

public static Contact getPublicContact()

isPublicContact

public static boolean isPublicContact(String contactKey)

isPublicContact

public static boolean isPublicContact(Contact contact)

shutdown

public void shutdown()

To shutdown the Contacts local database. This api should never be invoked by portal application developers..