Last update: 10/11/2009 13:30 CET  --- >1.52<

--------------------------------------------------------------------------------

>>>	Contents	<<<

1. Setup
	1.1	How do i run JFtp?
	1.2 What about compiling?
	1.3	Updates
	1.4	Compatibility
	1.5 Why do you use so many other APIs?
	1.6	What about those themes?
	1.7 Using JFtp as an applet or via webstart

2. Features
	2.1	General features
	2.2	Multiple parallel downloads
	2.3	You do not support the ??? command!
	2.4	SMB specific info

3. Tweaking / Bugs
	3.1	Changing options in Settings.java
	3.2	I found a bug!
	3.3	I see no icons!
	3.4 Tips and tricks

4. The team
	4.1 Wo is involved in this project?
	4.2	Submitting patches
	4.3	Hompage

5. API License
	5.1	Using the API in your own applications
	5.2	Use in commercial products

--------------------------------------------------------------------------------

			         --- NOTICE ---

	Updates are released quickly after coding, so please report
	bugs to j-ftp-devel@lists.sourceforge.net if you encounter them... :)

--------------------------------------------------------------------------------

1.1 How do i run JFtp?

	Unpack the .tar.gz to a java conform path (no exclamation mark, tab etc)

        To start JFtp just call "run" (*nix) or "run.bat" (Windows/DOS).
	Alternatively type "java -jar jftp.jar" in build/jars/

	You can also add a command-line url, for example:
		java -jar jftp.jar "ftp://anonymous:test@ftp.kernel.org/pub"
	or	run.bat "ftp://anonymous:test@ftp.kernel.org/pub"
	
	This works for SFTP now, too if you replace ftp:// with sftp://

1.2 What about compiling?

	JFtp is already compiled if you have downloaded it in a .tar.gz. 
	Recompile using "ant clean" and "ant" in j-ftp/ - of course you'll 
	need the ant tools installed.
	
1.3 Updates

	If we have important changes we usually release immendiately. Sometimes 
	we release a few versions a week, sometimes the developement stalls for 
	some time. If you have created patches or want to code on JFtp, please send
	a mail to me or directly to the mailing list.

	Binary prereleases are available via Java Web Start.
	You can also load the jar directly:
	
	http://j-ftp.sourceforge.net/jftp.jar

	If you found a critical bug, please mail it (see 3.2 for instructions).
	We'll try to fix it asap.
	
1.4 Compatibility

	JFtp should work with all platforms. However, i'm not able to test it 
	under different platforms often, so it may run less stable there than with linux.
	
	If you encounter a java.lang.UnsupportedClassVersionError please make sure to either recompile it with your
	java version or update you JRE.

1.5  Embedded APIs

	All APIs used by JFtp that are not written by myself and the other project members
	have a free (GPL/LGPL) license. These include:

	- jcifs for the SMB protocol, very nice API.

	- j2ssh for SFTP, a rather big but very good API.

	- webnfs for NFS, downloaded from Sun Microsystems, it took me a while to get things working
	              because there was just a small subset of NFS info in the javadoc and not that much demos.
		      But the API itselfs rocks, too - it is fast, stable and more than just a NFS API, but a
		      replacement for the File class with network support.
		      
	- apache.org: commons, log4j, webdav ...

1.6	The themes...

	...come from 
	
	http://www.incors.org/ 
	
	and
	
	http://mlf.sourceforge.net
	
	Much better even than swing in my opinion... :)

	And finally there are those neat litte Icons:

	- http://www.famfamfam.com/lab/icons/silk/

	- http://art.gnome.org/themes/icon/1352

	- The jayalobby icons are copyrighted by Dean S. Jones
	
1.7 Integration JFtp

	If you want to use JFtp as an applet or launch it via webstart please look at doc/applet.html 
	and doc/jftp.jnlp for examples.
	
	
	
	
--------------------------------------------------------------------------------
	
2.1 General features

	JFtp is a multi-platform, multi-protocol network browser.

	It started as a ftp client with its own api and has grown to support
	file, ftp, smb, http, sftp, nfs and raw tcp/ip connections using standard or 3rd-party apis.

	Some words about the ftp features:

	It can up- and download directories recursively, resume ftp up- and downloads automatically, has a
	download manager and a nice swing ui. Active and passive mode ftp are supported and the parsing
	of the directory listings is very robust. You can also ftp mutithreaded, which means that you can browse
	the server and transfer files/dirs at the same time (see "Multiple parallel transfers" below).

2.2 Multiple parallel transfers

	Use multiple connections parallel to save time, for example if a server
	has a bandwith limit. If a server allows only one connection at a time 
	you'll have to uncheck "Multiple Conenctions", though. You can increase 
	the number of parallel connections manually when initiating a 
	connection. Passive ftp is recommended because multiple connections do 
	not work with active ftp. 

2.3 You do not support the ??? command!
	
	Use "Execute remote command" if you have to use commands not implemented
	directly in JFtp, such as changing permissions of files. If it would 
	make sense to add support directly, send a mail to the mailing list 
	and/or write a feature request on our sourceforge-site. :-)

2.4 SMB specific info

	Note that if you have multiple network cards and get an error messag containing MSBROWSE
	when browsing the lan this probably happens because the wrong adapter is chosen.
	You have to temporaryly disable the other card and restart to use this feature atm, since there is no fix yet.

--------------------------------------------------------------------------------
	
3.1 Changing options in Settings.java

        If you want to activate some other options just edit src/Settings.java
        and recompile using "ant" in j-ftp/ 

	Notes: There are some interesting options you can manually tweak in
	Settings.java.	You need to recompile, of course...

	>>> uiRefresh
		 minimal amount of time between ui refreshes caused by JFtp.log().
		 500 milliseconds seem like a safe default, but if you recompile you
		 probably want to play with this.

	>>> enableMultiThreading
		uses different threads and connections so you can browse the 
		server while up- and/or downloading (single files, not 
		directories). Does not work on servers with a limit of 
		connections per user, but for servers supporting it you should 
		set this to true (can be set via gui, too).
	
	>>> noUploadMultiThreading 
		do not use different connections for uploads.

	>>> maxConnections
		use up to this many connections to up- and download.
	
	>>> smallSize
		if file is smaller than this it will be downloaded using the 
		normal control connection, this results in a faster transfer 
		blocking, but most times even faster than the initial blocking 
		when forking a download.
	
	>>> smallSizeUp
		same as above for uploads.
	
	>>> enableResuming
		false for the API (overwrite default), overridden to true by
		JFtp.

	>>> enableUploadResuming
		default: true
	
	>>> askToResume
		change this to false if you don't want any messages, but note 
		that if you have an older but smaller file you probably don't 
		want it to be autoresumed

	>>> connectionTimeout
		timeout for a connection to a server, default should be ok.
	
	>>> hideStatus
		if true some unimportant messages are hidden, default is false.
	
	>>> cachePass
		set this to false if you do not want your passwords to be saved.
	
	>>> safeMode
		sends some NOOPs to clear buffers, should be obsolete.
	
	>>> autoUpdate
		checks for new versions, but might not work sometimes.
	
	>>> defaultFtpPasvMode
		leave this true if you do not need active FTP. Passive FTP is 
		more firewall-friedly, and if it is not supported by the server 
		switches the app automatically.
	
	>>> bufferSize
		every n bytes recieved data is written on disk and a 
		statusmessage is sent to the downloadmanager. If you set this 
		too high and have a slow connection you'll get outdated status 
		in the downloadmanager, if you set it too low you'll waste 
		cpu power.

	>>> refreshDelay
		time in milliseconds bettween downloadmanager UI refreshes. 
		Increase this if the JList flickers often (default 500).

3.2 I found a bug!

	We need your help to improve JFtp. We cannot test every type of server 
	around with every option turned on/off every time we do a release. So 
	if you find an error, please mail me (hansmann.d@debitel.net) and/or the
	mailing list (j-ftp-devel@lists.sourceforge.net) and tell us about it. 
	Please include the server ip you we're trying to access and the 
	stacktrace of the exception (if you got one). 
	Please visit the sourceforge project page and fill out a bug report, too. 


3.3 I see no icons!

	If the application starts, but you cannot see any icons, you probably
	installed JFtp in a path that is not java conform. Remove all special
	characters like exclamation mark, tab, etc. and try again.

3.4 Tips and tricks

	- Check the shortcuts already present, if you are annoyed by log messages
	   and finished transfers. Just press "Alt-1" and "Alt-2" to clear log and
	   download manager.

	- Check the address bar. If you put a FTP-URL pointing to a file it will be downloaded
	   instantly using the (minimalistic) Java FTP protocol implementation, mostly because I want
	   to have an alternative if some code is broken in the API.
	   If a URL pointing to a directory is given it will be opened in a remote window using
	   the JFtp API.

	- Check the queueing system. It resumes aborted downloads automatically and does work really
	  good if you want to download huge files without haveing to check wheter they have been aborted by the
	  server every ten minutes. Tip: Add files to the queue, disconnect and then start the queued downloads
	  if the server does not support multiple connections.

--------------------------------------------------------------------------------

4.1 Who is involved in this project?

All new Contributors are appended at the end, please check the changelog
if you want to know who did what exactly. If your name is missing and you want
to be listed here because you contributed code, made documentation or similar -
please don't take that personal and just write a short email to me :)

        People involved:

Active developers:
    - David Hansmann <mailto:hansmann.d@debitel.net>
	- Jake Kasprzak <jolt@radioheart.com>

Other people that have spent time working on the project:
        - Ron Broberg <mailto:ronbroberg@yahoo.com>
        - Paul Hammant <mailto:Paul_Hammant@yahoo.com>
        - Gary Wong
        - Ricardo Kustner
        - Bas Cancrinus <mailto:bas@cipherware.com>
        - Daniele Panozzo <mailto:daniele@panozzo.191.it>
        - Sandy McGuffog <mailto:mcguffog@ieee.org>
        - Leon Stringer
	- Mark Hale <mailto:mj_hale@yahoo.com>
	- Richard Krutisch <mailto:richard.krutisch@gmx.net>
	- Bruno Brueckmann <Bruno.Brueckmann@BIT.admin.ch>

        Icons:
        - Copyright(C) 1998 by Dean S. Jones
        - Source: jfa.javalobby.com
        - Author: dean@gallant.com


4.2 Submitting patches

	If you are using JFtp and are able to fix bugs you find yourself, please
	consider to do this. A patch is applied quickly, and often i am not able
	to even find the bugs reported. If you want  you can have a cvs access
	and modify whatever you want. This is a free project... but if you contribute code
	to the FTP API you have to accept that i may sell commercial licenses / support for it.

	And yes, the project will remain GPL/open source!


4.3 Homepage

	Visit us at

	http://j-ftp.sourceforge.net -> Homepage, Java Web Start link

	http://www.sourceforge.net/projects/j-ftp -> Sourceforge project page

--------------------------------------------------------------------------------


5.1 Using the API in your own applications

	You can use the API in your own applications. Simply add jftp.jar to
	your classpath and import the packages net.sf.jftp.net, .util and
	.config and use the FtpConnection class to transfer files.

	Note that the license is GPL per default, but I may grant you a less restrictive
	license (see below).

	Take a look at doc/FtpDownload.java. Please note that resuming is
	*disabled* per default (in the api) and local files are overwritten if
	they exist. This behaviour is necessary since there is no proof the part
	of the file is equal to the remote file. You can change
	Setting.enableResuming to enable it, but you need to check the files
	manually (if they are smaller than the remote file).

	If you want to use advanced features of the API, such as progress
	updates for example, you'll have to read the source (it's very difficult
	to maintain a lot of documentation code if you still change to API, so
	there's not much doc) or to mail us your questions.


5.2	Commercial use of the FTP API

	The JFtp API is GPL, if you want to get another license, please contact me
	via mail or the mailing list. This will cost you money, but you'll get support, bugfixes
	and new features implemented if you want. There is already a commerical API package
	which is threatened more conservatively and much smaller in size.


		Have a lot of fun...

		David Hansmann, JFtp project maintainer
		hansmann.d@debitel.net