Features, download and contact info
Includes screenshots
Submitting patches, CVS access etc.
Features, target audience, hardware etc.
Diagrams and text of possible user actions

SourceForge Logo

FTraQ: File Transfer Queue

A Java-based FTP client


Version 1.0 - July 2002

Copyright © 2002 by the FTraQ Development Team. FTraQ is licensed under the GNU General Public License, Version 2. This manual is licensed under the GNU Free Documentation License.


Program Startup
The Bookmark Library
The Quick Connect Bar
An FTP Session
The Transfer Queue
Program Settings

^ top


FTraQ is an FTP client. FTP stands for File Transfer Protocol. It is a standardized (RfC 959), client/server-based protocol for sending and receiving files over a network. An FTP server waits for connections from FTP clients. Based on authentication information (username, password) it grants the clients read and/or write access to certain files and directories on the server.

FTP is used for a variety of purposes. Examples include public content archives, administration of web sites, exchange of private content between different machines and much more. There are both graphical and text-based FTP clients. Fortunately for you, FTraQ is a graphical FTP client that is quite easy to use.

Being written in Java, FTraQ should work on a broad range of platforms. The downside is that the execution speed is not as high as that of normal ("native") applications for your platform. FTraQ makes up for that with the following set of features:

  • A nice, three panel user interface
  • Tabbed server view
  • Built-in mini text editor
  • Directory cache for faster server-side listing
  • Bookmark library
  • Queue with resume support
  • Support for cross-platform resuming

Hopefully, you will be able to use FTraQ without reading this manual. It is primarily intended as a reference.

^ top


If you start me up
If you start me up I'll never stop
— The Rolling Stones

Once you have copied ftraq.jar into an appropriate directory (you need to have write access there), starting the client should be simple enough. Under Windows, double click the icon of the ftraq.jar file. If nothing happens, you do not have an up-to-date Java Runtime Environment installed -- see the installation documentation for details.

Under Linux, FreeBSD and other systems, you will probably have to start FTraQ from the command line. The command is simple:

user@system:~/apps/ftraq$ java -jar ftraq.jar

After a short time, the FTraQ main window should open. In the background, several files are created in the conf/ directory: the bookmark library file, the transfer queue file, the program options file and the document type definitions (DTDs) for these files. These files are human-readable, if you are familiar with XML, you may want to take a look.

^ top


"Human memory is a marvelous but fallacious instrument... The memories which lie within us are not carved in stone; not only do they tend to become erased as the years go by, but often they change, or even increase by incorporating extraneous features."
— Primo Levi

After starting FTraQ, you should see the main window with the bookmark library:

The bookmark library allows you to save the addresses and parameters of frequently accessed FTP servers. The numbers in the screenshot mark the three main areas of the bookmark library:

(1): the bookmark tree. It consists of folders and items. You can organize it in any way you want. To add a new bookmark item, click the "New" button on the top left. To add a new folder, click the "Folder" button. To delete the selected item, click the "Trashcan" button. Click the top right button to open a new connection for the selected bookmark item. To rename a bookmark item or folder, you must triple-click it.

(2): the detail view for the selected bookmark item. It consists of the following fields:

Host: The address of the FTP server you want to connect to.

Port: The usual FTP port is port 21. You can change the default port that is used for new bookmark items in the program settings.

User name, Password: Authentication parameters if desired.

Anoynmous (checkbox): Use anonymous login instead (user name "anonymous", password is defined in program settings, should be validly formed email address). Note that the user name / password parameters are still saved even if the anonymous login is active, so that you can later switch to non-anonymous login again.

Local directory, remote directory: Change into this directory on the local and remote system after a successful connect. Most FTP servers use the /pub directory for content available to the public.

Retry attempts: How many times should FTraQ try to connect to a busy server?

Seconds to wait before retrying: Most server administrators do not like "hammering" a server to get in. Therefore it is recommended to use a reasonably high value here.

Maximum number of connections: Four should be a good default settings, some servers only tolerate one connection from any individual user.

Seconds to keep connection alive: FTraQ disconnects from the server after this time is exceeded. (The connection is automatically restored when the user needs it.)

(3): the transfer queue panel. This panel is always visible. It contains files and directories which have been enqueued for uploading or downloading. If there are still files to be downloaded or uploaded from your last session, they will be listed here. Note: You do not need an open navigation session to transfer files in the queue -- the connection will be created in the background.

^ top


Instead of creating a bookmark entry and using it to connect to an FTP server, you can also use the quick connect bar at the top of the program window:

In the field "Hostname / URL" you can enter either a hostname in the form or an URL in the form If you use the hostname form, the username, password and port to the right are used. If you use the URL form, the data to the right is ignored (the default port is used).

The reason to allow both forms is simple: FTP addresses are often exchanged in the URL form, which can be parsed by many applications. So you can paste URLs you get elsewhere directly into the URL field. In normal everyday use you will probably prefer the hostname form.

Note that the quick connect bar has no site history. If you want to remember a site, you should use the "Add to bookmarks" function once you are connected.

^ top


"It is no exaggeration to conclude that the Internet has achieved, and continues to achieve, the most participatory marketplace of mass speech that this country--and indeed the world--has yet seen."
— From The Last Word by George F. Will, Newsweek, July 7, 1997.

Once you have established a connection to an FTP server, either by using quick connect bar or by selecting a bookmark entry and clicking the "Connect" button, you will see a two-panel view of your local filesystem and the server's filesystem, as in the example below:

Notice that the connection has been opened in a new "tab" next to the bookmark tab. You can open as many FTP sessions as you want at the same time.

The green lamp on the FTP server tab indicates that this connection is active. A black lamp means that the connection has been closed because the idle time has been exceeded (it will be opened again if necessary). A yellow lamp means that the client is trying to connect to the server. A dark green lamp means that an operation on the server is in progress. A red lamp means that an error has occurred; sometimes this can be solved, sometimes not.

Below the row of tabs are the FTP session operation buttons:

Close session: Disconnects from the server and closes the tab.

Add bookmark: Create a new bookmark item with the parameters of the current session. You will be prompted to enter a name. If a folder is selected in the bookmark library, the new entry will be created there.

Select All: Selects all files and directories in the currently active panel (local system or remote system). The active panel has a border around it.

Transfer: Immediately transfer the selected file(s), either from client to server or from server to client, depending on which panel is active. Directories are transferred recursively.

Add to queue: Add the selected file(s) to the transfer queue. The transfer can then be started on demand.

Refresh: Reload the currently displayed directory.

New directory: Create a new directory (requires write permission).

Rename: Rename the selected file(s) (requires write permission).

Delete: Delete the selected file(s) (directories are deleted recursively, i.e. all files and directories in them are deleted as well).

Edit: Edit a single file. Opens a built-in text editor. If the file is on the server, it is downloaded into memory (no local file is created). Saving the file then uploads the copy in memory to the server.

Properties: Change the permissions of the selected file(s). Works only on remote system, and only if you are the owner of the file(s) or root (superuser).

Below the operation buttons are the panels for the local and the remote filesystem. On the top of each panel is an entryfield which shows the current directory name but also allows you to enter a path name. To view the list of previously visited directories, click the down arrow next to the entryfield.

What follows is a text/graphical view of the filesystem that should be self-explanatory. To enter a folder, double click it (you may have to double click faster than in other applications - Java has its own settings). If the operation is executed, the window should gray out temporarily and then display the contents of the selected folder. Note that FTraQ caches directory contents in the background: As soon as you enter a directory, it tries to load the contents of any subdirectories using a second connection, so that these subdirectories can be displayed faster. Also, any directory you enter is cached.

If there is a problem executing any operation, a red window should appear within the filesystem panel explaining what went wrong. Click the button within the window to make the message disappear.

Note that you can change the size of the panels by clicking and moving the hatched bar between them.

^ top


All transfers to and from the server are managed using FTraQ's built-in queue. The queue works according to the FIFO (first in, first out) principle: Items are transferred in the same sequence in which you added them to the queue. The queue is persistent, which means that it will still contain all non-completed files when you exit and restart the program.

Once you have added some items to the queue, it might look as follows:

The queue shows the name of the file(s) that are to be transferred, the source and destination for the transfer, the status of the individual items (stopped, preparing, running, completed etc.), the progress for each item, and the current speed of the transfer(s).

If you add a directory to the queue, it is transferred recursively. In that case, the queue displays the name and size of the currently transferred file during the transfer.

The queue has a button row with the following operations:

Start / stop selected: Start or stop only the selected queue item(s).

Remove selected: Remove the selected queue item(s) from the queue. (Files are NOT deleted.)

Start queue: Starts transferring the queue items, beginning with the first item for each server.

Stop queue: Stops all transfers.

Clear completed: Removes the completed item(s) from the list.

Clear all: Removes all queue items (clears the queue).

Move to top: Move the selected item to the top so that it is transferred next.

Move up / down: Move the selected item up / down by one row.

Move to bottom: Move the selected item to the bottom so that it is transferred last.

^ top


FTraQ provides a variety of settings that can be modified to improve your user experience. To edit the program settings, choose "Edit | Settings" from the program's pull down menu.

The settings window is tabbed and consists of three categories: General, ASCII File Extensions, and Directory Mappings. The different settings are explained below.

General Options

Cache size: FTraQ caches the contents of directories on a server so that they are displayed faster. Here you can specify the maximum number of directories whose contents should be kept in the cache at the same time.

Max transfers: How many transfers can run at the same time?

Default connection settings: These settings are used for new bookmark entries and connections started using the quick connect bar.

ASCII File Extensions

FTP supports two different transfer modes: ASCII mode and binary mode. The reason for this is that different operating systems represent text files differently, especially with regard to the line separator at the end of each line. When files are transferred in ASCII mode, they are automatically converted to the correct format. When you transfer a binary file in ASCII mode, however, it will likely be damaged.

The list of ASCII file extensions is a list of the extensions of those files which you want to transfer in ASCII mode. These may be all kinds of text files: plain text documents, source code etc. Be sure to add the extensions of scripts you may want to execute on a web server to this list, or the scripts may not execute properly.

Directory Mappings

Ignore this if you only use one operating system. If you use several operating systems on the same machine (dual-boot, triple-boot etc.) and want to be able to use a single installation of FTraQ for all systems, you need to tell FTraQ how directories are represented on the different operating systems. Note that this only makes sense if you have write access to at least one directory from all operating systems you want to use.

For example, you might have a harddisk partition in FAT format which you can access from both Windows and Linux. Under Windows, this partition is known as "D:\". Under Linux, it is called "/mnt/D". You need to tell FTraQ this. But first FTraQ needs to know what operating systems you are running.

Operating systems are identified using "system strings". These are combinations of hostname, processor type, operating system name and operating system version (build) number. A single operating system may be identified with several different strings. For example, if you boot into Linux using more than one kernel, you would have to add a system string for each kernel version to the list of system strings for your operating system Linux. Alternatively, however, you might also have two completely separate Linux installations.

To support all this, you need to first create an operating system ("Add current system") and then at least one system string that identifies it ("Add Current ID String" automatically adds the generated system ID string). In the table below the list of operating systems you can then add "mappings" for each operating system you have created. A mapping consists of a list of pathnames for the different operating system, e.g. "C:\", "/mnt/C", etc. Wherever pathnames are used, they are from now on automatically resolved depending on the operating system FTraQ is running under.