SmartSync - Network Enabled File Synchronizer

Protocol Definition

The protocol of SmartSync uses one single HTTP post request for synchronization. To be independent of the architecture, no serialized  java objects are used for communication. The following sections describe the applicational protocol, i.e. the structure of the data stream of request and response.

Commands

The overall structure of the protocol is a list of commands in the request and in the response. One single command is coded in latin1 with a end of line sequence of \n\r. Each command consists of a single line command verb, an unordered list of parameters (each on one line) followed by an empty line and an optional content stream. The command handler must be able to read to the end of the content stream, where the next command verb starts. The last command in the stream is always a command with the verb "done".

A command parameter consists of the name of the parameter followed by ":", followed by the value of the parameter. Here comes an example of a list of two commands terminated with the done command: 

example-command
content-length:6
color:red

foobarexample-command
color:red
content-length:3

foodone

Notice that "done" s a complete command with (possibly) no parameter. It has two end-of-line sequences after the command verb, one that terminates the verb and one that terminates the empty parameter list.

File Names

Files are always named with its path, which is relative to a document root (e.g. reference directory or work directory). The separation character of the path elements is '/' independent of the platform. Directory references like '.' or '..' are illegal. Path elements cannot contain any of the following characters:

/  \  :  *  ?  "  >  <   |

Depending on the platform, more illegal characters may be added. Files that are directly located in a document root have no path. The following examples are legal file names:

a
.b
a b.txt
d/e f/g.txt

Request

The easiest way to describe a request is to start with an example request:

properties
task-list-flag:true
compression-flag:false

work-files
file-count:5

AbrechnungApotheke.xls|25088|13edcb3f|1032250516000
bookTOC.pdf|91988|657e4836|1033416916000
rfc/rfc1738.html|56303|8b787f89|908121844000
rfc/rfc1867.html|29154|462eec8|1045144660284
rfc/rfc1918.html|23988|b09c89d5|1045144805904
archive-files
file-count:5

AbrechnungApotheke.xls|25088|13edcb3f|1032250516000
Arbeitsvertag.doc|38400|f3ae5807|1037604357735
adress.doc|429|7e2d261e|1025855156000
rfc/rfc1738.html|56303|8b787f89|908121844000
rfc/rfc1867.html|29200|b145bd87|908121844000
done

The following table describes the request commands.

Command Verb Parameter / Stream Description
properties task-list-flag Specifies true or false, specifies whether the task summary should be included or not. 
compression-flag Specifies true or false, specifies whether gzip compression should be used or not. If this flag is set to true, the following commands of the request and the whole response is compressed using a gzip stream.
Stream No stream data
work-files
 file-count Specifies the number of work file definitions contained in the following stream. 
Stream A list of work file definitions. One single file definition consists of the following fields separated by a "|"
  • The file name and path
  • The size of the file coded in decimal notation
  • The crc32 checksum over the file content coded in hexadecimal notation
  • The modification time of the file coded in decimal notation representing the number of ms after 1.1.1970 00:00.
archive-files file-count Specifies the number of archive file definitions contained in the following stream. 
Stream A list of archive file definitions. One single file definition consists of the following fields separated by a "|"
  • The file name and path
  • The size of the file coded in decimal notation
  • The crc32 checksum over the file content coded in hexadecimal notation
  • The modification time of the file coded in decimal notation representing the number of ms after 1.1.1970 00:00.
done Stream No stream data

Response

Here is a possible response to the previous request:

summary
task-count:5
task-list-flag:true
transfer-length:19
transfer-count:2

delete|AbrechnungApotheke.xls|-1
resume-create|rfc/rfc1918.html|16
resume-keep|rfc/rfc1867.html|-1
create|foo.txt|3
keep|adress.doc|-1
delete
file-name:AbrechnungApotheke.xls

resume-create
last-modified:908121844000
append-length:16
file-name:rfc/rfc1918.html

</body></HTML>
resume-keep
last-modified:908121844000
file-name:rfc/rfc1867.html

create
last-modified:1045144549054
file-length:3
file-name:foo.txt

fookeep
last-modified:1025855156000
file-name:adress.doc

done

The following table describes all response commands. The sequence of the commands must follow the given sequence:

Command Verb Parameter / Stream Description
summary task-count Specifies the total number of tasks that will follow. This parameter defines also the end of the stream content. 
task-list-flag Specifies true or false, whether a task summary list will follow or not. 
transfer-length Specifies the clear number of byte that must be transferred for this update. This parameter is only intended for monitoring purposes. 
transfer-count Specifies the number of tasks that cause a clear data transfer. This parameter is only intended for monitoring purposes. 
Stream If the task-list-flag is set to true, the stream contains a list of task definitions. One single task definition consists of the following fields separated by a "|"
  • The command verb
  • The path and name of the file
  • The number of clear byte transfer caused by this task or -1.
delete
 file-name Defines the path and name of the file that must be deleted from the work directory.
Stream No stream data.
resume-create
 file-name Defines the path and name of the file.
last-modified Defines the last modification date of the file coded in decimal notation representing the number of ms after 1.1.1970 00:00.
append-length Defines number of byte that must be appended to the file.
Stream Contains the transfer data to resume the creation of the file.
resume-keep
 file-name Defines the path and name of the file whose rest must be copied from the archive directory to the work directory.
last-modified Defines the last modification date of the file coded in decimal notation representing the number of ms after 1.1.1970 00:00.
Stream No stream data
create
 file-name Defines the path and name of the file to be created
last-modified Defines the last modification date of the file coded in decimal notation representing the number of ms after 1.1.1970 00:00.
file-length Defines the length of the file in byte.
Stream Contains the transfer data for the creation of the file.
keep
 file-name Defines the path and name of the file that must be copied from the archive directory to the work directory.
last-modified Defines the last modification date of the file coded in decimal notation representing the number of ms after 1.1.1970 00:00.
Stream No stream data
done Stream No stream data

Links

Copyright © 2003 NetCat AG. All rights reserved.

keywords:java, net, servlet, synchronize, file, files, synchronize data, synchronize directory, synchronize files, synchronize files over HTTP, synchronize tree, file synchronizer, directory synchronizer, directory, directory structure, network, download, package, equalize, equalize, server, synchronise, file, files, synchronise data, synchronise directory, synchronise files, synchronise files over HTTP, synchronise tree, file synchroniser, file synchronisation, directory synchroniser, directory synchronisation, java, net, servlet, synchronize, file, files, synchronize data, synchronize directory, synchronize files, synchronize files over HTTP, synchronize tree, file synchronizer, directory synchronizer, directory, directory structure, network, download, package, equalize, equalize, server, synchronise, file, files, synchronise data, synchronise directory, synchronise files, synchronise files over HTTP, synchronise tree, file synchroniser, file synchronisation, directory synchroniser, directory synchronisation, java, net, servlet, synchronize, file, files, synchronize data, synchronize directory, synchronize files, synchronize files over HTTP, synchronize tree, file synchronizer, directory synchronizer, directory, directory structure, network, download, package, equalize, equalize, server, synchronise, file, files, synchronise data, synchronise directory, synchronise files, synchronise files over HTTP, synchronise tree, file synchroniser, file synchronisation, directory synchroniser, directory synchronisation