FTraQ: File Transfer Queue
A Java-based FTP client
USER MANUAL
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.
Introduction
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 ftp.server.com or an URL in the form
ftp://user:password@ftp.server.com:port. 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.
HAVE FUN!
