User manual FUNAMBOL DS SERVER MODULE DEVELOPMENT TUTORIAL 3.0

[. . . ] 4 Creating a Dummy SyncSource Configuration Panel . 9 Accessing Funambol Administration Tool . 10 Creating SQL Scripts for Registering the Module . 22 Creating a Dummy SyncSource Instance . [. . . ] The code is shown below: DummySyncSource. java: package sync4j. examples. engine. source; import java. security. Principal; import java. sql. Timestamp; import sync4j. framework. engine. source. *; import sync4j. framework. engine. *; /** * This class implements a dummy <i>SyncSource</i> that just displays the * calls to its methods * * @author Stefano Fornari * * @version $Id: DummySyncSource. java, v 1. 3 2005/04/25 07:42:42 harrie Exp $ * */ public class DummySyncSource extends AbstractSyncSource implements SyncSource { private String name private String type private String sourceURI private private private private SyncItem[] SyncItem[] SyncItem[] SyncItem[] = null; = null; = null; = = = = null; null; null; null; allItems newItems deletedItems updatedItems // --------------------------------------------------------- Constructors /** Creates a new instance of AbstractSyncSource */ public DummySyncSource() { newItems = new SyncItem[] { createItem("10", "This is a new item", SyncItemState. NEW) }; deletedItems = new SyncItem[] { createItem("20", "This is a deleted item", SyncItemState. DELETED) }; updatedItems = new SyncItem[] { createItem("30", "This is an UPDATED item", 4 DS SERVER MODULE DEVELOPMENT TUTORIAL SyncItemState. UPDATED) }; allItems = new SyncItem[newItems. length + updatedItems. length + 1]; allItems[0] = createItem("40", "This is an unchanged item", SyncItemState. SYNCHRONIZED); allItems[1] = newItems[0]; allItems[2] = updatedItems[0]; } // ------------------------------------------------------- Public methods /** * Returns a string representation of this object. * * @return a string representation of this object. */ public String toString() { StringBuffer sb = new StringBuffer(super. toString()); sb. append(" - {name: "). append(getName() ); sb. append(" type: " ). append(getType() ); sb. append(" uri: " ). append(getSourceURI()); sb. append("}" ); return sb. toString(); } public SyncItem[] getAllSyncItems(Principal principal) throws SyncSourceException { System. out. println("getAllSyncItems(" + principal + ")"); return allItems; } public SyncItem[] getDeletedSyncItems(Principal principal, Timestamp since ) throws SyncSourceException { System. out. println("getDeletedSyncItems(" + principal + ", " + since + ")"); return deletedItems; } public SyncItemKey[] getDeletedSyncItemKeys(Principal principal, Timestamp since ) throws SyncSourceException { System. out. println("getDeletedSyncItemKeys(" + principal + ", " + since + ")"); return extractKeys(deletedItems); } public SyncItem[] getNewSyncItems(Principal principal, Timestamp since ) throws SyncSourceException { System. out. println("getNewSyncItems(" + principal + ", " + since + ")"); 5 DS SERVER MODULE DEVELOPMENT TUTORIAL return newItems; } public SyncItemKey[] getNewSyncItemKeys(Principal principal, Timestamp since ) throws SyncSourceException { System. out. println("getnewSyncItemKeys(" + principal + ", " + since + ")"); return extractKeys(newItems); } public SyncItem[] getUpdatedSyncItems(Principal principal, Timestamp since ) throws SyncSourceException { System. out. println("getUpadtedSyncItems(" + principal + ", " + since + ")"); return updatedItems; } public SyncItemKey[] getUpdatedSyncItemKeys(Principal principal, Timestamp since ) throws SyncSourceException { System. out. println("getUpadtedSyncItemKeys(" + principal + ", " + since + ")"); return extractKeys(updatedItems); } public void removeSyncItem(Principal principal, SyncItem syncItem) throws SyncSourceException { System. out. println("removeSyncItem(" + principal + ", " + syncItem. getKey(). getKeyAsString() + ")"); } public void removeSyncItems(Principal principal, SyncItem[] syncItems) throws SyncSourceException { System. out. println("removeSyncItems(" + principal + " , . . . )"); for(int i=0; i<syncItems. length; ++i) { removeSyncItem(principal, syncItems[i]); } } public SyncItem setSyncItem(Principal principal, SyncItem syncItem) throws SyncSourceException { System. out. println("setSyncItem(" + principal + ", " + syncItem. getKey(). getKeyAsString() + ")"); return new SyncItemImpl(this, syncItem. getKey(). getKeyAsString()+"- 6 DS SERVER MODULE DEVELOPMENT TUTORIAL 1"); } public SyncItem[] setSyncItems(Principal principal, SyncItem[] syncItems) throws SyncSourceException { System. out. println("setSyncItems(" + principal + " , . . . )"); SyncItem[] ret = new SyncItem[syncItems. length]; for (int i=0; i<syncItems. length; ++i) { ret[i] = setSyncItem(principal, syncItems[i]); } return ret; } public SyncItem[] getSyncItemsFromTwins(Principal principal, SyncItem[] twinItems) { System. out. println("getSyncItemsFromTwins(" + principal + ")"); return new SyncItem[0]; } public SyncItem getSyncItemFromTwin(Principal principal, SyncItem twinItem) { System. out. println("getSyncItemsFromTwin(" + principal + " , . . . )"); return null; } public SyncItem getSyncItemFromId(Principal principal, SyncItemKey syncItemKey) { System. out. println("getSyncItemsFromId(" + principal + ", " + syncItemKey + ")"); return null; } public SyncItem[] getSyncItemsFromIds(Principal principal, SyncItemKey[] syncItemKeys) { System. out. println("getSyncItemsFromIds(" + principal + ", . . . )"); return new SyncItem[0]; } // ------------------------------------------------------ Private methods private SyncItem createItem(String id, String content, char state) { SyncItem item = new SyncItemImpl(this, id, state); item. setProperty( new SyncProperty(SyncItem. PROPERTY_BINARY_CONTENT, content. getBytes()) ); return item; } private SyncItemKey[] extractKeys(SyncItem[] items) { SyncItemKey[] keys = new SyncItemKey[items. length]; for (int i=0; i<items. length; ++i) { keys[i] = items[i]. getKey(); } 7 DS SERVER MODULE DEVELOPMENT TUTORIAL return keys; } } The class structure (methods) reflects the SyncSource interface. In addition, it extends AbstractSyncSource so that it inherits common methods. For details, see the Funambol DS Server Developer's Guide. The constructor creates some note items that are stored in the instance variables newItems, deletedItems and updatedItems. * * @param syncSource the SyncSource instance */ public void updateForm() { if (!(getSyncSource() instanceof DummySyncSource)) { notifyError( new AdminException( "This is not an DummySyncSource!Unable to process SyncSource values. " ) ); return; } if (getState() == STATE_INSERT) { confirmButton. setText("Add"); } else if (getState() == STATE_UPDATE) { confirmButton. setText("Save"); } 12 DS SERVER MODULE DEVELOPMENT TUTORIAL this. syncSource = (DummySyncSource) getSyncSource(); sourceUriValue. setText(syncSource. getSourceURI() ); nameValue. setText (syncSource. getName() ); if (this. syncSource. getSourceURI() != null) { sourceUriValue. setEditable(false); } } // ------------------------------------------------------ Private methods /** * Checks if the values provided by the user are all valid. In caso of errors, * a IllegalArgumentException is thrown. * * @throws IllegalArgumentException if: * <ul> * <li>name, uri, type or directory are empty (null or zero-length) * <li>the types list length does not match the versions list length * </ul> */ private void validateValues() throws IllegalArgumentException { String value = null; value = nameValue. getText(); if (StringUtils. isEmpty(value)) { throw new IllegalArgumentException( "Field 'Name' cannot be empty. Please provide a SyncSource name. "); } if (!StringUtils. containsOnly(value, NAME_ALLOWED_CHARS. toCharArray())) { throw new IllegalArgumentException( "Only the following characters are allowed for field 'Name': \n" + NAME_ALLOWED_CHARS); } value = typeValue. getText(); if (StringUtils. isEmpty(value)) { throw new IllegalArgumentException( "Field 'Type' cannot be empty. Please provide a SyncSource type. "); } value = sourceUriValue. getText(); if (StringUtils. isEmpty(value)) { throw new IllegalArgumentException( "Field 'Source URI' cannot be empty. Please provide a SyncSource URI. "); } } /** * Set syncSource properties with the values provided by the user. */ private void getValues() { syncSource. setSourceURI (sourceUriValue. getText(). trim()); 13 DS SERVER MODULE DEVELOPMENT TUTORIAL syncSource. setName syncSource. setType (nameValue. getText(). trim() (typeValue. getText(). trim() ); ); ContentType[] contentTypes = new ContentType[] { new ContentType("text/plain", "1. 0") }; syncSource. setInfo(new SyncSourceInfo(contentTypes, 0)); } } 14 DS SERVER MODULE DEVELOPMENT TUTORIAL Creating SQL Scripts for Registering the Module To make the Funambol DS Server aware of the sample module, Connector, and SyncSource type, we will register these items in a database using SQL scripts. We can support multiple databases by storing the script(s) specific to each in the /src/sql/<database_vendor> directory, where database_vendor is the vendor's name. This name is also specified in the install. properties file, where it identifies the database the Funambol DS Server uses. For each database, we could create the following scripts: · · · drop_schema. sql ­ cleans up existing database tables, if any create_schema. sql ­ creates new database tables, if required init_schema. sql ­ populates the database For our sample module we do not need additional tables; the only required script is init_schema, which includes the following SQL statements: init_schema: --- SyncSource type registration -delete from sync4j_sync_source_type where id='dummy-1. 2'; insert into sync4j_sync_source_type(id, description, class, admin_class) values('dummy-1. 2', 'Dummy SyncSource', 'sync4j. examples. engine. source. DummySyncSource', 'sync4j. examples . admin. DummySyncSourceConfigPanel'); --- Module registration -delete from sync4j_module where id='dummy-1. 2'; insert into sync4j_module (id, name, description) values('dummy-1. 2', 'dummy-1. 2', 'Dummy 1. 2'); --- SyncConnector registration -delete from sync4j_connector where id='dummy-1. 2'; insert into sync4j_connector(id, name, description, admin_class) values('dummy-1. 2', 'Sync4jDummyConnector', 'Sync4j Dummy Connector', ''); --- The SyncSource type belongs to the SyncConnector -delete from sync4j_connector_source_type where connector='dummy-1. 2' and sourcetype='dummy-1. 2'; insert into sync4j_connector_source_type(connector, sourcetype) values('dummy-1. 2', 'dummy-1. 2'); --- The SyncConnector belongs to the module -delete from sync4j_module_connector where module='dummy-1. 2' and connector='dummy-1. 2'; insert into sync4j_module_connector(module, connector) values('dummy-1. 2', 'dummy-1. 2'); 15 DS SERVER MODULE DEVELOPMENT TUTORIAL The above SQL commands inform the Funambol DS Server there is a new module called dummy-1. 2, which contains a Connector called dummy-1. 2, which in turn contains a SyncSource type called dummy-1. 2. The SyncSource type is specified by the SyncSource class sync4j. examples. engine. source. DummySyncSource and the configuration panel by sync4j. examples. admin. DummySyncSourceConfigPanel. 16 DS SERVER MODULE DEVELOPMENT TUTORIAL Creating the Module Archive File In this step we will automate the process of compiling the classes and packing everything into module archive (for additional details on module archives, see Chapter 6 of the Funambol DS Server Developer's Guide). The internal structure of the archive file is shown below: We will use Jakarta Ant to build the module archive, but you can use your preferred tool or IDE, as long as you produce a single . s4j file and maintain the structure shown above. We will use the following build. xml file: 17 DS SERVER MODULE DEVELOPMENT TUTORIAL build. xml: <?html version="1. 0" enconding="UTF-8"?> <!-- $Id ======================================================= Build file for DummySyncSource. ======================================================= --> <project name="Sync4jServerDS" default="pack" basedir=". . "> <!-- Pick up the environment variables --> <property environment="ENV"/> <property file="build/build. properties"/> <!-- =============================================== --> <!-- Definitions --> <!-- =============================================== --> <property name="dir. lib" value="lib" /> <property name="dir. src" value="src" /> <property name="dir. src. sql" value="src/sql" /> <property name="dir. src. java" value="src/java" /> <property name="dir. src. bean" value="src/bean" /> <property name="dir. src. manifest" value="src/manifest" /> <property name="dir. src. properties" value="src/properties" /> <property name="dir. src. sql" value="src/sql" /> <property name="dir. src. xml" value="src/xml" /> <property name="dir. output" value="output" /> <property name="dir. output. javadoc" value="output/javadoc" /> <property name="dir. output. classes" value="output/classes" /> <property name="file. jar. config" value="config. jar" /> <property name="dummy. version" value="${dummy. release. major}. ${dummy. release. minor}. ${dummy. build. number}"/ > <property name="module. name" value="dummy-${dummy. version}"/> <!-- ============================================================== --> <!-- ================================================================ --> <!-- =============================================== --> <!-- USAGE --> <!-- =============================================== --> <target name="usage" depends="init"> <echo message=""/> <echo message="${project-name-text} build file"/> <echo message="-----------------------------------------------------"/> <echo <echo <echo <echo <echo <echo <echo <echo <echo </target> message=""/> message=" Available targets are :"/> message=""/> message=" usage --> help on usage"/> message=" build --> builds the project"/> message=" pack --> generates binary files"/> message=" clean --> cleans up the build directory"/> message=" env --> Displays the current environment"/> message=""/> 18 DS SERVER MODULE DEVELOPMENT TUTORIAL <!-- =============================================== --> <!-- ENV --> <!-- ================================================ --> <target name="env"> <echoproperties/> </target> <!-- ============================================================== --> <!-- ================================================================ --> <!-- =============================================== --> <!-- INIT --> <!-- =============================================== --> <target name="init"> <!-- Directory set up --> <mkdir dir="${dir. output. classes}"/> </target> <!-- =============================================== --> <!-- BUILD --> <!-- =============================================== --> <target name="build" depends="init"> <javac debug = "on" deprecation = "true" srcdir = "${dir. src. java}" destdir = "${dir. output. classes}" includeAntRuntime = "no" source = "1. 4" includes = "**/*java"> <classpath> <fileset dir="lib"> <include name="**/*. jar"/> </fileset> </classpath> </javac> </target> <!-- =============================================== --> <!-- PACK --> <!-- =============================================== --> <target name="pack" depends="build"> <property name="dir. module" value="${dir. output}/${module. name}"/> <!-Create the package directory structure --> <mkdir dir="${dir. module}/config"/> <mkdir dir="${dir. module}/sql"/> <mkdir dir="${dir. module}/lib"/> <!-- --> <copy todir = "${dir. module}/sql" preservelastmodified="true"> <fileset dir="${dir. src. sql}/"/> </copy> <!-The classes --> <jar jarfile = compress = update = jar "${dir. module}/lib/${module. name}. jar" "true" "true" 19 DS SERVER MODULE DEVELOPMENT TUTORIAL > <fileset dir="${dir. output. classes}"> <include name="**/*. class" /> </fileset> </jar> <!-The module jar --> <jar jarfile = "${dir. output}/${module. name}. s4j" compress = "true" update = "true" > <fileset dir="${dir. module}"> <include name="**/*" /> </fileset> </jar> <antcall target="clean-module"> <param name="dir. module" value="${dir. module}"/> </antcall> </target> <!-- =============================================== --> <!-- CLEAN --> <!-- =============================================== --> <target name="clean"> <delete dir = "${dir. output}"/> </target> <!-- =============================================== --> <!-- CLEAN-MODULE --> <!-- =============================================== --> <target name="clean-module" unless="debug"> <echo message="Cleaning ${dir. module}"/> <delete dir = "${dir. module}"/> </target> </project> To perform the build, go to the build directory and run the command (with Jakarta Ant in your path): $ ant 20 DS SERVER MODULE DEVELOPMENT TUTORIAL The output should appear similar to the following: The build process creates the directory \output containing the dummy-1. 2. x. s4j module archive file. 21 DS SERVER MODULE DEVELOPMENT TUTORIAL Installing the Module In this procedure we will use <DS-SERVER_HOME> to represent the directory containing the Funambol DS Server (e. g. , C:\Program Files\funambol\ds-server). 1. Copy the dummy-1. 2. x. s4j module archive file to the <DS-SERVER_HOME>\modules directory. 2. [. . . ] For example, after the first sync (which was a slow sync), therefore in the case of a fast sync, you will see something like. name=testdummy sourceClass=sync4j. syncclient. test. FileSystemSyncSource sourceDirectory=db/dummy type=clear/text sourceURI=testdummy 24 DS SERVER MODULE DEVELOPMENT TUTORIAL Resources This section lists resources you may find useful. Related Documentation This section lists documentation resources you may find useful. Funambol DS Server Documentation The following documents form the Funambol DS Server documentation set: · Funambol DS Server Administration Guide: Read this guide to gain an understanding of installation, configuration, and administration. Funambol DS Server Developer's Guide: Read this guide to understand how to develop extensions to the server. Funambol DS Server Quick Start Guide: Read this guide to install and run a simple demonstration of synchronizing PIM data using the Funambol DS Server. [. . . ]