From 9cd4d4c603ef657808510de093582427cc3e9fde Mon Sep 17 00:00:00 2001 From: macdonst Date: Tue, 19 Oct 2010 04:05:36 +0800 Subject: [PATCH] Adding comments to Contact code --- framework/assets/js/contact.js | 132 +++++++++++++++++- .../src/com/phonegap/ContactAccessor.java | 21 ++- .../com/phonegap/ContactAccessorSdk3_4.java | 75 +++++++++- .../src/com/phonegap/ContactAccessorSdk5.java | 81 ++++++++++- 4 files changed, 290 insertions(+), 19 deletions(-) diff --git a/framework/assets/js/contact.js b/framework/assets/js/contact.js index 96f948cd..5658d5e1 100644 --- a/framework/assets/js/contact.js +++ b/framework/assets/js/contact.js @@ -1,4 +1,37 @@ +/** + * PhoneGap is available under *either* the terms of the modified BSD license *or* the + * MIT License (2008). See http://opensource.org/licenses/alphabetical for full text. + * + * Copyright (c) 2005-2010, Nitobi + * Copyright (c) 2010, IBM Corporation + */ +/** +* Contains information about a single contact. +* @param {DOMString} id unique identifier +* @param {DOMString} displayName +* @param {ContactName} name +* @param {DOMString} nickname +* @param {ContactField[]} phoneNumbers array of phone numbers +* @param {ContactField[]} emails array of email addresses +* @param {ContactAddress[]} addresses array of addresses +* @param {ContactField[]} ims instant messaging user ids +* @param {ContactOrganization[]} organizations +* @param {DOMString} published date contact was first created +* @param {DOMString} updated date contact was last updated +* @param {DOMString} birthday contact's birthday +* @param (DOMString} anniversary contact's anniversary +* @param {DOMString} gender contact's gender +* @param {DOMString} note user notes about contact +* @param {DOMString} preferredUsername +* @param {ContactField[]} photos +* @param {ContactField[]} tags +* @param {ContactField[]} relationships +* @param {ContactField[]} urls contact's web sites +* @param {ContactAccounts[]} accounts contact's online accounts +* @param {DOMString} utcOffset UTC time zone offset +* @param {DOMString} connected +*/ var Contact = function(id, displayName, name, nickname, phoneNumbers, emails, addresses, ims, organizations, published, updated, birthday, anniversary, gender, note, preferredUsername, photos, tags, relationships, urls, accounts, utcOffset, connected) { @@ -27,7 +60,11 @@ var Contact = function(id, displayName, name, nickname, phoneNumbers, emails, ad this.connected = connected || null; }; - +/** +* Removes contact from device storage. +* @param successCB success callback +* @param errorCB error callback +*/ Contact.prototype.remove = function(successCB, errorCB) { if (this.id == null) { var errorObj = new ContactError(); @@ -38,16 +75,34 @@ Contact.prototype.remove = function(successCB, errorCB) { PhoneGap.execAsync(successCB, errorCB, "Contacts", "remove", [this.id]); }; +/** +* Creates a deep copy of this Contact. +* With the contact ID set to null. +* @return copy of this Contact +*/ Contact.prototype.clone = function() { var clonedContact = PhoneGap.clone(this); clonedContact.id = null; return clonedContact; }; -Contact.prototype.save = function(win, fail) { +/** +* Persists contact to device storage. +* @param successCB success callback +* @param errorCB error callback +*/ +Contact.prototype.save = function(successCB, errorCB) { }; - +/** +* Contact name. +* @param formatted +* @param familyName +* @param givenName +* @param middle +* @param prefix +* @param suffix +*/ var ContactName = function(formatted, familyName, givenName, middle, prefix, suffix) { this.formatted = formatted || null; this.familyName = familyName || null; @@ -57,12 +112,27 @@ var ContactName = function(formatted, familyName, givenName, middle, prefix, suf this.honorificSuffix = suffix || null; }; +/** +* Generic contact field. +* @param type +* @param value +* @param primary +*/ var ContactField = function(type, value, primary) { this.type = type || null; this.value = value || null; this.primary = primary || null; }; +/** +* Contact address. +* @param formatted +* @param streetAddress +* @param locality +* @param region +* @param postalCode +* @param country +*/ var ContactAddress = function(formatted, streetAddress, locality, region, postalCode, country) { this.formatted = formatted || null; this.streetAddress = streetAddress || null; @@ -72,6 +142,16 @@ var ContactAddress = function(formatted, streetAddress, locality, region, postal this.country = country || null; }; +/** +* Contact organization. +* @param name +* @param dept +* @param title +* @param startDate +* @param endDate +* @param location +* @param desc +*/ var ContactOrganization = function(name, dept, title, startDate, endDate, location, desc) { this.name = name || null; this.department = dept || null; @@ -82,23 +162,44 @@ var ContactOrganization = function(name, dept, title, startDate, endDate, locati this.description = desc || null; }; +/** +* Contact account. +* @param domain +* @param username +* @param userid +*/ var ContactAccount = function(domain, username, userid) { this.domain = domain || null; this.username = username || null; this.userid = userid || null; } +/** +* Represents a group of Contacts. +*/ var Contacts = function() { this.inProgress = false; this.records = new Array(); } - -Contacts.prototype.find = function(fields, win, fail, options) { +/** +* Returns an array of Contacts matching the search criteria. +* @param fields that should be searched +* @param successCB success callback +* @param errorCB error callback +* @param {ContactFindOptions} options that can be applied to contact searching +* @return array of Contacts matching search criteria +*/ +Contacts.prototype.find = function(fields, successCB, errorCB, options) { PhoneGap.execAsync(win, fail, "Contacts", "search", [fields, options]); }; -//This function does not create a new contact in the db. -//Must call contact.save() for it to be persisted in the db. +/** +* This function creates a new contact, but it does not persist the contact +* to device storage. To persist the contact to device storage, invoke +* contact.save(). +* @param properties an object who's properties will be examined to create a new Contact +* @returns new Contact object +*/ Contacts.prototype.create = function(properties) { var contact = new Contact(); for (i in properties) { @@ -109,6 +210,13 @@ Contacts.prototype.create = function(properties) { return contact; }; +/** + * ContactFindOptions. + * @param filter used to match contacts against + * @param multiple boolean used to determine if more than one contact should be returned + * @param limit maximum number of results to return from the contacts search + * @param updatedSince return only contact records that have been updated on or after the given time + */ var ContactFindOptions = function(filter, multiple, limit, updatedSince) { this.filter = filter || ''; this.multiple = multiple || false; @@ -116,10 +224,17 @@ var ContactFindOptions = function(filter, multiple, limit, updatedSince) { this.updatedSince = updatedSince || ''; }; +/** + * ContactError. + * An error code assigned by an implementation when an error has occurred + */ var ContactError = function() { this.code=null; }; +/** + * Error codes + */ ContactError.UNKNOWN_ERROR = 0; ContactError.INVALID_ARGUMENT_ERROR = 1; ContactError.NOT_FOUND_ERROR = 2; @@ -129,6 +244,9 @@ ContactError.IO_ERROR = 5; ContactError.NOT_SUPPORTED_ERROR = 6; ContactError.PERMISSION_DENIED_ERROR = 20; +/** + * Add the contact interface into the browser. + */ PhoneGap.addConstructor(function() { if(typeof navigator.service == "undefined") navigator.service = new Object(); if(typeof navigator.service.contacts == "undefined") navigator.service.contacts = new Contacts(); diff --git a/framework/src/com/phonegap/ContactAccessor.java b/framework/src/com/phonegap/ContactAccessor.java index fab36964..7cb2ded0 100644 --- a/framework/src/com/phonegap/ContactAccessor.java +++ b/framework/src/com/phonegap/ContactAccessor.java @@ -86,18 +86,30 @@ public abstract class ContactAccessor { return sInstance; } + /** + * Check to see if the data associated with the key is required to + * be populated in the Contact object. + * @param key + * @param map created by running buildPopulationSet. + * @return true if the key data is required + */ protected boolean isRequired(String key, HashMap map) { Boolean retVal = map.get(key); return (retVal == null) ? false : retVal.booleanValue(); } - protected HashMap buildPopulationSet(JSONArray filter) { + /** + * Create a hash map of what data needs to be populated in the Contact object + * @param fields the list of fields to populate + * @return the hash map of required data + */ + protected HashMap buildPopulationSet(JSONArray fields) { HashMap map = new HashMap(); String key; try { - for (int i=0; i dbMap = new HashMap(); static { dbMap.put("id", People._ID); @@ -73,6 +76,9 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { dbMap.put("note", People.NOTES); } + /** + * Create an contact accessor. + */ public ContactAccessorSdk3_4(WebView view, Activity app) { mApp = app; @@ -80,7 +86,14 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { } @Override - public JSONArray search(JSONArray filter, JSONObject options) { + /** + * This method takes the fields required and search options in order to produce an + * array of contacts that matches the criteria provided. + * @param fields an array of items to be used as search criteria + * @param options that can be applied to contact searching + * @return an array of contacts + */ + public JSONArray search(JSONArray fields, JSONObject options) { String searchTerm = ""; int limit = 1; boolean multiple = false; @@ -102,8 +115,8 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { ContentResolver cr = mApp.getContentResolver(); - Set contactIds = buildSetOfContactIds(filter, searchTerm); - HashMap populate = buildPopulationSet(filter); + Set contactIds = buildSetOfContactIds(fields, searchTerm); + HashMap populate = buildPopulationSet(fields); Iterator it = contactIds.iterator(); @@ -162,13 +175,20 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { return contacts; } - private Set buildSetOfContactIds(JSONArray filter, String searchTerm) { + /** + * Query the database using the search term to build up a list of contact ID's + * matching the search term + * @param fields + * @param searchTerm + * @return a set of contact ID's + */ + private Set buildSetOfContactIds(JSONArray fields, String searchTerm) { Set contactIds = new HashSet(); String key; try { - for (int i=0; i contactIds, Uri uri, String projection, String selection, String[] selectionArgs) { ContentResolver cr = mApp.getContentResolver(); @@ -252,6 +281,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { cursor.close(); } + /** + * Create a ContactField JSONArray + * @param cr database access object + * @param contactId the ID to search the database for + * @return a JSONArray representing a set of ContactFields + */ private JSONArray imQuery(ContentResolver cr, String contactId) { String imWhere = ContactMethods.PERSON_ID + " = ? AND " + ContactMethods.KIND + " = ?"; @@ -277,6 +312,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { return null; } + /** + * Create a ContactOrganization JSONArray + * @param cr database access object + * @param contactId the ID to search the database for + * @return a JSONArray representing a set of ContactOrganization + */ private JSONArray organizationQuery(ContentResolver cr, String contactId) { String orgWhere = ContactMethods.PERSON_ID + " = ?"; String[] orgWhereParams = new String[]{contactId}; @@ -302,6 +343,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { return organizations; } + /** + * Create a ContactAddress JSONArray + * @param cr database access object + * @param contactId the ID to search the database for + * @return a JSONArray representing a set of ContactAddress + */ private JSONArray addressQuery(ContentResolver cr, String contactId) { String addrWhere = ContactMethods.PERSON_ID + " = ? AND " + ContactMethods.KIND + " = ?"; @@ -323,6 +370,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { return addresses; } + /** + * Create a ContactField JSONArray + * @param cr database access object + * @param contactId the ID to search the database for + * @return a JSONArray representing a set of ContactFields + */ private JSONArray phoneQuery(ContentResolver cr, String contactId) { Cursor cursor = cr.query( Phones.CONTENT_URI, @@ -345,6 +398,12 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { return phones; } + /** + * Create a ContactField JSONArray + * @param cr database access object + * @param contactId the ID to search the database for + * @return a JSONArray representing a set of ContactFields + */ private JSONArray emailQuery(ContentResolver cr, String contactId) { Cursor cursor = cr.query( ContactMethods.CONTENT_EMAIL_URI, @@ -375,6 +434,10 @@ public class ContactAccessorSdk3_4 extends ContactAccessor { } @Override + /** + * This method will remove a Contact from the database based on ID. + * @param id the unique ID of the contact to remove + */ public boolean remove(String id) { int result = mApp.getContentResolver().delete(People.CONTENT_URI, "people._id = ?", diff --git a/framework/src/com/phonegap/ContactAccessorSdk5.java b/framework/src/com/phonegap/ContactAccessorSdk5.java index 6ac156dd..8df076c1 100644 --- a/framework/src/com/phonegap/ContactAccessorSdk5.java +++ b/framework/src/com/phonegap/ContactAccessorSdk5.java @@ -51,6 +51,9 @@ import android.webkit.WebView; */ public class ContactAccessorSdk5 extends ContactAccessor { + /** + * A static map that converts the JavaScript property name to Android database column name. + */ private static final Map dbMap = new HashMap(); static { dbMap.put("id", ContactsContract.Contacts._ID); @@ -102,11 +105,21 @@ public class ContactAccessorSdk5 extends ContactAccessor { //dbMap.put("connected", null); } + /** + * Create an contact accessor. + */ public ContactAccessorSdk5(WebView view, Activity app) { mApp = app; mView = view; } + /** + * This method takes the fields required and search options in order to produce an + * array of contacts that matches the criteria provided. + * @param fields an array of items to be used as search criteria + * @param options that can be applied to contact searching + * @return an array of contacts + */ @Override public JSONArray search(JSONArray fields, JSONObject options) { long totalEnd; @@ -271,6 +284,18 @@ public class ContactAccessorSdk5 extends ContactAccessor { return contacts; } + /** + * Create a new contact using a JSONObject to hold all the data. + * @param contact + * @param organizations array of organizations + * @param addresses array of addresses + * @param phones array of phones + * @param emails array of emails + * @param ims array of instant messenger addresses + * @param websites array of websites + * @param relationships array of relationships + * @return + */ private JSONObject populateContact(JSONObject contact, JSONArray organizations, JSONArray addresses, JSONArray phones, JSONArray emails, JSONArray ims, JSONArray websites, JSONArray relationships) { @@ -289,7 +314,13 @@ public class ContactAccessorSdk5 extends ContactAccessor { return contact; } - private WhereOptions buildWhereClause(JSONArray filter, String searchTerm) { + /** + * Take the search criteria passed into the method and create a SQL WHERE clause. + * @param fields the properties to search against + * @param searchTerm the string to search for + * @return an object containing the selection and selection args + */ + private WhereOptions buildWhereClause(JSONArray fields, String searchTerm) { ArrayList where = new ArrayList(); ArrayList whereArgs = new ArrayList(); @@ -307,8 +338,8 @@ public class ContactAccessorSdk5 extends ContactAccessor { String key; try { - for (int i=0; i