This chapter explains what happens when a Palm device connects to a synchronization server. It illustrates how the parts of the synchronization server cooperate in order to synchronize the Palm device with a server-side data source.
The SyncBuilder framework encapsulates the connection management into a single, easy-to-use class, called com.syncbuilder.sync.SyncServer. As soon as you instantiate a SyncServer object and call its start() method it is ready to accept incoming connections from Palm devices.
SyncServer needs two helper-objects in order to do its work. It is your job to instantiate these objects and to pass them to SyncServer's constructor. The first object is an instance of com.syncbuilder.sync.ServerSocket. The ServerSocket implements low-level service-routines that deal with the physical connection between the Palm device and the host. The SyncBuilder framework comes with a ServerSocket class that can handle both serial cable, and TCP/IP networking. You just have to instantiate and parameterize it. The second object is an instance of the com.syncbuilder.sync.SyncHandler interface. This will have to be implemented by you. It contains the synchronization logic between the Palm device and your enterprise data. Its interface and the way in which it is invoked by the SyncServer is very similar to that of the Java Servlet technology (think of the SyncServer as the web server, and of the SyncHandler as the Servlet).
Figure 2-1. The basic constellation of a synchronization server
SyncServer instantiates a com.syncbuilder.sync.Link object for each connection it has accepted. This Link object represents a single connection between a Palm device and the synchronization server. The most important functionality of the Link is its ability to give you access to the DLP protocol (indirectly through a com.syncbuilder.sync.Dlp object). DLP gives you all the functionality that you need to query, retrieve, and manipulate data on the Palm device. Invoke the getDlp() method of the Link object in order to obtain a Dlp object.
Figure 2-2. A Palm device has just connected...
Once the Link has been instantiated it is your turn! The SyncServer will invoke the service(Link link) method of your implementation of the SyncHandler interface and it is up to you now to synchronize the Palm device with your data-source on the host. This typically involves querying the databases on both sides, to compare their contents, and to make the neccessary changes then. The databases on the Palm device can be accessed through the DLP protocol (that is the reason why your service method is given the Link object). The data-source on the host can be accessed through any means that the Java platform makes available to you. This includes JDBC, JNDI, CORBA, and web protocols.
Figure 2-3. The synchronization procedure is under way
When you are finished with the synchronization you should simply return from the service method. The SyncServer will close the connection, and discards the Link object.
The following sequence diagram is an alternative look at the procedure I illustrated above. You will have noted the class com.syncbuilder.storage.Database. This is a wrapper for some of the functionality of the DLP protocol. DLP is rather low-level, and Database is a high-level abstraction of the same functionality.
Figure 2-4. The whole synchronization procedure as a sequence diagram
Example 2-1. A fully working piece of samplecode for the section called Overview
/* samplecode/SyncServerTest.java: * * Copyright (C) 1998, Tilo Christ * * This is free software, licensed under the GNU Public License V2. * See the file COPYING for details. */ /* $Id: connection.sgm,v 1.3 1998/10/25 14:05:25 christ Exp $ */ import com.syncbuilder.sync.*; import com.syncbuilder.device.*; /** * This program demonstrates the usage of the com.syncbuilder.sync.SyncServer-class. * It will not work through the PalmPilot's regular HotSync application, but only through * the Network HotSync application which you will have to obtain separately from Palm * Computing. * * @author Tilo Christ */ public class SyncServerTest { public static void main(String[] args) { try { // Create a ServerSocket for use with Network HotSync. Socket.setSocketFactory( new NetworkHSSocketImplFactory() ); ServerSocket ssock = new ServerSocket(null); // Create the SyncServer from the ServerSocket. The SyncServer // will serve all clients using SimpleHandler (see the class // SimpleHandler below). SimpleHandler will mostly print diagnostic // messages and read the UserInfo from the device. See the section called com.syncbuilder.sync.SyncServer See the section called com.syncbuilder.sync.ServerSocket See the section called com.syncbuilder.sync.SyncHandler SyncServer sync_server = new SyncServer(ssock, new SimpleHandler()); System.err.println("Initiate the Network HotSync procedures now."); // The SyncServer starts running NOW! sync_server.start(); System.err.println("Press <RETURN> to stop the service"); com.syncbuilder.util.Util.readLine(); // The SyncServer is shut down sync_server.stop(); } catch(Throwable t) { t.printStackTrace(); } } } /** * This non-public class is used by the SyncServer to handle incoming * connections. */ class SimpleHandler implements com.syncbuilder.sync.SyncHandler { /** Invoked one time at start-up */ public void init() { System.err.println("SimpleHandler.init()"); } /** Invoked every time a device connects */ public void service(Link link) throws Exception { System.err.println("SimpleHandler.service() with " + link.toString() ); Dlp dlp = link.getDlp(); // Do it ten times, so it takes more time... for (int i=0; i < 10; i++) { UserInfo uinfo = dlp.getUserInfo(); System.err.println( uinfo.toString() ); } dlp.endHotSync(); } /** Invoked one time at shutdown */ public void destroy() { System.err.println("SimpleHandler.destroy()"); } }