gnu.hylafax
Class HylaFAXClient

java.lang.Object
  |
  +--gnu.inet.ftp.FtpClientProtocol
        |
        +--gnu.hylafax.HylaFAXClientProtocol
              |
              +--gnu.hylafax.HylaFAXClient

All Implemented Interfaces:

Client, ClientProtocol, ConnectionEventSource, TransferEventSource

Direct Known Subclasses:

HylaFAXPooledClient

public class HylaFAXClient

extends HylaFAXClientProtocol

implements Client, ConnectionEventSource, TransferEventSource

This class implements convenience methods that wrapper the ClientProtocol methods for common functionality.

Most developers will want to use this class rather than the lower-level ClientProtocol methods directly.

See Also:

ClientProtocol

Field Summary

protected PassiveConnection

connection This is a cached PassiveConnection instance.

Fields inherited from class gnu.hylafax.HylaFAXClientProtocol

DEFAULT_PORT, TZONE_GMT, TZONE_LOCAL

Fields inherited from class gnu.inet.ftp.FtpClientProtocol

fileType, greeting, istream, MDTM_TIME_FORMAT1, MDTM_TIME_FORMAT2, MODE_BLOCK, MODE_COMPRESSED, MODE_STREAM, MODE_ZLIB, ostream, port, sock, STRU_FILE, STRU_PAGE, STRU_RECORD, STRU_TIFF, TYPE_ASCII, TYPE_EBCDIC, TYPE_IMAGE, TYPE_LOCAL

Fields inherited from interface gnu.hylafax.ClientProtocol

NOTIFY_ALL, NOTIFY_DONE, NOTIFY_NONE, NOTIFY_REQUEUE, TZONE_GMT, TZONE_LOCAL

Constructor Summary

HylaFAXClient()
default constructor.

Method Summary

void	addConnectionListener(ConnectionListener listener) Register a connection listener with the event source.
void	addConnectionListeners(java.util.Vector listeners) Register a set of connection listeners with the event source.
void	addTransferListener(TransferListener listener) Register a transfer listener with the event source.
void	addTransferListeners(java.util.Vector listeners) Register a set of transfer listeners with the event source.
Job	createJob() create a new job in the server
void	delete(Job job) delete the given done or suspended job
void	get(java.lang.String path, java.io.OutputStream out) GET the named file, FTP style.
Job	getJob(long id) get a Job instance for the given job id
java.util.Vector	getList() get a long-style listing of files in the current directory.
java.util.Vector	getList(java.lang.String path) get a long-style listing of files in the given directory.
java.util.Vector	getNameList() get name list of files in the current directory.
java.util.Vector	getNameList(java.lang.String path) get name list of files in the given directory.
boolean	getPassive() check whether passive transfers have been enabled
void	interrupt(Job job) interrupt the given job
void	kill(Job job) kill the given job
static void	main(java.lang.String[] Arguments) run some basic tests.
void	mode(char mode) set the transfer mode.
java.lang.String	put(java.io.InputStream in) put a file with a unique name.
void	put(java.io.InputStream in, java.lang.String pathname) store a file.
java.lang.String	putTemporary(java.io.InputStream data) put a temp file, the data is stored in a uniquely named file on the server.
void	removeConnectionListener(ConnectionListener listener) De-register a connection listener with the event source.
void	removeTransferListener(TransferListener listener) De-register a transfer listener with the event source.
void	setPassive(boolean passive) enable or disable passive transfers
void	submit(Job job) submit the given job to the scheduler
void	suspend(Job job) suspend the given job from the scheduler
void	wait(Job job) wait for the given job to complete

Methods inherited from class gnu.hylafax.HylaFAXClientProtocol

admin, filefmt, filefmt, idle, idle, jdele, jintr, jkill, jnew, job, job, jobfmt, jobfmt, jparm, jparm, jparm, jparm, jparm, jrest, jsubm, jsubm, jsusp, jwait, mdmfmt, mdmfmt, open, open, rcvfmt, rcvfmt, size, stot, tzone, vrfy

Methods inherited from class gnu.inet.ftp.FtpClientProtocol

abor, abor, cdup, connect, cwd, dele, getDebug, getGreeting, getInetAddress, getType, list, list, mdtm, nlst, nlst, noop, open, pass, pasv, port, pwd, quit, readResponse, retr, rnfr, rnto, setDebug, stat, stat, stor, stou, stru, syst, type, user

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface gnu.hylafax.Client

setDebug

Methods inherited from interface gnu.hylafax.ClientProtocol

admin, filefmt, filefmt, idle, idle, jdele, jintr, jkill, jnew, job, job, jobfmt, jobfmt, jparm, jparm, jparm, jparm, jparm, jrest, jsubm, jsubm, jsusp, jwait, mdmfmt, mdmfmt, noop, open, open, pass, quit, rcvfmt, rcvfmt, size, stot, tzone, user, vrfy

Field Detail

connection

protected PassiveConnection connection

This is a cached PassiveConnection instance. After some hair-pulling I came to realize that in order to avoid an annoying bug, I needed to cache the last PassiveConnection instance in case an error was encountered in the last passive transfer. In my test cases the error condition that triggered the wierd bug could be duplicated by attempting to getList(some-non-exising-file). This caused an exception during the LIST transfer. The next PASV command would return the same IP/Port values. Opening a second socket to the same IP/Port would yield an exception or other errors. Caching the last PassiveConnection (and by extension the Socket) I could reuse the last PassiveConnection values avoiding the bug/error-condition. This is not very pretty but it works. Unfortunately, I'm worried that it may not be very portable since it relies on the behavior of the HylaFAX server. I'll have to see if this behavior is in the FTP RFC (RFC0959.)

Whenever a successful passive transfer occurrs, this variable should be set to null, thereby invalidating the cached value.

Constructor Detail

HylaFAXClient

public HylaFAXClient()

default constructor. initialize class state.

Method Detail

setPassive

public void setPassive(boolean passive)

enable or disable passive transfers

Specified by:

setPassive in interface Client

Parameters:

passive - indicates whether passive transfers should be used

getPassive

public boolean getPassive()

check whether passive transfers have been enabled

Specified by:

getPassive in interface Client

Returns:

true if passive transfers are enabled, false otherwise

mode

public void mode(char mode)
          throws java.io.IOException,
                 ServerResponseException

set the transfer mode. valid mode values are MODE_* listed in the ClientProtocol class.

Specified by:

mode in interface Client

Overrides:

mode in class FtpClientProtocol

Parameters:

mode - the new mode setting

Throws:

java.io.IOException - an io error occurred talking to the server

ServerResponseException - the server replied with an error code

putTemporary

public java.lang.String putTemporary(java.io.InputStream data)
                              throws java.io.IOException,
                                     ServerResponseException

put a temp file, the data is stored in a uniquely named file on the server. The remote temp file is deleted when the connection is closed. NOTE: this calls stot() internally.

Specified by:

putTemporary in interface Client

Returns:

the filename of the temp file

Throws:

java.io.IOException - io error occurred talking to the server

ServerResponseException - server replied with error code

put

public java.lang.String put(java.io.InputStream in)
                     throws java.io.IOException,
                            ServerResponseException

put a file with a unique name. NOTE: this calls stou() internally.

Specified by:

put in interface Client

Returns:

the name of the file created

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error code

put

public void put(java.io.InputStream in,
                java.lang.String pathname)
         throws java.io.IOException,
                ServerResponseException

store a file. NOTE: this calls stor() internally.

Specified by:

put in interface Client

Parameters:

pathname - name of file to store on server (where to put the file on the server)

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error

getList

public java.util.Vector getList(java.lang.String path)
                         throws java.io.IOException,
                                java.io.FileNotFoundException,
                                ServerResponseException

get a long-style listing of files in the given directory. NOTE: this calls the list() method internally.

Specified by:

getList in interface Client

Parameters:

path - the path that we're interested in finding the contents of

Returns:

a Vector of Strings containing the list information

Throws:

java.io.IOException - an IO error occurred

java.io.FileNotFoundException - the given path doesn't exist

ServerResponseException - the server reported an error

getList

public java.util.Vector getList()
                         throws java.io.IOException,
                                java.io.FileNotFoundException,
                                ServerResponseException

get a long-style listing of files in the current directory. NOTE: this calls the list() method internally with the "." path.

Specified by:

getList in interface Client

Returns:

a Vector of Strings containing the list information

Throws:

java.io.IOException - an IO error occurred

java.io.FileNotFoundException - the "." path doesn't exist

ServerResponseException - the server reported an error

getNameList

public java.util.Vector getNameList(java.lang.String path)
                             throws java.io.IOException,
                                    ServerResponseException,
                                    java.io.FileNotFoundException

get name list of files in the given directory. Similar to getList() but returns filenames only where getList() returns other, system dependant information.

Specified by:

getNameList in interface Client

Parameters:

path - the path of the directory that we want the name list of

Returns:

Vector of Strings containing filenames

Throws:

java.io.IOException - an IO error occurred

ServerResponseException - the server reported an error

java.io.FileNotFoundException - the requested path does not exist

getNameList

public java.util.Vector getNameList()
                             throws java.io.IOException,
                                    ServerResponseException,
                                    java.io.FileNotFoundException

get name list of files in the current directory. Similar to getList() but returns filenames only where getList() returns other, system dependant information.

Specified by:

getNameList in interface Client

Returns:

Vector of Strings containing filenames

Throws:

java.io.IOException - an IO error occurred

ServerResponseException - the server reported an error

java.io.FileNotFoundException - the requested path does not exist

get

public void get(java.lang.String path,
                java.io.OutputStream out)
         throws java.io.IOException,
                java.io.FileNotFoundException,
                ServerResponseException

GET the named file, FTP style.

Specified by:

get in interface Client

Parameters:

path - the name of the file to GET. This can be a full or partial path.

out - the OutputStream to write the file data to

Throws:

java.io.IOException - an IO error occurred

ServerResponseException - the server reported an error

java.io.FileNotFoundException - the given path does not exist

createJob

public Job createJob()
              throws ServerResponseException,
                     java.io.IOException

create a new job in the server

Specified by:

createJob in interface Client

Returns:

a new Job instance on the server

Throws:

ServerResponseException -

java.io.IOException - an IO error occurred while communicating with the server

getJob

public Job getJob(long id)
           throws ServerResponseException,
                  java.io.IOException

get a Job instance for the given job id

Specified by:

getJob in interface Client

Parameters:

id - the id of the job to get

Throws:

ServerResponseException -

java.io.IOException - an IO error occurred while communicating with the server

submit

public void submit(Job job)
            throws ServerResponseException,
                   java.io.IOException

submit the given job to the scheduler

Specified by:

submit in interface Client

Parameters:

job - the Job to submit

Throws:

ServerResponseException -

java.io.IOException - an IO error occurred while communicating with the server

delete

public void delete(Job job)
            throws ServerResponseException,
                   java.io.IOException

delete the given done or suspended job

Specified by:

delete in interface Client

Parameters:

job - the (done or suspended) job to delete

Throws:

ServerResponseException -

java.io.IOException - an IO error occurred while communicating with the server

suspend

public void suspend(Job job)
             throws ServerResponseException,
                    java.io.IOException

suspend the given job from the scheduler

Specified by:

suspend in interface Client

Parameters:

job - the Job to suspend

Throws:

ServerResponseException -

java.io.IOException - an IO error occurred while communicating with the server

wait

public void wait(Job job)
          throws ServerResponseException,
                 java.io.IOException

wait for the given job to complete

Specified by:

wait in interface Client

Parameters:

job - the job to wait for

Throws:

ServerResponseException -

java.io.IOException - an IO error occurred while communicating with the server

kill

public void kill(Job job)
          throws ServerResponseException,
                 java.io.IOException

kill the given job

Specified by:

kill in interface Client

Parameters:

job - the job to kill

Throws:

ServerResponseException -

java.io.IOException - an IO error occurred while communicating with the server

interrupt

public void interrupt(Job job)
               throws ServerResponseException,
                      java.io.IOException

interrupt the given job

Specified by:

interrupt in interface Client

Parameters:

job - the job to interrupt

Throws:

ServerResponseException -

java.io.IOException - an IO error occurred while communicating with the server

addConnectionListener

public void addConnectionListener(ConnectionListener listener)

Register a connection listener with the event source.

Specified by:

addConnectionListener in interface ConnectionEventSource

Parameters:

listener - the listener to register with the event source

addConnectionListeners

public void addConnectionListeners(java.util.Vector listeners)

Register a set of connection listeners with the event source.

Specified by:

addConnectionListeners in interface ConnectionEventSource

Parameters:

listeners - the listeners to register with the event source

removeConnectionListener

public void removeConnectionListener(ConnectionListener listener)

De-register a connection listener with the event source.

Specified by:

removeConnectionListener in interface ConnectionEventSource

Parameters:

listener - the listener to de-register with the event source

addTransferListener

public void addTransferListener(TransferListener listener)

Register a transfer listener with the event source.

Specified by:

addTransferListener in interface TransferEventSource

Parameters:

listener - the listener to register with the event source

addTransferListeners

public void addTransferListeners(java.util.Vector listeners)

Register a set of transfer listeners with the event source.

Specified by:

addTransferListeners in interface TransferEventSource

Parameters:

listeners - the listeners to register with the event source

removeTransferListener

public void removeTransferListener(TransferListener listener)

De-register a transfer listener with the event source.

Specified by:

removeTransferListener in interface TransferEventSource

Parameters:

listener - the listener to de-register with the event source

main

public static void main(java.lang.String[] Arguments)

run some basic tests. eventually this method should be removed in favor of a decent testing framework.

Parameters:

Arguments - an array of command-line-argument Strings