Adding new contact fields in Funambol

Another 2 weeks into Funambol and this time the work is little different, more interesting and more challenging. The task at hand is to add a new field under new contacts in Funambol. Previously I had mentioned how to enable the already supported fields of Funambol in the web demo and I was able to enable the Nickname under new contacts. This time we doing something similar. When we create a new contact in BlackBerry, henceforth to be called as client or BB, we see an extra field called PIN which is specific to BB only. Funambol doesn't know about this. In this post we will see how we can create a PIN support in our locally installed funambol server, henceforth to be called server. In other words, I should be able to send and receive contacts including the PIN field from client to sever and vice-versa.

We will assume that we have a working funambol server installed in the PC and Funambol source code in local hard drive. There are three things through which we can accomplish the addition of new field. First, we need to create a new attribute in the contact class structure called Pin. Second, we need to add an additional column in the database for storing PIN against all contacts. Third, we need to change the webdemo front end to expose the PIN field to user and send/receive PIN from user to backend and vice versa.

Module -1: Adding PIN attribute. The java files are in \funambol\common\pim-framework\src\main\java\com\funambol\common\pim

Step-1: In file PersonalDetail.java, add a new attribute "private String rim_pin;" going by the same format as other fields there, like gender. You'd add getPin(), setPin() etc.
Step-2: we'll edit SIFC.java, SIFCParser.java and ContactToSIFC.java to enable PIN field in incoming/outgoing SIFC, going by the same format as other fields in there like NICKNAME, ANNIVERSARY etc.
Step-3: We'll edit ContactToVcard.java going by the same format as other PersonalDetail attributes. So, we'll add a method "composeFieldPin" which should be like this,

/**
*
* @return a representation of the vCard field X-RIM-PIN
*/
private String composeFieldPin(String pin) {
if (pin != null) {
return "X-RIM-PIN:" + escapeSeparator(pin) + newLine;
}
return "";
}

This is because the tag name standard for PIN in Vcard is X-RIM-PIN so when we are converting contacts in server to vcard for sending it to client, the pin data must be against X-RIM-PIN tag. This will enable the client which will know that it has received a PIN value and so when you see the corressponding contact in client, the PIN field will contain the value that you had set in the server.
Next we will edit VCardSyntaxParserListenerImpl.java and add code for pin going by the same format as there are codes for other fields in there. Now all the X-* fields in the vcard that the server receives from the client, they are added to a XTag list through "addExtension" method in this file. For interpreting the PIN, we will intercept this method. Add the following at the end of this method,

if(tagName.equalsIgnoreCase("X-RIM-PIN")|| tagName.equalsIgnoreCase("RIM-PIN")){
contact.getPersonalDetail().setPin(text);
}
Next we edit the VCardSyntaxParserListener.java in the same format as other fields.
Step-4: Build the changes. Go to pim-framework directory and run mvn package. One may need to modify test files as well if build fails. When its done, run mvn install so that the changes are reflected to other packages later.

Module -2: Adding PIN in database. Corresponding java files are in \funambol\modules\foundation\foundation-core-8.X.Y\src\main\java\com\funambol\foundation\items\dao

Step-5: Modify the PIMContactDAO.java changing the select and insert SQL query, adding the extra rim_pin field at the end. Just go by the same format as Gender field is handled in the file and add similar codes for rim_pin. One may also want to add rim_pin in the create table query in PIMContactDAOTest.java for checking including sql files in test folder.
Step-6: Edit the funambol.script file in hypersonic\data and in the query CREATE MEMORY TABLE FNBL_PIM_CONTACT( ... ) add RIM_PIN column at the end.
Step-7: Build this module, mvn package and then mvn install.

Module -3: Adding PIN in webdemo. Source files are in \funambol\modules\webdemo-module\webdemo-webapp

Step-8: Edit the PDIServlet.java adding rim_pin just like the way other fields are mentioned. Build this module.Edit the add.jsp and view.jsp in \tomcat\webapps to show an extra text box field named rim_pin. Follow the other fields mentioned in the files and rim_pin can be added in the same way.
Step-9: Replace all the libraries that were created from build into corresponding places in local server directory. Replace the class files in webdemo module with that generated after the build like PDIServlet.class.
Step-10: Restart the server and try creating a new contact in webdemo, give some value in pin field. Sync with client. open the same contact in client the see the pin field populated. Similarly create a new contact in BB and sync, then see the contact in webdemo(server side) and find the pin field as given in BB.

Helpful references:
https://core.forge.funambol.org/ds/viewMessage.do?dsForumId=405&dsMessageId=126575
https://core.forge.funambol.org/ds/viewMessage.do?dsForumId=405&dsMessageId=125104
https://core.forge.funambol.org/wiki/HowToHackWebdemo?highlight=%28CategoryHowTo%29