gnu.hylafax
Class HylaFAXClientProtocol

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

All Implemented Interfaces:

ClientProtocol

Direct Known Subclasses:

HylaFAXClient

public class HylaFAXClientProtocol

extends FtpClientProtocol

implements ClientProtocol

This is the core implementation of the HylaFAX client protocol.

The purpose of this class is to implement the HylaFAX client protocol as simply and straight-forward as possible.

Method names are not my choosing for the most part. They have been largely pulled straight from the protocol and HylaFAX man pages. I expect that convenience classes and methods, with more developer friendly names will be built on top of this raw protocol implementation as time passes.

Most developers should use the higher-level Client to perform some actions rather than this class directly.

Field Summary

static int	DEFAULT_PORT default HylaFAX server port.
static java.lang.String	TZONE_GMT use the GMT timezone for date fields.
static java.lang.String	TZONE_LOCAL use the local timezone for date fields.

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

Constructor Summary

HylaFAXClientProtocol()
default constructor.

Method Summary

void	admin(java.lang.String password) establish administrator privileges given password
java.lang.String	filefmt() get the FILEFMT string value.
void	filefmt(java.lang.String value) set the FILEFMT string value.
long	idle() get the current idle timeout in seconds
void	idle(long timeout) set the idle timeout value to the given number of seconds
void	jdele(long jobid) delete the given job this can be called on a suspended or done job.
void	jintr(long jobid) interrupt the given job id
void	jkill(long jobid) kill the job with the given job id
void	jnew() create a new job.
long	job() get the current job id 0 indicates the current job id is "default" value
void	job(long value) set the current job id
java.lang.String	jobfmt() get the job format string.
void	jobfmt(java.lang.String value) set the job format string.
java.lang.String	jparm(java.lang.String parm) get job parameters of the current job
void	jparm(java.lang.String parm, int value) set job parameters on the current job
void	jparm(java.lang.String parm, long value) set job parameters on the current job
void	jparm(java.lang.String parm, java.lang.Object value) set job parameters on the current job
void	jparm(java.lang.String parm, java.lang.String value) set job parameters on the current job
void	jrest() reset the state of the current job.
long	jsubm() submit the current job to the scheduler
int	jsubm(long jobid) submit the given job to the scheduler
void	jsusp(long jobid) Suspend the job with the given job id.
void	jwait(long jobid) Wait for the job with the given job id to complete.
java.lang.String	mdmfmt() get the modem format string value.
void	mdmfmt(java.lang.String value) set the modem format string.
void	open() open a connection to the localhost on the default port
void	open(java.lang.String host) open a connection to a given server at default port this is an alias for connect()
java.lang.String	rcvfmt() get the received file output format string.
void	rcvfmt(java.lang.String value) set the receive file output format string.
long	size(java.lang.String pathname) Returns the size (in bytes) of the given regular file.
java.lang.String	stot(java.io.InputStream data) store temp file, the file is stored in a uniquely named file on the server.
void	tzone(java.lang.String value) set the timezone display format valid tzone values are TZONE_GMT and TZONE_LOCAL
java.net.InetAddress	vrfy(java.lang.String dialstring) verify dialstring handling and/or least-cost routing.

Methods inherited from class gnu.inet.ftp.FtpClientProtocol

abor, abor, cdup, connect, cwd, dele, getDebug, getGreeting, getInetAddress, getType, list, list, mdtm, mode, 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.ClientProtocol

noop, pass, quit, user

Field Detail

DEFAULT_PORT

public static int DEFAULT_PORT

default HylaFAX server port. currently 4559

TZONE_GMT

public static final java.lang.String TZONE_GMT

use the GMT timezone for date fields.

TZONE_LOCAL

public static final java.lang.String TZONE_LOCAL

use the local timezone for date fields.

Constructor Detail

HylaFAXClientProtocol

public HylaFAXClientProtocol()

default constructor. sets up the initial class state.

Method Detail

admin

public void admin(java.lang.String password)
           throws java.io.IOException,
                  ServerResponseException

establish administrator privileges given password

Specified by:

admin in interface ClientProtocol

Parameters:

password - administrator password

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

idle

public long idle()
          throws java.io.IOException,
                 ServerResponseException

get the current idle timeout in seconds

Specified by:

idle in interface ClientProtocol

Overrides:

idle in class FtpClientProtocol

Returns:

server's idle timeout in seconds

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

idle

public void idle(long timeout)
          throws java.io.IOException,
                 ServerResponseException

set the idle timeout value to the given number of seconds

Specified by:

idle in interface ClientProtocol

Overrides:

idle in class FtpClientProtocol

Parameters:

timeout - new timeout value in seconds (MAX = 7200)

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

job

public long job()
         throws java.io.IOException,
                ServerResponseException

get the current job id 0 indicates the current job id is "default" value

Specified by:

job in interface ClientProtocol

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

job

public void job(long value)
         throws java.io.IOException,
                ServerResponseException

set the current job id

Specified by:

job in interface ClientProtocol

Parameters:

value - new current job id

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jobfmt

public java.lang.String jobfmt()
                        throws java.io.IOException,
                               ServerResponseException

get the job format string. read the HylaFAX man pages, hfaxd(8c), for format codes.

Specified by:

jobfmt in interface ClientProtocol

Throws:

java.io.IOException - a socket IO error occurred.

ServerResponseException - the server responded with an error code

jobfmt

public void jobfmt(java.lang.String value)
            throws java.io.IOException,
                   ServerResponseException

set the job format string. read the HylaFAX man pages, hfaxd(8c), for format codes.

Specified by:

jobfmt in interface ClientProtocol

Parameters:

value - new job format string

Throws:

java.io.IOException - a socket IO error occurred.

ServerResponseException - the server responded with an error

mdmfmt

public void mdmfmt(java.lang.String value)
            throws java.io.IOException,
                   ServerResponseException

set the modem format string. the modem format string is used to format the modem status information. Refer to the HylaFAX man pages, hfaxd(8c), for formatting codes.

Specified by:

mdmfmt in interface ClientProtocol

Parameters:

value - the new modem format string to use

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error code

mdmfmt

public java.lang.String mdmfmt()
                        throws java.io.IOException,
                               ServerResponseException

get the modem format string value. the modem format string specifies how modem status information should be displayed. refer to the HylaFAX man pages, hfaxd(8c), for the format string codes.

Specified by:

mdmfmt in interface ClientProtocol

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error code

rcvfmt

public void rcvfmt(java.lang.String value)
            throws java.io.IOException,
                   ServerResponseException

set the receive file output format string. The rcvfmt string specifies how received faxes (files in the rcvq directory) are displayed. refer to the HylaFAX man pages, hfaxd(8c), for the format string codes.

Specified by:

rcvfmt in interface ClientProtocol

Parameters:

value - the new format string

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error code

rcvfmt

public java.lang.String rcvfmt()
                        throws java.io.IOException,
                               ServerResponseException

get the received file output format string. The rcvfmt string specifies how received faxes (files in the rcvq directory) are displayed. Refer to the HylaFAX man pages, hfaxd(8c), for the format string codes.

Specified by:

rcvfmt in interface ClientProtocol

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error code

filefmt

public void filefmt(java.lang.String value)
             throws java.io.IOException,
                    ServerResponseException

set the FILEFMT string value. the FILEFMT string specifies how file status information is returned when the LIST and STAT commands are used. Refer to the HylaFAX man pages, hfaxd(8c), for the formatting codes.

Specified by:

filefmt in interface ClientProtocol

Parameters:

value - the new value of the FILEFMT string

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server replied with an error code

filefmt

public java.lang.String filefmt()
                         throws java.io.IOException,
                                ServerResponseException

get the FILEFMT string value. The FILEFMT string specifies how file status information is formatted when returned by the LIST and STAT commands. Refer to the HylaFAX man pages, hfaxd(8c), for information on the formatting codes that can be used in this string.

Specified by:

filefmt in interface ClientProtocol

Returns:

the current FILEFMT value

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server replied with an error code

jdele

public void jdele(long jobid)
           throws java.io.IOException,
                  ServerResponseException

delete the given job this can be called on a suspended or done job.

Specified by:

jdele in interface ClientProtocol

Parameters:

jobid - id of the job to delete

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - server replied with error code

jintr

public void jintr(long jobid)
           throws java.io.IOException,
                  ServerResponseException

interrupt the given job id

Specified by:

jintr in interface ClientProtocol

Parameters:

jobid - id of the job to interrupt

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server replied with an error code

jkill

public void jkill(long jobid)
           throws java.io.IOException,
                  ServerResponseException

kill the job with the given job id

Specified by:

jkill in interface ClientProtocol

Parameters:

jobid - the id of the job to kill

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server replied with an error code

jnew

public void jnew()
          throws java.io.IOException,
                 ServerResponseException

create a new job. get the new job id using the job() method. The new job is the current job.

Specified by:

jnew in interface ClientProtocol

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server replied with an error code

jrest

public void jrest()
           throws java.io.IOException,
                  ServerResponseException

reset the state of the current job. get/set the current job id via the 'job' method

Specified by:

jrest in interface ClientProtocol

Throws:

java.io.IOException - an IO error occurred

ServerResponseException - the server replied with an error code

jsubm

public int jsubm(long jobid)
          throws java.io.IOException,
                 ServerResponseException

submit the given job to the scheduler

Specified by:

jsubm in interface ClientProtocol

Parameters:

jobid - the id of the job to submit

Returns:

the submitted job id, should match jobid passed in

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jsubm

public long jsubm()
           throws java.io.IOException,
                  ServerResponseException

submit the current job to the scheduler

Specified by:

jsubm in interface ClientProtocol

Returns:

the job id

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jsusp

public void jsusp(long jobid)
           throws java.io.IOException,
                  ServerResponseException

Suspend the job with the given job id.

Specified by:

jsusp in interface ClientProtocol

Parameters:

jobid - id of the job to suspend

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jwait

public void jwait(long jobid)
           throws java.io.IOException,
                  ServerResponseException

Wait for the job with the given job id to complete.

Specified by:

jwait in interface ClientProtocol

Parameters:

jobid - id of the job to wait for

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

tzone

public void tzone(java.lang.String value)
           throws java.io.IOException,
                  ServerResponseException

set the timezone display format valid tzone values are TZONE_GMT and TZONE_LOCAL

Specified by:

tzone in interface ClientProtocol

Parameters:

value - new timezone display setting

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jparm

public void jparm(java.lang.String parm,
                  java.lang.String value)
           throws java.io.IOException,
                  ServerResponseException

set job parameters on the current job

Specified by:

jparm in interface ClientProtocol

Parameters:

parm - the name of the job parameter to change

value - the value of the given parameter

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jparm

public void jparm(java.lang.String parm,
                  java.lang.Object value)
           throws java.io.IOException,
                  ServerResponseException

set job parameters on the current job

Specified by:

jparm in interface ClientProtocol

Parameters:

parm - the name of the job parameter to change

value - the value of the given parameter as an Object

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jparm

public void jparm(java.lang.String parm,
                  int value)
           throws java.io.IOException,
                  ServerResponseException

set job parameters on the current job

Specified by:

jparm in interface ClientProtocol

Parameters:

parm - the name of the job parameter to change

value - the value of the given parameter

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jparm

public void jparm(java.lang.String parm,
                  long value)
           throws java.io.IOException,
                  ServerResponseException

set job parameters on the current job

Specified by:

jparm in interface ClientProtocol

Parameters:

parm - the name of the job parameter to change

value - the value of the given parameter

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

jparm

public java.lang.String jparm(java.lang.String parm)
                       throws java.io.IOException,
                              ServerResponseException

get job parameters of the current job

Specified by:

jparm in interface ClientProtocol

Parameters:

parm - the name of the job parameter to change

Returns:

value of the named job parameter

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

stot

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

store temp file, the file is stored in a uniquely named file on the server. The remote temp file is deleted when the connection is closed.

Specified by:

stot in interface ClientProtocol

Overrides:

stot in class FtpClientProtocol

Returns:

the filename of the temp file

Throws:

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

ServerResponseException - server replied with error code

vrfy

public java.net.InetAddress vrfy(java.lang.String dialstring)
                          throws java.io.IOException,
                                 ServerResponseException

verify dialstring handling and/or least-cost routing.

Specified by:

vrfy in interface ClientProtocol

Parameters:

dialstring - the dialstring to verify

Returns:

the InetAddress of the server that will handle the given dialstring

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server replied with an error code

open

public void open(java.lang.String host)
          throws java.net.UnknownHostException,
                 java.io.IOException,
                 ServerResponseException

open a connection to a given server at default port this is an alias for connect()

Specified by:

open in interface ClientProtocol

Overrides:

open in class FtpClientProtocol

Parameters:

host - the hostname of the HylaFAX server

Throws:

java.net.UnknownHostException - cannot resolve the given hostname

java.io.IOException - IO error occurred

ServerResponseException - the server replied with an error code

open

public void open()
          throws java.net.UnknownHostException,
                 java.io.IOException,
                 ServerResponseException

open a connection to the localhost on the default port

Specified by:

open in interface ClientProtocol

Overrides:

open in class FtpClientProtocol

Throws:

java.net.UnknownHostException - cannot resolve the given hostname

java.io.IOException - IO error occurred

ServerResponseException - the server replied with an error code

size

public long size(java.lang.String pathname)
          throws java.io.IOException,
                 java.io.FileNotFoundException,
                 ServerResponseException

Returns the size (in bytes) of the given regular file. This is the size on the server and may not accurately represent the file size once the file has been transferred (particularly via ASCII mode)

Specified by:

size in interface ClientProtocol

Overrides:

size in class FtpClientProtocol

Parameters:

pathname - the name of the file to get the size for

Throws:

java.io.IOException - caused by a socket IO error

ServerResponseException - caused by a server response indicating an error

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