Xrsync Files

Xrsync uploads an entire folder from a local MS-Windows client to a remote
Linux host if the folder doesn't exist remotely. Or it synchronizes the
folders and files under the selected folder on the remote host by either
checking the consistency of the checksum, or comparing the last modified
time and size of the file to be synchronized.

Xrsync transfers files using Java implemented SSH API to ensure secure data
transfer. So it works for any remote Linux host that runs a SSH daemon and
a local Windows client that can launch an IP connection to the Linux host
using an account with a home directory on that host.

Xrsync was originally developed to upload and synchronize locally-developed
Java source code to a remote Linux server. The primary concerns were the
correctness, integrity, easiness, security, reliability and speed of the
transfer. JSch turned out the best choice that the author could find on the
Internet to serve all these purposes ideally out of various Java SSH API
packages. The other Java implemented SSH API's are either not updated for a
long time - Ganymed SSH-2 for Java, last updated on 2006, for example, or
not free any longer - J2SSH/SSHTOOLS, for another example, the last free
release was on 2007, and still with some bugs in its sftp API which caused
sudden connection-closed event on the server side in case of file transfer
multithreaded.

**************************************************************************
*								Installation							 *
**************************************************************************

Executable: Just download Xrsync.exe and run.

Plugin for Eclipse: Download com.dj.srcRsync_1.0.0.*.jar and copy it to the
		"plugins" folder in the home of Eclipse, e.g. "%eclipse%/plugins".
		Reopen Eclipse after the copy, it will be available in the name of
		"Xrsync" in the main menu named "Code Assist", the toolbar and the
		right-key pop-up menu, with an icon of dark green background and a
		white upward arrow in the center.

**************************************************************************
*									Usage							 	 *
**************************************************************************

Sync Paths
----------

Local:	Valid local folder path which is not empty.
		
		example: C:/users/[username]/[dirname]/.../[source_dirname]
		
Remote:	Valid remote folder path name on the remote host.
		Note: This should be the valid format of path name recognized by
		the remote Linux system. It should not be preceded with the host
		name or address.
		
		example: /home/[username]/[dirname]/.../[destination_dirname] (or)
				 ~/[dirname]/.../[destination_dirname] (or)
				 [dirname]/.../[destination_dirname] 

Remote Host
-----------

Address: Valid Internet domain name or IP address of the remote host.
		
		example: www.[hostname].edu (or)
				 [hostname].com (or)
				 110.48.112.176 (IP address)
		
Port:	Valid port number that a SSH daemon is listening on the remote
		host.
		
		example: 22

Remote Login
------------

Name:	Valid login name with a home directory on the remote host.
		
		example: admin
		
Password: Valid password for the login name. 
		
		example: xxxxxx
		
Sync Option
-----------

This option only works when a file with the same name as the local file
exists in the corresponding remote path. Otherwise the local file will be
simply uploaded to the remote path. 

Sync by checksum: If the Content Checksum of the local file is the same
as the remote file, the remote file is up to date so the local file will
not be uploaded. Instead it will be marked by the sign of "Up to date".
Otherwise the local file will be uploaded to synchronize the remote file.

Sync by time && size: If the Last Modified Time and Size of the local file
are both the same as the remote file, the remote file is up to date so the
local file will not be uploaded. Instead it will be marked by the sign of
"Up to date". Otherwise the local file will be uploaded to synchronize the
remote file.

Options
-------

Remember settings: Save current settings - e.g. sync paths, remote host
info, remote login info, sync option, options and thread settings - into
the settings file, so that the current settings will pop out as default
settings next time when Xsync is launched. Saved settings can also pop out
automatically by matching the prefix of the field text through the field
assistance function.

Clear history: Delete all saved history settings from the settings file.

Include binary: Binary files under the designated local path will also be
synchronized in addition to text files. This option can be used to choose
to upload and synchronize only the source code, or all files in a project
including referenced libraries and image resource files in binary format.
Note Xrsync tells whether a file is binary or text by simply reading the
file by bytes, converting the bytes to string, writing the string to file,
then comparing the length of the new file and the bytes. If they are not
of the same size, then Xrsync considers the original file binary. Other
wise text. But this is not absolute. Small binary files with size below 1k
could also get the same size after the conversion because they contained
too few bytes to include the characters unique to binary files. A brute
force to read and test a file byte by byte may better tell if it's binary,
but it will cost much more time especially when a large number of files
need to be tested. The way Xrsync practices is a lot faster with a high
accuracy. Here any tests, corrections or solutions here are welcome and
appreciated. The author's contact information can be found by clicking
the "About..." button on the main UI.

Clean remote path: If there are files or folders in the remote path that
doesn't exist locally, they will be deleted so when the synchronization
process is over, the content of the local path and the remote path will
be completely the same.

Show item progress: Show a progress bar for each file being synchronized.
Note there is a bug here. When a column is sorted by clicking the header,
some folders are collapsed some levels right after the sorting. Now if a
folder is expanded, if there was a file in a sub-folder of the folder being
synchronized right before the folder was collapsed, and now the sub-folder
that contains the file is not expanded, then there will be a static trail
of the progress bar of the file in the place where it was right before the
sorting. Is it an issue of the org.eclipse.jface.viewers.TreeViewer class
since Xrsync uses TreeViewer to display its synchronization progress, and
TreeViewer manages the whole content refresh of the tree control after the
sorting. A solution has been worked out to compute the visible tree items
each time the content changed in the tree, and it does work well in case of
resize, selection changed, vertical bar scrolled, and direct collapse or
expand operation sequences, but it doesn't work for this sort-collapse-and-
expand sequence. Here again, any tests, corrections or solutions here are
welcome and appreciated. The author's contact information can be found by
clicking the "About..." button on the main UI.

Thread Settings
---------------

Maximum number of threads: The file synchronization process is threaded
in Xrsync, which means there can be more than one thread to synchronize
local files to the remote path simultaneously, with each thread working
on a separate file. This way the maximum potential of client bandwidth
can be exploited. On the other hand as each thread will need a private
SSH connection to work alone in order to avoid messing up data between
different threads and files, two many connections to the SSH server may
increase the burden of the remote server and significantly weaken its
capability in serving other clients or tasks. Experiments on the author's
client and server shows four to eight threads might be a good balance
between leveraging local bandwidth and avoiding too much burden on the
remote side.

Maximum buffer per thread: Initially designed for other SSH API, not
necessary for JSch.