Contact’em is a desktop address book application, and the user interacts with it through typing commands into the application.
Code contributed: [Functional code] [Test code]
Start of Extract [from: User Guide]
Contact’em is now integrated with the ability to import/ export / sync contacts from google contacts. Being able to access contacts from your mobile phones is the quickest way to get things done. Export your contact directly to your android phones through google contacts to have your contacts on the go. Simply synchronize Contact’em whenever you make changes to your Google Contacts and your contacts will be updated.
Enter login to link Contact’em with Google Contacts / Gmail. When the login page is loaded, simply key in your credentials and you will be redirected to google contacts.
Format: login import export sync
Enter import to have all your Google Contacts transferred to Contact’em.
Figure 5.14.1 : Example of usage of Import command
Use export to have all your contacts in Contact’em transferred to Google Contacts.
Figure 5.14.2 : Example of usage of Export command
|
Note
|
Export might take several minutes. Please do not close your application meanwhile even if it becomes unresponsive |
Enter sync to have your contacts in Google Contacts updated to Contact’em. Contacts in Google Contacts takes higher precedence and when sync is used, contacts in Contact’em will be updated to the contacts in Google Contacts.
-
When using
import/export/synccommand, your browser must have google contacts page loaded If you have switched the page, you will have to login again to use the commands. -
Please refresh the Google contacts page after exporting for the exported contacts to show up. Check FAQ for more information if contacts are still missing.
-
If a google contact fails to import or sync, please check the contact to make sure that the parameters are valid. Please check the reference guide on the validity of the parameters
-
All google contacts imported are tagged with a ‘GoogleContact’ tag to indicate that they are linked to Google Contacts. Contacts deleted in Google Contacts will not be deleted in Contact’em when synced. It will simply lose its
GoogleContacttag.
End of Extract
The main theme of Contact’em is to manage and store contacts. As the use of Smart phones is becoming more prevalent in the world right now, being able to access contacts on the go has become the priority of many users. Hence, Contact’em is now able to be synchronise with google contacts, which can be accessed on most mobile devices.
Contact’em now incorporates and integrates Google Contacts and Gmail which will enhance its usability. Firstly,
Login Command is implemented so that the Contact’em can authenticate with the google servers when the user has successfully logged in.
The new GoogleAuthenticator class is created to run the authentication process.
The Login Command sequence diagram is as follows:
Figure 3.1.1 : Login command sequence diagram
The login page will be loaded in the browser panel after the login command has successfully executed. This is for the user to authenticate with google. Contact’em will then redirect the user to the Google contacts web page after successful authentication.
The GoogleContactsBuilder class can be instantiated to access the list of contacts from Google and also to obtain the PeopleService object needed to modify the contacts in Google. This is done by making use of the methods in the GoogleAuthenticator object to obtain the access token and PeopleService from Google.
The token required for authentication is obtained from the redirect url after logging in. This means that the user must stay on the Google contacts page in the browser panel when instantiating this class (For import / export / sync
commands). The class diagram for GoogleContactsBuilder is shown below.
Figure 3.1.1.1 : GoogleContactsBuilder class diagram
Every Person in the address book now has a new attribute known as the GoogleID. This ID refers to its own GoogleID in Google contacts. Contacts that are not synchronised with Google will have a null GoogleID.
After successful authentication, the user can proceed to import contacts from his google account. The import command creates a GoogleContactsBuilder object to retrieve the list of google contacts from the server.
The Import command sequence diagram is as follows:
Figure 3.1.2.1 : Import command sequence diagram
When the command is executed, the list of Google contacts will be looped through and compared with the contacts in Contact’em. If the GoogleID of a particular Google contact is not found in Contact’em, the contact will be imported. This is represented by the code snippet as shown below.
Pseudo-code snippet:
for each contact: googleContactsList {
if contact does not exists in Contact’em
model.addPerson(newPerson(contact))
}Scenario 1
The newPerson(…) method shown in the above code snippet successfully creates a Person object using attributes from the Google contact and it will be added to the address book. The GoogleID of the contact will also be instantiated within the new Person Object. The Person will also be given a GoogleContact Tag.
Scenario 2
The newPerson(…) method fails to create a Person object from the Google contact. The Google contact will fail to import. Reasons for the above mentioned failure includes,
1) Google contact might have invalid attributes. Eg: Invalid email format
2) Google contact might not have all attributes required to create a new Person object.
All the following attributes must be present: Name, Phone, Email and Address.
A message detailing the result of the command will be displayed to inform the user on the number of contacts imported or the number of contacts along with a string of names of contacts that failed to import.
After successful authentication, the user can next proceed to export contacts from Contact’em into his google account. The command creates a GoogleContactsBuilder object to retrieve peopleService from google which is required to modify/add contacts in Google contacts.
The Export command sequence diagram is as follows:
Figure 3.1.3.1 : Export command sequence diagram
When the command is executed, the list of contacts in Contact’em will be looped through to check whether they are a google contact. If they are not, they will be exported to Google contacts. This is represented by the code snippet shown below.
Pseudo-code snippet
for each contact: addressBookList{
if contact does not have a GoogleContact Tag
New googleContact = createGoogleContact (contact);
googleContact = builder.getPeopleService().people() createContact(googleContact).
execute();
model.updatePerson(contact, newAddressBookContact(contact));
}Scenario 1
The createGoogleContact method shown in the above code snippet successfully creates a GooglePerson that will be exported to Google contacts. The export command will then update the contact by instantiating its GoogleID attribute retrieved from the newly created Google contact and adding a GoogleContacts tag to it.
Scenario 2
The contact might not be exported to Google due to the failure in connecting to Google servers. This is can be due to token expiring.
A message detailing the result of the command will be displayed to inform the user on the number of contacts imported or failed to import.
After successful authentication, the user can proceed to sync contacts in Contact’em. The sync command creates a GoogleContactsBuilder object to retrieve the list of Google contacts from the server. In this case, the contacts in Google contacts takes higher precedence and any changes to them will be updated to the contacts in Contact’em when the user syncs. However, any changes made to the contacts in the Contact’em will not be transferred to Google contacts when the user syncs but instead, its attribute will be restored to its original value.
The Sync command sequence diagram is as follows:
Figure 3.1.4.1 : Sync command sequence diagram
When the command is executed, the list of contacts in Contact’em will be looped through to check if they exists within the list of Google contacts. If they are, a Person object based on the Google contact will be created and it will be used to compare with the contact in the address book. This is represented by the code snippet shown below.
Pseudo-code snippet:
for each contact: addressBookList{
for each googlecontact : googleContactsList{
if contact shares a similar googleID with the googlecontact
exists = true;
if convertToAddress(googlecontact) is not the same as contact
model.updatePerson(contact, convertToAddress(googlecontact))
}
if contact is a google contact but exists == false
model.updatePerson(contact, removeGoogleContactStatus(contact));
}Scenario 1
The attributes of the contact are the same as itself in Google contacts. No synchronising will be done on that contact.
Scenario 2
The attributes of the contact are different from itself in Google contacts. A newly created contact will replace the previous contact as shown in the above code snippet in model.updatePerson(…).
Scenario 3
The format of the Google contact is invalid and hence no new Person is created for comparision with the contact in Contact’em. The contact in the Contact’em will not be synchronised.
Scenario 4
The contact in the Contact’em is thought to exist in Google contacts but is not found. The removeGoogleContactStatus() method shown in the above code snippet will remove the Google contact status of the contact.
A message detailing the result of the command will be displayed to inform the user on the number of contacts synced and the number of contacts along with a string of names of contacts that failed to sync.
Aspect: Storage of access token.
Alternative 1 (current choice): Users have to be on the Google contact web page in order to use the following commands : Import, Export, Sync. This is because the token is retrieved from the url every time the user uses the above mentioned commands.
Pros: Users will be able to inspect the contacts within the Google contacts and they will be able to update the contacts if the contacts fail to import or synchronise by referring to the warning messages displayed.
Cons: This might cause some inconvenience because the users have to re-login to use the above mentioned commands if they have switched pages in the browser panel.
Alternative 2: Stores the token within the program once the user has logged in.
Pros: More convenience for user as they do not have to stay on the Google contacts page whenever they want to use the above mentioned commands.
Cons: In the case when some contacts fail to synchronise or import, the user have to re-login anyway to check on the contacts in google. By doing so, the error message produced earlier on will be removed and the user does not have a reference to see which contact is not importing or synchronising.
Aspect: Precedence of Google contacts over Contact’em contacts in sync command
Alternative 1 (current choice): Google contacts takes higher precedence. Contacts updated in Google contacts will be synchronised to Contact’em.
Pros: This alternative allow users to update contacts in Google contacts on-the-go which can be synchronised to Contact’em next time they use it.
Cons: Contacts updated in Contact’em must be manually updated in the Google contacts as well. If not, next time when the user synchronises Contact’em, the changes will be removed.
Alternative 2: Contact’em takes higher precedence. Contacts updated in Contact’em will be synchronised to Google contacts.
Pros: This is better for user who uses Contact’em more often than Google contacts. For some, the contacts in Google contacts might just be an on-the-go reference and most updating is done within Contact’em.
Cons: Will not be able to update contacts if they are away from the computer.
End of Extract
The easyfind feature improves on the find feature. Contact’em now auto updates the results display whenever user inputs a letter with the find command word.
Find persons whose names contain any of the letters in the command box constantly having the user to input enter.
-
find Alex
ReturnsAlexandAlexandra -
find Alexan
ReturnsAlexandra -
find Bet Ti Jo
Returns any person having starting alphabetsBetsy,Tim, orJohn
Figure 5.5.1 : Example of usage of EasyFind feature
|
Note
|
Letters are case-insensitive. |
|
Note
|
Different letter sequences will be separated by a space . |
|
Note
|
As long as a letter in a contact’s name matches any of the keywords, that contact will be displayed. |
|
Note
|
When the search results displays no results , the letters will not match any contacts even when the user continues inputting new characters. |
End of Extract
One of the main functionality of Contact’em is to allow users to search for contacts. However, the current search command is extremely inefficient as users have to input entire first names or given names inorder to obtain the contact. Additionally, this search command does not aid the user in the event he has forgotten the exact name when searching for contacts. EasyFind solves the above mentioned problems by constantly updating the results display whenever the user inputs a letter when searching for a contact.
The EasyFind mechanism is an action driven task, which activates when the user tries to search for a contact by updating the search results whenever the user inputs a letter into the command box.
The mechanism is facilitated by a new command FindLettersCommand which will search for contacts matching the letters in the command box. The command is called every time the user inputs or remove a character from the command box while using the command Find.
The key release event of the command box is constantly searching for the term find and when the user inputs the mentioned term into the command box, the key release event will begin searching for contacts by passing the letters entered after the term find into FindLettersCommand.
The application will display the number of contacts that share the same letters as the input. The following images shows how the EasyFind mechanism is activated:
|
Note
|
After the user inputs enter, normal find command will be executed
|
|
Note
|
EasyFind mechanism is case insensitive |
The following sequence diagram shows how the FindLettersCommand works:
Figure 5.6.1 : Example of usage of EasyFind feature
Aspect: Intertwining of FindLettersCommand and FindCommand
Alternative 1 (current choice): Separate both commands.
Pros: We will not lose the original functionality of the FindCommand and creating a new FindLettersCommand allows the application to search for contacts more frequently when the EasyFind mechanism is activated.
Cons: This might confuse the user as the FindCommand and FindLettersCommand could generate different results. The contact that the user is searching for may be displayed when a partial name is inputted. However, when the user inputs enter before typing in the full name, the displayed contact will be removed by the original FindCommand
Alternative 2: Replace FindCommand with FindLettersCommand
Pros: The results displayed will not change even after the user has pressed enter. It can also help the user to speed up the process of searching for contacts as they user does not have to input the full name
Cons: Removing the find Command may affect other functions of the application.
End of Extract
Managing contacts is the main focus of our application. Hence, it would be more convenient for the user if they are able to delete multiple contacts at once. Additionally, contacts to be deleted can be displayed first before the user inputs enter. This can be implemented using the easy find implementation.