Funambol DS Server

Module Development Guide

Version 3.0 April 2006

Important Information

Copyright Funambol, Inc. 2006. All rights reserved. The information contained in this publication is subject to US and international copyright laws and treaties. Except as permitted by law, no part of this document may be reproduced or transmitted by any process or means without the prior written consent of Funambol, Inc. Funambol, Inc. has taken care in preparation of this publication, but makes no expressed or implied warranty of any kind. Funambol, Inc. does not guarantee that any information contained herein is and will remain accurate or that use of the information will ensure correct and faultless operation of the relevant software, service or equipment. Funambol, Inc., its agents and employees shall not be held liable for any loss or damage whatsoever resulting from reliance on the information contained herein. Funambol and Sync4j are trademarks and registered trademarks of Funambol, Inc. All other products mentioned herein may be trademarks of their respective companies. Published by Funambol, Inc., 643 Bair Island Road, Suite 305, Redwood City, CA 94063
DS SERVER MODULE DEVELOPMENT TUTORIAL

Contents

Introduction. 1
Module Development Overview. 1 Prerequisites. 2 Obtaining the Tutorial Software. 2
Creating the Module Source Directory Structure. 3 Creating a Dummy SyncSource Type. 4

Reviewing the Code. 4

Creating a Dummy SyncSource Configuration Panel. 5
Using the Administration Tool. 5 Creating the Configuration Panel. 6
Creating SQL Scripts for Registering the Module. 7 Creating the Module Archive File. 9 Installing the Module. 11 Creating a Dummy SyncSource Instance. 12 Testing the Module with a SyncML Client. 13 Resources. 15
Related Documentation. 15 Other Resources. 15

Introduction

This document describes how to create a module that extends the functionality of the Funambol DS Server. For example, a module may consist of a packaged set of files, including classes, configuration files, server beans, and initialization SQL scripts, that are embedded into the Funambol DS Server to provide access to a specific database for data synchronization. In general, a module can be viewed as a container for anything related to server extensions. We will use the following terms and concepts in developing the sample module: Connector: A server extension that provides support for data synchronization with a specific data source. For example, the Funambol Visual DB Connector provides a GUI and runtime classes for the synchronization of generic data stored in a RDMS. Alternatively, a Connector could support a data source that stores email messages, calendar events, or other data types. SyncSource: A key component of a Connector, it defines the way a set of data is made accessible to the Funambol DS Server for synchronization. A SyncSource type is a template from which an instance of a SyncSource is created. For example, the FileSystemSyncSource type defines how data stored in directories in a file system can be accessed by the Funambol DS Server. This SyncSource type does not represent a specific instance of the FileSystemSyncSource, so it does not identify a directory to be used for synchronization. To specify such a directory, you create an instance of the FileSystemSyncSource and configure it with the desired directory. For additional information, see the Funambol DS Server Developers Guide. This tutorial will guide you through the development, packaging, installation and testing of a module. The module contains a simple SyncSource and is comprised of code classes, configuration files and database initialization scripts.

Module Development Overview
We will develop the sample module using the steps below:
1. Create the following, in sequence:
Module source directory structure Dummy SyncSource type Dummy SyncSource configuration panel SQL scripts for registering the module Module archive file
2. Install the module 3. Create a SyncSource instance 4. Test the module with a SyncML client

Prerequisites

This tutorial assumes a working knowledge of Java, Ant and SQL. The system requirements are as follows: Funambal DS Server Funambol Java Command Line Client Example Java 2 SDK version 1.4.x Jakarta Ant
Obtaining the Tutorial Software
Files used in developing the sample module are available for download from the following site:
http://forge.objectweb.org/project/download.php?group_id=96&file_id=5868
Creating the Module Source Directory Structure
Unzip the compressed file in a directory of your choice. The structure containing the source, configuration and script files will be created as follows:
Creating a Dummy SyncSource Type
The SyncSource type is the primary component of the module; it defines the way a set of data is made accessible to the Funambol DS Server for synchronization. We will use the SyncSource type as a template for implementing an instance of a SyncSource later in the tutorial. Our component, DummySyncSource, is a simple example; it only displays a message when one of its methods is called, and it always returns the same items. The sample code for DummySyncSource is in the \dummy\src\java\com\funambol\examples\engine\source directory.

Reviewing the Code

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 Developers Guide. The constructor creates some note items that are stored in the instance variables newItems, deletedItems and updatedItems. These are returned when requested by get[All/Updated/ New/Deleted]Items(). Items are created in createItem(): given the item identifier (the item key), the content and the state, it instantiates a new SyncItemImpl (a simple implementation of the SyncItem interface) and sets the BINARY_PROPERTY to the note content.

Creating a Dummy SyncSource Configuration Panel
You use the Administration Tool to configure a SyncSource. In this section we briefly introduce the Administration Tool, then we will create an extension specifically for configuring the Dummy SyncSource.
Using the Administration Tool
To start the Administration Tool, perform the following:
1. Start the Funambol DS Server by selecting Start > All Programs > Funambol >
Data Synchronization Server > Start.
2. Start the Administration Tool by selecting Start > All Programs > Funambol >
Administration Tool. The Administration Tool window displays.
3. On the Main Menu bar, select File > Login. The Login window displays. Verify the fields
are populated as follows, or specify these values: Hostname/IP: Port: User name: Password: <localhost> (should be your machine name)

8080 admin sa

Click Login. The Output window in the lower pane should display "connected."
4. To configure a SyncSource, navigate in the left pane to the desired SyncSource. For
example, to configure a File System SyncSource, expand the localhost tree as follows: localhost > Modules > pdi > FunambolPDIConnector, then select FileSystem SyncSource. The Edit File System SyncSource screen displays, as shown below:
You use this screen to specify configuration values and add an instance of the SyncSource type. We will create a screen similar to this for the Dummy SyncSource.
Creating the Configuration Panel
To create a configuration panel for Dummy SyncSource, we create an extension of sync4j.syncadmin.ui.SourceManagementPanel and call it DummySyncSourceConfigPanel.java. The sample code for DummySyncSourceConfigPanel is in the \dummy\src\java\com\funambol\examples\admin directory.
Creating SQL Scripts for Registering the Module
To make the Funambol DS Server aware of a module containing a connector and SyncSource type, we register these items in the Sync4j database using SQL scripts. You can support multiple databases by storing the script(s) specific to each in the \dummy\src\sql\<database_vendor> directory, where database_vendor is the vendors 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 will use Hypersonic. The only required script for the tutorial is init_schema, which includes the following SQL statements:
init_schema: --- Initialization data for the Dummy module -- @version $Id: init_schema.sql,v 1.1 2006/01/18 16:04:56 luigia Exp $ ---- Module structure registration -delete from fnbl_sync_source_type where id='dummy'; insert into fnbl_sync_source_type(id, description, class, admin_class) values('dummy','Dummy SyncSource', 'com.funambol.examples.engine.source.DummySyncSource', 'com.funambol.examples.admin.DummySyncSourceConfigPanel'); delete from fnbl_module where id='dummy'; insert into fnbl_module (id, name, description) values('dummy','dummy','Dummy'); delete from fnbl_connector where id='dummy'; insert into fnbl_connector(id, name, description, admin_class) values('dummy','FunambolDummyConnector','Funambol Dummy Connector',''); delete from fnbl_connector_source_type where connector='dummy' and sourcetype='dummy'; insert into fnbl_connector_source_type(connector, sourcetype) values('dummy','dummy'); delete from fnbl_module_connector where module='dummy' and connector='dummy'; insert into fnbl_module_connector(module, connector) values('dummy','dummy');
The SQL commands inform the Funambol DS Server there is a new module called dummy, which contains a Connector called dummy, which in turn contains a SyncSource type called dummy. The SyncSource type is specified by the SyncSource class com.funambol.examples.engine.source.DummySyncSource and the configuration panel by com.funambol.examples.admin.DummySyncSourceConfigPanel.
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. Sample code for the build file we will use, build.xml, is available in the \dummy\build directory.
To perform the build, go to the \dummy\build directory and run the command (with Jakarta Ant in your path):

> ant

The output should appear similar to the following:
The build process creates the directory \output containing the dummy-3.0.2.s4j module archive file.

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-3.0.2.s4j module archive file to the <DS_SERVER_HOME>\modules

directory.

2. Using a text editor, open the <DS_SERVER_HOME>\install.properties file. 3. Find the line that begins modules-to-install= in the Module definitions section. This
line specifies, in a comma-separated list, the modules to install during installation.
4. Add dummy-3.0.2 to the comma-separated list (without the.s4j filename extension). 5. Save and close install.properties. 6. On Windows, open a command prompt window by selecting Start > All Programs >
Accessories > Command Prompt and run the server installation script by typing the following at the prompt:
cd <DS_SERVER_HOME> bin\install <application_server>
Alternatively, you can install just the modules with the following command:
bin\install-modules <application_server>
Unix/Linux: use the command bin/install.sh <application_server> or bin/ install-modules.sh <application_server>.
Creating a Dummy SyncSource Instance
We will use the Administration Tool to create an instance of Dummy SyncSource, as follows:
2. Start the Funambol Administration tool by selecting Start > All Programs > Funambol >
are populated as follows, or specify these values: Hostname/IP: Port: User name: Password:
<localhost> (should be your machine name) 8080 admin sa
Click Login. The Output Window in the lower right pane should display "connected."
4. In the left pane, expand the localhost tree as follows: localhost > Modules > dummy >
FunambolDummyConnector, then select Dummy SyncSource. The Edit Dummy SyncSource screen displays in the right pane, as shown below:
5. Specify the following field values:

Source URI: Name: Type:

6. Click Add.
testdummy testdummy text/plain
Testing the Module with a SyncML Client
To test the module with a SyncML client, perform the following:
1. Download the Funambol Java Command Line Client Example and unpack the archive. 2. Copy the file \dummy\examples\dummy.properties to the \cl-client\config\spds\sources directory. Make sure there are no other properties

files in this directory.

3. Create the directory \cl-client\db\dummy. 4. Verify the JAVA_HOME environment property is set correctly. 5.
Execute run.cmd (or run.sh inLinux). The output should appear similar to the following:

If successful, the \db\dummy directory contains three new files named 10, 30 and 40; these are the items generated by Dummy SyncSource. You can also inspect the content to verify that it corresponds to the text set in the SyncSource code.
You can also view the synchronization results in the server log:

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 Developers 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. Funambol DS Server Module Development Tutorial: This document.

Other Resources

This section lists other resources you may find useful. For information on Java 2 Standard Edition, visit http://java.sun.com/j2se. For information on Java 2 Enterprise Edition, visit http://java.sun.com/j2ee. For information on JBoss, visit http://www.jboss.org. For information on Apache Tomcat, visit http://jakarta.apache.org/tomcat.

Funambol DS Server

Administration Guide
Version 3.0 September 2006

Important Information

Copyright Funambol, Inc. 2006. All rights reserved. The information contained in this publication is subject to US and international copyright laws and treaties. Except as permitted by law, no part of this document may be reproduced or transmitted by any process or means without the prior written consent of Funambol, Inc. Funambol, Inc. has taken care in preparation of this publication, but makes no expressed or implied warranty of any kind. Funambol, Inc. does not guarantee that any information contained herein is and will remain accurate or that use of the information will ensure correct and faultless operation of the relevant software, service or equipment. Funambol, Inc., its agents and employees shall not be held liable for any loss or damage whatsoever resulting from reliance on the information contained herein. Funambol and Sync4j are trademarks and registered trademarks of Funambol, Inc. All other products mentioned herein may be trademarks of their respective companies. Published by Funambol, Inc., 643 Bair Island Road, Suite 305, Redwood City, CA 94063
DS SERVER ADMINISTRATION GUIDE

Contents

Chapter 1
Installation and Configuration. 1
Introduction. 2 Prerequisites. 2 Obtaining the Software. 3 Installing the Funambol DS Server. 4 Installing the Server With Bundled Software. 4 Installing the Server Without Bundled Software. 5 Installing the Funambol Administration Tool. 7 Starting and Stopping the Funambol DS Server. 8 Starting the Server. 8 Stopping the Server. 9 Starting and Stopping the Administration Tool. 10 Configuring the Funambol DS Server. 11 Specifying the Public IP Address. 11 Changing the Device-ID. 12 Changing the HTTP Server Port. 13 Changing the Database. 14

Chapter 2

Using the Funambol Administration Tool. 17
Introduction. 18 Main Window. 18 Server Login. 19 Server Settings. 21 Log Settings. 27 Managing Users. 30 Managing Devices. 32 Managing Principals. 34

Chapter 3

Managing Modules. 37
Understanding Modules. 38 Standard Modules. 39 Managing SyncSources. 40 Installing Modules. 41 Installing a Module. 41 Uninstalling a Module. 42

Chapter 4

Using the DB Connector. 43
Overview. 44 Using the DB Connector. 45 Adding a Table SyncSource. 47 Configuring a Single Table Synchronization. 49 Configuring a Partitioned Table Synchronization. 53

Chapter 5

Using the Email Connector and Inbox Listener. 57
Configuring the Email Connector. 58 Configuring the Officer. 58 Configuring the Connector. 59 Creating a SyncSource. 60 Modifying Log Settings. 62 Implementing the Inbox Listener. 63 Configuring the Inbox Listener. 63 Configuring the Log Level. 64 Starting and Stopping the Inbox Listener. 64 Managing the User Account Database. 65

Appendix A

Supplemental Information. 67
Resources. 68 Related Documentation. 68 Other Resources. 68 Default Databases. 69 Calendar. 69 Contacts. 69 Notes. 69 Tasks. 69 Briefcase. 70 Install Properties. 71 Connection Factory Sample. 72
Installation and Configuration
The chapter provides details for obtaining, installing, configuring and running the Funambol DS Server and the Funambol Administration Tool.

Topics

Introduction, page 2 Installing the Funambol DS Server, page 4 Starting and Stopping the Funambol DS Server, page 8 Configuring the Funambol DS Server, page 11

Introduction

This document is intended for those who manage the Funambol DS Server, and includes the following information: Installing and configuring the Funambol DS Server Installing and using the Funambol Administration Tool Managing Funambol Modules Managing Funambol Connectors

Once you have determined whether to download the bundle or individual components, and whether to use the stable or developer release, you can locate the appropriate download(s) for your operating system.
Installing the Funambol DS Server
This section describes how to install the Funambol DS Server and the Funambol Administration Tool.
Installing the Server With Bundled Software
When you install bundled software, the Funambol Administration Tool and prerequisite software are automatically installed with the server. Windows
1. Run the executable installation file. 2. Review the license agreement. To accept the terms, select the checkbox and click Next. 3. Accept the suggested Destination Folder, i.e., the \Funambol directory, that we will refer to as <FUNAMBOL_HOME> in this document. The installer will create subdirectories for
bundle components under the top-level directory, including a subdirectory for the Funambol DS Server that we will refer to as <DS_SERVER_HOME>, as shown below:
Note the prerequisite application server, Java runtime, and database will be installed in the <FUNAMBOL_HOME>\tools directory.
4. When prompted for a Program Group, specify Funambol (if not already specified). 5. At the completion of the installation, you are given the option to view the readme file and

to start the server.

If you choose to start the server, the Funambol icon (two circular arrows) appears in the system tray. The color of the icon indicates the status of the server. Green the server is running. Red the server is stopped. Yellow the server is starting, wait for the icon to become green to access the server.
If the Funambol icon is green, you can verify the server is running by pointing a browser to http://localhost:8080/funambol, where a welcome page to the Funambol DS Server should display. Linux
1. Execute the downloaded file in a shell as follows: > sh funambol-<version>.bin 2. Review the license agreement. To accept the terms, select the checkbox and click Next. 3. Specify a top-level directory in which to install the bundled software. If not specified, the installation defaults to funambol.
Installing the Server Without Bundled Software
This section assumes that you have an application server, JDK/JRE, and a JDBC-compliant database installed on your system, or will obtain and install those components. Windows and Unix / Linux
1. Unpack the compressed file. This creates a top-level directory named Funambol that we will refer to as <FUNAMBOL_HOME> in this document. The server is in the \ds-server subdirectory and we will refer to this subdirectory as <DS_SERVER_HOME>. 2. Using a text editor, open the <DS_SERVER_HOME>\install.properties file. Note that

> cd <FUNAMBOL_HOME>/admin > gunzip funambol-admin-<version>.tar.gz > tar xvf funambol-admin-<version>.tar
Starting and Stopping the Funambol DS Server
The methods for starting and stopping the Funambol DS Server depend on how the application server associated with the server starts and stops J2EE applications. In this section, we assume the Funambol DS Server is installed as a standalone application; therefore, when the Funambol DS Server is stopped, the entire application server is stopped, and when it is started, the entire application server is started.

Starting the Server

The following commands start the server: Bundled Installation Windows Start > All Programs > Funambol > Data Synchronization Server > Start Command line:
> cd <FUNMAMBOL_HOME> > sh tools/bin/funambol.sh start
Unbundled Installation Command line:
> cd <DS_SERVER_HOME> > bin\start.cmd

Unix / Linux

Command line:
> cd <DS_SERVER_HOME> > sh bin/start.sh
If you have installed the bundled software, when you start the server, the Funambol icon (two circular arrows) appears in the system tray. The color of the icon indicates the status of the server. Green the server is running. Red the server is stopped. Yellow the server is starting, wait for the icon to become green to access the server.
If the Funambol icon is green, you can verify the server is running by pointing a browser to http://localhost:8080/funambol, where a welcome page to the Funambol DS Server should display. You can also right-click the icon to open a menu that allows you to start or stop the server.
If you have installed the server as an individual component (not the bundled software), the Funambol icon does not display in the system tray.

Stopping the Server

Windows (bundled installation) The following actions stop the server: Start > All Programs > Funambol > Data Synchronization Server > Stop Right-click the icon in system tray and select Stop
When you right-click the icon in the system tray, you can also select Exit. This terminates the service with which you can see if the server is still running, but does not stop the server, and thus avoids stopping the server if the user disconnects from the desktop.
Unbundled Installation The method of stopping the Funambol DS Server depends on the application server. For JBoss, perform the following: If it is running in foreground, press Ctrl+C; if this fails, determine the process id and kill it with an operation system command or tool. For Tomcat 5.0.x, perform the following: Windows
> cd <CATALINA_HOME> > bin\shutdown.cmd
> cd <CATALINE_HOME> > bin/shutdown.sh
In either case, <CATALINA_HOME> is the Tomcat installation directory, i.e., <FUNAMBOL_HOME>\tools\tomcat.

Starting and Stopping the Administration Tool
To start the Administration Tool, perform the following: Windows
Start > All Programs > Funambol > Administration Tool
> cd <FUNAMBOL_HOME>/admin > bin/funamboladmin
To stop the Administration Tool, perform the following on the Administration Tool main menu:

File > Exit

Configuring the Funambol DS Server
This section describes the following Funambol DS Server configuration tasks: Specifying the Public IP Address Changing the Device-ID Changing the HTTP Server Port Changing the Database
To perform the first two tasks, you use the Administration Tool to modify the appropriate server JavaBean. Server JavaBeans are JavaBeans used server-side. A bean configuration is stored in a serialized form of the bean itself. In this way, a bean can be instantiated, configured and serialized to persist its configuration. Later, the bean can be deserialized in memory as a properly configured instance. For additional details on server JavaBeans, see the Funambol DS Server Developer's Guide. To perform the remaining tasks, you modify configuration or properties files.
Specifying the Public IP Address
The default installation provides access to the Funambol DS Server via the localhost; however, in most situations it is necessary to change the IP/hostname to access the server from a remote system. Before proceeding, see Introduction on page 18 for general information on using the Administration Tool, and Server Engine Parameters on page 22 for information on server JavaBeans. To change the IP/hostname, perform the following:
1. Start the DS Server. 2. Start the Administration Tool and login to the server. 3. In the navigation pane, expand the server and double-click Server settings. 4. In the Server Settings panel, locate the Server URI property, specify the desired IP address
or hostname and click Save. In the Output message pane, the message Server configuration saved. is displayed.

Changing the Device-ID

The Funambol distribution provides a a non-rewriting PipelineManagerGeneric server JavaBean, as well as a PipelineManager server JavaBean (the default); the latter implements the syncml-phone device-id override. You have to reset this property to the com/funambol/ server/engine/pipeline/PipelineManagerGeneric.xml server JavaBean to use real device-ids. Before proceeding, see Introduction on page 18 for general information on using the Administration Tool, and Server Engine Parameters on page 22 for information on server JavaBeans. To change the Pipeline Manager, perform the following:

In the bundled version, server.xml is in the <FUNAMBOL_HOME>\tools\tomcat\conf\ directory and contains additional comment lines shown below:
<!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8080 --> <!-- Funambol comment: don't modify or remove this Funambol comment! ##### -> <Connector port="8080" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" redirectPort="8443" acceptCount="100" debug="0" connectionTimeout="20000" disableUploadTimeout="true" /> <!-- Funambol comment: don't modify or remove this Funambol comment! ###### -> <!-- Note : To disable connection timeouts, set connectionTimeout value to 0 -->
These lines comment out the above example and are used by the Funambol icon in the system tray. JBoss Example
1. Access the deploy/http-invoker.sar/META-INF/jboss-service.xml file and change
any occurrence of port 8080 to the desired value.
2. Access the deploy/jbossweb-tomcatXX.sar/META-INF/jboss-service.xml file and
change any occurrence of port 8080 to the desired value.

3. Restart the server.

Changing the Database
The bundled distribution includes the Hypersonic database; however, you can use any JDBCcompliant database. We recommend that you use a database you are familiar with, or in a production environment, one that is most suitable. You can use either of the following methods to change the database: Modify the install properties file (recommended). Modify the application server specific database configuration.
To Modify the Install Properties File
1. Use a text editor to open the <DS_SERVER_HOME>\install.properties file. Note that
commented lines are preceded by the number (#) symbol.
2. Locate the line dbms= and specify the name of your JDBC-compliant database. 3. Locate the following lines and specify values appropriate for your database: jdbc.classpath= jdbc.driver= jdbc.url= jdbc.user= jdbc.password= 4. Save and close install.properties. For additional details on this file, see Install
5. Verify that your J2EE_HOME environment variable points to the top-level directory where your application server resides, and the JAVA_HOME environment variable points to the
6. Run the server installation script. Open a command prompt window and type the
7. Verify the server is running by pointing a browser to http://<server>:<port>/ funambol, where a welcome page to the Funambol DS Server should display.

Officer

Parameter Pipeline manager
Description Server JavaBean for the Pipeline Manager configuration. The Pipeline Manager constructs and manages input and output pipelines. It is configured with a list of components that build up the input pipeline, and a list of components that build up the output pipeline. A message processing pipeline modifies incoming and outgoing messages, i.e., the message is modified before it goes into the synchronization engine, and the message returned by the synchronization engine is changed before it is sent to the client. SyncSession handler. The session handler is the server component that handles the entire synchronization session. It defaults to com.funambol.server.session.SyncSessionHandler, but it can be replaced by the server JavaBean representing the custom component. Server JavaBean representing the persistent store manager, which is the component responsible of accessing the persistent store (i.e., the database used internally by the DS server). The default implementation is configured by the server JavaBean
com/funambol/server/store/ PersistentStoreManager.xml and stores and reads the data

Handler

Persistence store manager
to and from a JDBC database; a custom implementation can be configured by specifying a custom server bean. Server JavaBean for Device Inventory configuration. The Device Inventory component is responsible for storing information about devices and their capabilities. The default implementation is com/funambol/server/ inventory/PSDeviceInventory.xml, which uses the PersistentStoreManager to store and retrieves the devices and their capabilities.

Device inventory

Data transformer manager
Server JavaBean for Data Transformer Manager configuration. The Data transformer manager is the component responsible for applying transformations to the data provided by a connector. Common transformations are encoding of binary data (e.g., B64 encoding), encryptions, conversions between vcard/icalendar and SIF-C/SIF-E, and so on. The default is
com/funambol/server/engine/transformer/ DataTransformerManager.xml.
To specify configuration parameters, click Configure (see Data Transformer Manager Configuration Parameters on page 25). Strategy Server JavaBean representing a SyncStrategy object. The Strategy component is responsible for defining the behavior of the synchronization engine. One of the main roles of this component is to resolve the conflicts that may arise when the same information is modified by different sources. The default is com/funambol/server/engine/Strategy.xml. To specify configuration parameters, click Configure (see Strategy Configuration Parameters on page 26).

Parameter User manager

Description Server JavaBean representing the user manager. This component is responsible of accessing the user database. The default is com/funambol/server/admin/ DBUserManager.xml, which accesses the user in the local Funambol DS Server database. However, it can be customized in order to access a different database, such as a LDAP server. In that case, this parameter will reflect the custom server bean. The minimum MaxMsgSize supported by the server. If a client requests a MaxMsgSize less than this value, the request is rejected. When starting a synchronization, a device can tell the server not to send messages bigger than a certain byte amount; however, there is a lower limit under which the server may not be able to work. This limit can be influenced by some internal processing or by the amount of metadata the server needs to return. This parameter specifies the lower limit the server can accept.
Min. value for max. msg size
Click Save to save the configuration settings, or Cancel to quit without saving the settings.
Data Transformer Manager Configuration Parameters Parameter Transformers for incoming items Transformers for outgoing items Data transformations Description Specifies the name and class of transformers for incoming items. Specifies the name and class of transformers for outgoing items. Specifies the source URI of items that require transformation, and the name of the transformer to use.
Strategy Configuration Parameters These settings specify the conflict resolution the Funambol DS Server uses for SyncSources.
Parameter Default conflict resolution
Description Specifies the default conflict resolution; this setting applies to those SyncSources that do not need to be configured individually, and can be used to quickly switch the conflict resolution for all such SyncSources to client wins or server wins. Use the default conflict resolution for this SyncSource. The server wins for this SyncSource (overrides default). The client wins for this SyncSource (overrides default). Applicable only to MergeableSyncSources and must be used for such SyncSources.
Default value Server wins Client wins Merge data

Log Settings

A basic installation includes a single log file called funambol_ds.log, stored in the <DS_SERVER_HOME>\logs directory. However, you can specify logging for specific server components, with the output going to separate files if desired. The system provides loggers for this purpose, as follows: Logger funambol funambol.engine funambol.engine.pipeline funambol.engine.source funambol.handler funambol.server funambol.server. notification funambol.transport funambol.email Description / Filename The standard system logger. Filename: funambol_ds.log Logger for the engine. Filename: funambol_ds.engine.log Logger for the pipeline manager. Filename: funambol_ds.engine.pipeline.log Logger for the engine source. Filename: funambol_ds.engine.source.log Logger for the handler. Filename: funambol_ds.handler.log Logger for the server. Filename: funambol_ds.server.log Logger for server notification. Filename: funambol_ds.server.notification.log Logger for the transport. Filename: funambol_ds.transport.log Logger for email. Filename: funambol_ds.email.log

Multiuser

Installing Modules
A module is usually distributed as a zip or jar archive. The archive might contain several files, but the primary file has the following filename syntax,
{modulename}-{versionnumber}.s4j
where modulename is the name of the module and versionnumber is the version.
Example: Funambol Email Connector Module filename funambol-email-3.0.2.s4j
The.s4j module file contains the part of the module that becomes part of the Funambol DS Server enterprise archive (a J2EE ear file). It contains classes, configuration files, and initialization files that are processed by the installation procedure. The.s4j module file must be copied to the <DS_SERVER_HOME>\modules directory to be processed by the installation procedure.
Funambol modules can be installed either by re-installing the entire Funambol DS Server, or by using a separate script that installs only modules. Also, if you are using the bundled installation, the server must be running before performing the installation procedure below.

Installing a Module

1. Unpack the module archive file. 2. Copy the funambol-{modulename}-{versionnumber}.s4j file to the <DS_SERVER_HOME>\modules directory.
3. Using a text editor, open the <DS_SERVER_HOME>\install.properties file. 4. Find the line that begins modules-to-install= in the Module definitions section. This
line specifies, in a comma-separated list, the modules to install during installation.
5. Add funambol-{modulename}-{versionnumber} to the comma-separated list without the.s4j filename extension. 6. Save and close install.properties. 7. Start the server if not already running (for bundled installation users). 8. Install the module. Open a command prompt window and run the installation script by
typing the following at the prompt: Windows
> cd <DS_SERVER_HOME> > install-modules.cmd <application_server>
> cd <DS_SERVER_HOME> > install-modules.sh <application_server>
During the installation you are prompted to create (i.e., rebuild) the database for the server. Type n (no) if you have data in the database that you do not want to lose, such as your existing users, mappings and previous sync information. In addition, as the installation procedure installs each module, you are prompted to rebuild that modules database. Accept or decline as appropriate, but for the module that is being installed for the first time, you must type y (yes).

Uninstalling a Module

To uninstall a module, perform the following:
1. Open the <DS_SERVER_HOME>\install.properties file. 2. Find the modules-to-install= property and delete the module from the comma-

separated list.

3. Save and close install.properties. 4. Reinstall the application server and rebuild the database.

Edit Table SyncSource Buttons Load table from db Displays a window that allows you to connect with a database and select a table to synchronize with. This action populates the fields in the Table Info area. For example, the Table name field displays the name of the selected table, and the Key field list box contains fields for selection. In addition, the Field Mapping table is populated with server and client fields, with a checkbox for each row to designate binary data fields. New Adds a new row (mapping) to the Field Mapping table. Remove Removes the selected row (mapping) from the Field Mapping table. Add Adds a SyncSource (i.e., an instance of the SyncSource type) configured with the specified parameter values.
Adding a Table SyncSource
To add a Table SyncSource, perform the following:
1. Double-click Table SyncSource in the navigation pane. 2. Specify the Source URI, Name, Type, and JNDI Name datasource. 3. Click Load data from db. The following window displays:
Load Data from DB Parameters Parameter Jar driver Description JAR file containing the database driver, including the path. You can use the. button to browse to the desired file; you can specify multiple files. Database driver class. Database URL. User ID for accessing the database. Password for accessing the database. List of tables in the specified database. List of columns in the selected table.
Driver URL User Password Tables List Columns List
4. Specify values for accessing the database and click Connect. This action populates the
Tables List with all tables accessible with the given values.
Select the desired table in the Tables List. This action populates the Columns List with all columns in the selected table.
Click OK or Cancel to cancel the operation. When you click OK, you return to the Edit Table SyncSource window. The parameters in the Table Info area, such as Table name, Key field, and so on, are now populated with the fields of the selected table. In addition, the Field Mapping table is populated with server and client fields, with a checkbox for each row to designate binary data fields.
7. Select the desired field for the parameters in the Table Info area. The fields you select are
highlighted in the Field Mapping table. For example, when you make a selection for Key field, the selected field is highlighted in the table.

The parameter definitions in Edit Table SyncSource Parameters on page 46 apply to this window. An additional Link field parameter is defined as follows: In the partitioning table, this is the field used to get the records from the data table (the guid) In the data table, this is the guid field (which can be the key field).
A sample configuration is shown below: Parameter Source URI Name Type JNDI Name datasource./customerDB customerDB text/plain jdbc/fnblds Partitioning Table Table name Principal field Link field Last update timestamp field Last update type field agent_customer id_principal id_customer update_date update_type Data Table Table name Key field Link field Last update timestamp field Last update type field Field Mapping customer id_customer id_customer update_date update_type country street postal_code state name city Binary fields None country street postal_code state name city Value
Configuring the Client Table SyncSource The procedure for configuring the client is the same as described in Configuring the Client Table SyncSource on page 50.
Using the Email Connector and Inbox Listener
The chapter describes how to configure the email connector and inbox listener to synchronize email between client and server databases.
Configuring the Email Connector, page 58 Implementing the Inbox Listener, page 63
Configuring the Email Connector
To configure the email connector, you perform the following actions: Configure the Officer Configure the connector Create a SyncSource Set the log level

Configuring the Officer

The Officer is a Server JavaBean that is responsible for authenticating users and authorizing access to DS server resources. To set the Officer for the email connector, perform the following:
1. Start the DS Server and open the Administration Tool. 2. In the navigation pane on the left, expand the server and double-click Server settings. The
server parameters display on the right as shown below:
3. In the Officer field, specify com/funambol/server/security/EmailOfficer.xml. 4. Click Save to save the configuration settings. For additional details on server settings, see
the Server Settings on page 21.
Configuring the Connector
To configure the email connector, perform the following:
1. Start the DS Server and open the Administration Tool (if not already open). 2. In the navigation pane on the left, expand the server tree as follows: [server] > Modules >
email > FunambolEmailConnector. The email connector parameters display on the right as shown below:

Other Resources

This section lists other resources you may find useful. For information on Java 2 Standard Edition, visit http://java.sun.com/j2se. For information on Java 2 Enterprise Edition, visit http://java.sun.com/j2ee. For information on JBoss, visit http://www.jboss.org. For information on Apache Tomcat, visit http://jakarta.apache.org/tomcat.

Default Databases

The Funambol DS Server provides the following default databases to which you can synchronize:

URIs are case sensitive.

Calendar
Usage: synchronizing calendar data. URI scal cal MIME-TYPE text/x-s4j-sife text/x-vcalendar text/calendar Clients All Funambol-developed clients Most of the common and known clients that are already built into a mobile device.

Contacts

Usage: synchronizing contact data. URI scard card MIME-TYPE text/x-s4j-sifc text/x-vcard text/vcard Clients All Funambol-developed clients Most of the common and known clients that are already built into a mobile device.
Usage: synchronizing text-based notes. URI snote note MIME-TYPE text/x-s4j-sifn text/plain Clients All Funambol-developed clients Most of the common and known clients that are already built into a mobile device.
Usage: synchronizing task data. URI stask MIME-TYPE text/x-s4j-sift Clients All Funambol-developed clients

Briefcase

Usage: synchronizing briefcase data. URI briefcase MIME-TYPE Application/* Clients All Funambol-developed clients

Install Properties

The <DS_SERVER_HOME>\install.properties file is the central repository of configuration information that is used by the installation procedure to set up the Funambol DS Server. It is a standard Java properties file that contains the following parameters: Parameter context-path Description The context path to be used to configure the web container for the Funambol DS Server module. The DS Server will respond to URLs starting with this context path. Name of the database where Funambol DS Server tables are created. Classpath including the JDBC driver for the database, if not included in the system classpath. JDBC driver class. Database user password JDBC connection URL Comma-separated list of Funambol DS Server modules to install. If a module has already been installed, the installation procedure reinstalls it again. The server URI that will be specified in SyncML messages. The server will only respond to messages addressed to this URI.

dbms jdbc.classpath jdbc.driver jdbc.password jdbc.url modules-to-install

server-name

Connection Factory Sample
The following is an example of a simple connection factory that uses a single connection to access to a database.
/** * Copyright (C) 2003-2006 Funambol * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 */ package com.funambol.db.client.test; import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; /** * This is an example of a simple ConnectionFactory that guarantees to use * only one connection to the database. */ public class SimpleConnectionFactoryImpl implements com.funambol.db.client.ConnectionFactory { // ----------------------------------------------------------- Constants // -------------------------------------------------------- Private data private String driver = null; private String url = null; private String user = null; private String password = null; private static Connection conn = null; /** * Open a new connection if there isn't one. * @return Connection * @throws SQLException */ public Connection getConnection() throws SQLException { if (conn == null) { connect(); } return conn; }
/** * This implementation doesn't close the connection * @param conn Connection */ public void closeConnection(Connection conn) { } /** * Closes the connection * @throws SQLException */ public void closeConnection() throws SQLException { if (conn != null) { conn.close(); } } // ----------------------------------------------------- Private Methods /** * Creates the connection to the database * @throws SQLException */ private synchronized void connect() throws SQLException { if (conn != null) { return ; } try { Class.forName(driver); conn = DriverManager.getConnection(url, user, password); } catch (Exception e) { e.printStackTrace(); } } /** * Sets the driver * @param driver the driver to set */ public void setDriver(String driver) { this.driver = driver; } /** * Sets the user * @param user the user to set */ public void setUser(String user) { this.user = user; } /** * Sets the password * @param password the password to set */ public void setPassword(String password) { this.password = password; }