A Guide to Sync

Sync is a system for replicating data across multiple computers and keeping the replicas synchronized through periodic exchange of updates. Intelligent merging of updates allows the replicas to be updated concurrently with minimal conflict. Sync is useful for replicating many kinds of data, from generic files and directories to application specific forms such as drawings and documents.

This guide is intended for application programmers who wish to use Sync to replicate the data for their applications. It gives an overview of the Sync application programming interface and discusses some example Sync applications. It also describes the Sync run-time system. Programmers may also consult the library documentation. Those who would like a high-level description of Sync may wish to read the original Sync paper.

Installing Sync and Running Example Applications

Sync offers a hub-and-spoke replication model, where a Sync server executes on the hub and Sync clients execute on the spokes. The installation is the same for either client or server, but must be repeated for each participating machine.

Installation

  1. Download Sync as a ZIP file or a tar file.
  2. Unzip or extract the package wherever desired. This will create a "Sync" directory.
  3. From the Sync directory, copy the sync.jprops file to your home directory (which should be the one returned by the Java System.getProperty("user.home") call).
  4. Modify the sync.jprops, client.jprops, and server.jprops files appropriately for your environment. These have several site-specific values.
  5. For a server machine, start the Sync server by executing java edu.unc.sync.server.SyncServer. For a client machine, start the Sync client by executing java edu.unc.sync.server.SyncClient.

Using the Sync client and server, and running Sync applications

The Sync client and server have similar interfaces but offer a somewhat different set of operations. Sync applications may be executed from either.

The Sync server interface

The Sync server interface allows users to view and edit the replicated data of their Sync applications. Objects are hierarchically organized in folders, like a conventional file system. The left pane of the display presents a tree view of the data, while the right pane shows the contents of the folder selected in the left pane.

The Object menu has the following items:

New
Presents a list of classes that may be instantiated. (Must have been registered with the server as described below.) Upon selection, a new instance of the class is created and deposited in the currently open folder (that which is displayed in the right pane).
Application
Presents a list of applications that may be started. (Must have been registered with the server as described below.)
Commit
Commits the current changes, if any, of the selected object. Choosing this item does not have any effect on synchronization, since any object's uncommitted changes are first committed upon receiving a client's synchronization request with respect to that object.
Garbage Collect
When an application disposes of a replicated object, it is not immediately removed from the Sync system because it is possible that the application's deletion may be undone in the merge process. Thus Sync keeps a reference to the object until it is no longer needed. As there is currently no automatic mechanism in Sync to do this, garbage collection is left for the user to do, as frequently as determined by memory and disk space needs.

First-level garbage collection removes disposed-of objects from the object server's internal table. (The Sync client and server delegate object storage and retrieval to a module known as the object server, which is described in the library documentation.) This allows Java's garbage collection to dispose of the objects. The objects, however, may have been stored in a disk file as well, and thus second-level garbage collection looks for files that do not have corresponding entries in the object server's internal table. It is left as an independent operation because leaving the persistent storage of an object still allows it to be reactiveated if necessary.
Shutdown
Shuts down the Sync server, after a confirmation prompt.

The Sync client interface

The Sync client interface is very similar to the Sync server interface but has some different commands. The client has an extra menu, Server, which is used to connect to one or more Sync servers for the purpose of browsing their contents. In the the client's Object menu are two commands not in the server Object menu, namely Replicate and Synchronize. To replicate an object from a server, a server must first be mounted. The user then selects an object of a server and chooses Replicate. This will then copy the data from the server to the client. To synchronize a client's data with the data on the server, the user should select the top-level object and choose Synchronize. Due to a current limitation in the synchronization code, only top-level objects can be selected for synchronization. As a result, lower-level objects will be synchronized, but they cannot be selectively synchronized.

Running Sync applications

Sync applications are started from the New or Application menus in either the client or server. The contents of these menus are determined at load time by the client.jprops and server.jprops files.

Applications are installed by adding to these files, either directly or through the Properties command in the Edit menu. If edited directly, changes will not be seen unless the client/server is reloaded. Also, any changes to application class files will not be seen until the the client/server is reloaded.

The following headings are left as a reminder as to what needs filling in.

Writing a Sync Application

Extending Sync Classes

The Replicated Classes

The Delta Classes

The MergeMatrix Classes