#1 adds experimental 'token' scheme

[tom kelsey]

* what it is
- this is a 'scheme' in jfilesync (similar to the 'server' scheme) that makes it easier to use one directory as a intermediary between the two directories to synch, e.g. using a usb flash disc to sync two PCs.
- the advantage of the token scheme is that only files that need to be copied across are stored on the drive
- this means that a small drive can synchronize two larger directories, provided no one file is too large in size.
- this is an early beta release and there are a few known problems with it listed below, and probably some unknown ones.
- please read 'how to use' and 'known bugs' sections carefully, particularly setting the correct directory text, or you may lose data.

* how to install it
- download the attached jfs.jar file. rename your existing jfs.jar file (which will normally be at C:\Program Files\jfilesync\libs on windows) and replace it with the downloaded version

* how to use it
- create a profle and select two directories as normal, where one of the directories is on your removable drive.
- in the 'edit profile' dialog, change the directory on the removable drive to have 'token:///' in front of it.
- e.g. if it is 'G:\sync\' change it to 'token:///G:\sync\'
- IMPORTANT: if this string is entered incorrectly it will use the current working directory as the directory to sync, which may cause you to lose data - not necesarily in the synched directory.
- The text will then change to green.
- repeat this process on the other machine to sync, again adding 'token:///' in front of the directory on the removable drive
- then use jfs as normal, syncing each machine with the removable drive in turn
- don't delete or change any files from the synced directory on the removable disc. instead change them on the other directories.

* todos
- adapt to be used with >2 machines to sync (with a different token directory per machine)
- add wizard for converting a 'local' drive to 'token' drive
- add wizard for creating a token drive to sync two machines
- ensure 'compatible' profiles are used on both machines - i.e. use the same set of exclusions / inlcusions. this could be done by splitting the profile into two files , one with per machine settings, the other with everything else, and syncing the 'everything else' file
- use rsync protocol (rdiff) to minimize data sent (will also allow larger files to be synced)

* known bugs
- jfs parses the token drive string as for a server string, which means if it is entered incorrectly e.g. as "token://" - no 'root' directory is found and instead it uses '.'
- sometimes it seems to leave empty directories in a state where they can't be deleted (windows only)
- it doesn't cope well with stuff being deleted from the token drive - a workaround is to only update the other drives
- the token directory is not hidden
- wont work as well as a 'local' scheme if it is used to sync > 2 machines. the problem is that when a file is copied off the token drive, it is deleted, leaving a token in place, so it cant then be copied onto another machine.
- there is potential for more conflicts when using token scheme with a small drive
e.g. if a 1gb drive is used to synch two directories with no files > 1 gb, and more than 1gb of files has changed since the last synch., an out of space error would happen. But with the next sync cycle the remaining files would be copied. Provided on average less than the capacity of the token drive changes on each directory per sync cycle then eventually all files will be synced. the problem is that because of the delay in syching files a conflict (where a file is changed on both dirs) is more likely to happen.
generally when the token drive runs out of space, although jfilesync can cope with it, it is generally better to use a bigger drive.

* untested: the following has not been tested:
- running out of space on token drive
- token scheme & server scheme together
- syncing token directory with token directory
- changing files directly on the token drive.

[tom kelsey]

main file with experimental 'token' scheme