wttools.protocols.ifc
Interface ProtocolIfc

All Known Implementing Classes:

AbstractProtocol, ProtocolImpl, ProtocolImpl, ProtocolImpl

public interface ProtocolIfc

Interface ProtocolIfc defines genral interface for reaching network resources. Now it can be incomplete for some protocols ideas but desiging is in progress.
All protocols implementations should implement every of methods including in this interface. Note that there is also AbstractProtocol class which has many simple implementation of methods in this interface. You can use them if they are enough for your protocol use or reimplement.
Each metod returning particular resource info (header or data) can be called at any time, even before calling to connect() method. If call to some method occured before call to connect(), protocol implementation should perform connect() automaticaly.

Version:

$Revision: 1.11 $

Author:

Artur Hefczyc

Field Summary

static int	CODE_BAD_REQUEST
static int	CODE_CONNECTION_ERROR Constant CODE_CONNECTION_ERROR means that unknown error occured.
static int	CODE_CONNECTION_OK Constant CODE_CONNECTION_OK means that everuthing was correct and successful and application can continue downloading data or can close connection.
static int	CODE_FORBIDDEN
static int	CODE_HOST_NOT_FOUND Constant CODE_HOST_NOT_FOUND means that it was impossible to resolve host name into IP number.
static int	CODE_INTERNAL_SERVER_ERROR
static int	CODE_LENGTH_REQUIRED
static int	CODE_NETWORK_NOT_REACHABLE
static int	CODE_NO_CONTENT Constant CODE_NO_CONTENT means that request to resource was correct but resource contains no data.
static int	CODE_NOT_FOUND
static int	CODE_NOT_INITIALIZED Constant CODE_NOT_INITIALIZED means that no connection tries were performed.
static int	CODE_PARTIAL_CONTENT
static int	CODE_REDIRECT
static int	CODE_REQUEST_TIMEOUT
static int	CODE_SERVER_NOT_REACHABLE Constant CODE_SERVER_NOT_REACHABLE means that there was no route to host or remote host is reachable but there was no response from web server application (on given remote port).
static int	CODE_UNAUTHORIZED
static int	CODE_VERSION_NOT_SUPPORTED
static int	METHOD_GET constant METHOD_GET contains value of
static int	METHOD_HEAD constant METHOD_HEAD contains value of

Method Summary

void	connect() connect method performs all necessary actions required to connect to remote resource.
void	disconnect() disconnect method closes network connection.
java.util.HashMap	getAllHeaders() Methods getAllHeaders returns all received header from the web server.
java.lang.String	getClientId() getClientId method returns client identification string which it sends to web sever during connection.
java.lang.Object	getConnectionInfo() getConnectionInfo method should return some connection parameters.
int	getConnectionResult() getConnectionResult method returns standarized for all protocols connection with server result.
java.util.List	getConnectionStatuses() getConnectionStatuses method calculates and returns connection statuses in List.
byte[]	getContentData()
long	getContentLength() getContentLength method returns expected content length.
java.lang.String	getContentType() getContentType method returns type of data stored in resource.
URI	getEffectiveURI() getEffectiveURI returns effective uri of requested resource.
long	getHeaderIntValue(java.lang.String headerKey) Method getHeaderStrValue returns header value as long integer for given header name.
java.lang.String	getHeaderStrValue(java.lang.String headerKey) Method getHeaderStrValue returns header value as String for given header name.
int	getInputBufferSize() getInputBufferSize method returns input buffer size which is set for this protocol.
java.io.InputStream	getInputStream() getInputStream method returns InputStream where from user can read resource data.
java.lang.String	getProtocolType() getProtocolType method returns protocols type it implementing.
long	getRealContentSize() getRealContentSize method returns received size of data.
java.lang.String	getRequestData()
java.lang.String	getServerId() getServerId method returns web server identification string detected during making connection.
int	getStreamReadTimeout() getStreamReadTimeout method returns value of stream read timeout.
float	getTransferSpeed() getTransferSpeed method calculates and returns transfer speed in bytes/sec.
URI	getURI() getURI method returns URI for which performing connection.
java.lang.String	getUserName() getUserName method returns user name used during authorization process.
java.lang.String	getUserPassword() getUserPassword method returns user password used during authorization process.
boolean	isAllowAllCookies()
boolean	isAllowRedirect()
boolean	isAllowUserInteraction()
boolean	isDebug()
boolean	isErrorRecoverable(int code) This method isErrorRecoverable should be able to return info if given error code is permanent or not.
boolean	isKeepAlive() getKeepAlive method returns value of keepAlive field.
void	saveContent(java.io.OutputStream out_stream) saveContent method performs saving resource data to given OutputStream.
void	saveContent(java.lang.String file_name) saveContent method performs saving resource data to given disk file.
void	setAllowAllCookies(boolean allow)
void	setAllowRedirect(boolean redirect)
void	setAllowUserInteraction(boolean allow)
void	setClientId(java.lang.String id) setClientId method sets client identification string.
void	setDebug(boolean debug) Method setDebug sets debug mode.
void	setInputBufferSize(int buff_size) setInputBufferSize method InputStream returns data in packets.
void	setKeepAlive(boolean keepAlive) setKeepAlive method sets keepAlive variable.
void	setRequestData(java.lang.String data)
void	setStreamReadTimeout(int tm_out) setStreamReadTimeout method sets timeout for reading from input stream taken from socket.
void	setURI(URI uri) setURI method sets new URI for protocol instance.
void	setUserName(java.lang.String name) setUserName method sets user name for authorization.
void	setUserPassword(java.lang.String password) setUserPassword method sets user password dor authorization.

Field Detail

METHOD_HEAD

public static final int METHOD_HEAD

constant METHOD_HEAD contains value of

METHOD_GET

public static final int METHOD_GET

constant METHOD_GET contains value of

CODE_HOST_NOT_FOUND

public static final int CODE_HOST_NOT_FOUND

Constant CODE_HOST_NOT_FOUND means that it was impossible to resolve host name into IP number.

CODE_SERVER_NOT_REACHABLE

public static final int CODE_SERVER_NOT_REACHABLE

Constant CODE_SERVER_NOT_REACHABLE means that there was no route to host or remote host is reachable but there was no response from web server application (on given remote port).

CODE_NETWORK_NOT_REACHABLE

public static final int CODE_NETWORK_NOT_REACHABLE

CODE_CONNECTION_ERROR

public static final int CODE_CONNECTION_ERROR

Constant CODE_CONNECTION_ERROR means that unknown error occured.

CODE_NOT_INITIALIZED

public static final int CODE_NOT_INITIALIZED

Constant CODE_NOT_INITIALIZED means that no connection tries were performed. Instance of protocol implementation object was just created.

CODE_CONNECTION_OK

public static final int CODE_CONNECTION_OK

Constant CODE_CONNECTION_OK means that everuthing was correct and successful and application can continue downloading data or can close connection. Note that in some cases data still can be broken. From the protocol implementation sight everything could look correct but for example if protocol doesn't know how many bytes should download and server closed connection during transfer protocol implementation may not know that not all necessary data was downloaded.

CODE_NO_CONTENT

public static final int CODE_NO_CONTENT

Constant CODE_NO_CONTENT means that request to resource was correct but resource contains no data.

CODE_PARTIAL_CONTENT

public static final int CODE_PARTIAL_CONTENT

CODE_REDIRECT

public static final int CODE_REDIRECT

CODE_BAD_REQUEST

public static final int CODE_BAD_REQUEST

CODE_UNAUTHORIZED

public static final int CODE_UNAUTHORIZED

CODE_FORBIDDEN

public static final int CODE_FORBIDDEN

CODE_NOT_FOUND

public static final int CODE_NOT_FOUND

CODE_REQUEST_TIMEOUT

public static final int CODE_REQUEST_TIMEOUT

CODE_LENGTH_REQUIRED

public static final int CODE_LENGTH_REQUIRED

CODE_INTERNAL_SERVER_ERROR

public static final int CODE_INTERNAL_SERVER_ERROR

CODE_VERSION_NOT_SUPPORTED

public static final int CODE_VERSION_NOT_SUPPORTED

Method Detail

getConnectionResult

public int getConnectionResult()
                        throws java.io.IOException

getConnectionResult method returns standarized for all protocols connection with server result. For some protocols such HTTP it could translated server response code for other particular protocol implementation should decide what code return in given situation.

Returns:

an int value standarized connection code.

Throws:

java.io.IOException - if an error occurs

getProtocolType

public java.lang.String getProtocolType()

getProtocolType method returns protocols type it implementing. It should allways be a string taken from package name. For example for HTTP implementation we have class wttools.protocols.http.ProtocolImpl. And we know what protocol it implement from class name, becouse it is stored in last package name level wttools.protocols.http.

Returns:

a String value

setURI

public void setURI(URI uri)
            throws java.io.IOException

setURI method sets new URI for protocol instance. Note that there can be problem that if we have for example FTP instance implementation for URI="ftp://ftp.wttools.sf.net/protocols.jar" We must define proper action if somebody sets new url with different protocol for example URI="http://wttools.sf.net/".

Parameters:

uri - an URI value of new resource URI

Throws:

java.io.IOException - if an error occurs

getURI

public URI getURI()

getURI method returns URI for which performing connection.

Returns:

an URI value of internal field URI uri

getEffectiveURI

public URI getEffectiveURI()
                    throws java.io.IOException

getEffectiveURI returns effective uri of requested resource. If during connecting to web server redirection response occurs it means that effective URI is different then original.

Returns:

an URI value of effective resource URI.

setClientId

public void setClientId(java.lang.String id)

setClientId method sets client identification string. I don't know if it make sense but there is "User-Aget" header in HTTP protocol there which client sends to HTTP server.

Parameters:

id - a String value of client idenification string.

getClientId

public java.lang.String getClientId()

getClientId method returns client identification string which it sends to web sever during connection. In HTTP protocol it is value of "User-Agent" header.

Returns:

a String value of userId field.

setStreamReadTimeout

public void setStreamReadTimeout(int tm_out)

setStreamReadTimeout method sets timeout for reading from input stream taken from socket. When some communication problem occures during perfmorming data transmision application may infinitely wait for data which will never arrive. To prevent such situation you can set stream read timeout to ensure waiting for data no longer than you expect. If set to 0 it means turn off timeout and allow infinite reading.

Parameters:

tm_out - an int value of reading from stream timeout.

getStreamReadTimeout

public int getStreamReadTimeout()

getStreamReadTimeout method returns value of stream read timeout.

Returns:

an int value of stream read timeout.

setInputBufferSize

public void setInputBufferSize(int buff_size)

setInputBufferSize method InputStream returns data in packets. With this method you can sets size of this packet. The smaller size of packet should be used if there are some transmision problems and bigger size should be used if we use network with very good bandwich to improve transmision efficiency.

Parameters:

buff_size - an int value of input buffer size.

getInputBufferSize

public int getInputBufferSize()

getInputBufferSize method returns input buffer size which is set for this protocol.

Returns:

an int value of input buffer size.

setKeepAlive

public void setKeepAlive(boolean keepAlive)

setKeepAlive method sets keepAlive variable. This variable determines keeping connection to web server after completing user request. If we know that we want reach only one resource from thet web server we can set keepAlive to false and protocol implementation should disconnect after finishing transmision. But very often we want to download many files from web server for example from FTP or HTTP server. It is not effective to reconnection every time. It is better to keep alive connection between downloading every file.
For example suppose we have to download 10 files from HTTP server. Each file is about 10kB size. So downloading each of them with good internet connection takes about 1 sec. But establishing connection takes from 1 sec to 30 sec. Lets suppose that it takes about 10 sec. So we can see how much time we can save with using keep alive connections.

Parameters:

keepAlive - a boolean value

isKeepAlive

public boolean isKeepAlive()

getKeepAlive method returns value of keepAlive field. keepAlive field switches between permaneent connection mode and single transfer connection mode. Permanent connection mode should allow to transfer many files with one persistent connection to server.

Returns:

a boolean value of keepAlive field.

See Also:

setKeepAlive(boolean keepAlive)

setAllowUserInteraction

public void setAllowUserInteraction(boolean allow)

isAllowUserInteraction

public boolean isAllowUserInteraction()

setAllowAllCookies

public void setAllowAllCookies(boolean allow)

isAllowAllCookies

public boolean isAllowAllCookies()

setRequestData

public void setRequestData(java.lang.String data)

getRequestData

public java.lang.String getRequestData()

setAllowRedirect

public void setAllowRedirect(boolean redirect)

isAllowRedirect

public boolean isAllowRedirect()

isErrorRecoverable

public boolean isErrorRecoverable(int code)

This method isErrorRecoverable should be able to return info if given error code is permanent or not. I mean for example if error code means "Page not found" it mean that there is no page under requested URL. It is most probably permanent error. However if error code means "Network not reachable" or "Request timeout" it mean that in future during next try download may be successful.

Parameters:

code - an int value of requested error code.

Returns:

a boolean calculated value of recoverability of error.

connect

public void connect()
             throws java.io.IOException

connect method performs all necessary actions required to connect to remote resource. After successfuly completing this method connection should be established and remote data should be ready to download.
User is able both to retrieve special resource info (data headers only) or resource data. For example user should be allowed to return only mail headers instead of full message.

Throws:

java.io.IOException - if an error occurs

disconnect

public void disconnect()
                throws java.io.IOException

disconnect method closes network connection. All received resource info should be still available but not additional data resource data.

Throws:

java.io.IOException - if an error occurs

saveContent

public void saveContent(java.lang.String file_name)
                 throws java.io.IOException

saveContent method performs saving resource data to given disk file. I have doubt what mean resource data. In general we can divide resource info on resource headers and resource data. It is very usefull if we think about HTTP resources. But if we think about mail message headers are almost as important as message data. So in particular protocol implementation headers should be joined with data.

Parameters:

file_name - a String value

Throws:

java.io.IOException - if an error occurs

saveContent

public void saveContent(java.io.OutputStream out_stream)
                 throws java.io.IOException

saveContent method performs saving resource data to given OutputStream. This method does not open nor close given stream. Closing stream should be performed by user.

Parameters:

out_stream - an OutputStream value

Throws:

java.io.IOException - if an error occurs

See Also:

saveContent(String file_name)

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException

getInputStream method returns InputStream where from user can read resource data. For some protocols implementation InputStream should return not only resource data but also resource headers - it is important in mail protocols for example (POP3, IMAP4, SMTP).

Returns:

an InputStream value

Throws:

java.io.IOException - if an error occurs

getContentData

public byte[] getContentData()
                      throws java.io.IOException

getHeaderStrValue

public java.lang.String getHeaderStrValue(java.lang.String headerKey)
                                   throws java.io.IOException

Method getHeaderStrValue returns header value as String for given header name.

Parameters:

headerKey - a String name of header.

Returns:

a String value of header.

getHeaderIntValue

public long getHeaderIntValue(java.lang.String headerKey)
                       throws java.io.IOException

Method getHeaderStrValue returns header value as long integer for given header name.

Parameters:

headerKey - a String name of header.

Returns:

a long value of given header.

getAllHeaders

public java.util.HashMap getAllHeaders()
                                throws java.io.IOException

Methods getAllHeaders returns all received header from the web server.

Returns:

a HashMap value table of pairs header keys and values.

getContentType

public java.lang.String getContentType()
                                throws java.io.IOException

getContentType method returns type of data stored in resource. for some protocols implementation it is easy to return info received from web server (HTTP server returns Content-Type header with such info) for others it is necessary to create engine to determine content type. This engine may base on file extension or based on mime-magic file.

Returns:

a String value returns standard internet mime-type of resource data.

getContentLength

public long getContentLength()
                      throws java.io.IOException

getContentLength method returns expected content length. In many situations web server sends size of resource data, but sometimes we don't know how much data we receive till end of transmision. If expected content length is not known protocol should return -1.

Returns:

a long value size of resource data or -1.

getRealContentSize

public long getRealContentSize()

getRealContentSize method returns received size of data. First of all if undetected network error occurs we can recieve less data that we expect. So during verification we can check if expected data size is equal to received. Second if web server don't send expected data size then with this method we can know how many bytes were received.

Returns:

a long value

getTransferSpeed

public float getTransferSpeed()

getTransferSpeed method calculates and returns transfer speed in bytes/sec. This info should be available during downloading data to allow breaking transfer if ransfer speed is too low.

Returns:

a float value

getServerId

public java.lang.String getServerId()
                             throws java.io.IOException

getServerId method returns web server identification string detected during making connection. in HTTP protocol server identification string can be found in header named Server.

Returns:

a String value containing server identification string.

getConnectionInfo

public java.lang.Object getConnectionInfo()

getConnectionInfo method should return some connection parameters. for example remote host IP number, socket buffers size, socket timeout, remote server info and so on.

Returns:

an Object value containing connection info in any form.

getConnectionStatuses

public java.util.List getConnectionStatuses()

getConnectionStatuses method calculates and returns connection statuses in List. All objects stored in returned List should have implemented String toString() method to allow displaing info.
As statuses should be put info about transmision: average transfer speed, bytes received, transfer time and so on.

Returns:

an List value contain list of objects representing connection statuses.

setUserName

public void setUserName(java.lang.String name)

setUserName method sets user name for authorization. in general user name and pasword should be encoded in url with the form: http://user:passwd@www.sf.net:8000/path/file.html but sometimes it isn't possible to put user name and password in url and then you can set them with these methods.

Parameters:

name - a String value cotains user name.

getUserName

public java.lang.String getUserName()

getUserName method returns user name used during authorization process. User name can be taken from URI or from data received in setUserName(Strin name) method.

Returns:

a String value cotains user name.

setUserPassword

public void setUserPassword(java.lang.String password)

setUserPassword method sets user password dor authorization. in general user name and pasword should be encoded in url with the form: http://user:passwd@www.sf.net:8000/path/file.html but sometimes it isn't possible to put user name and password in url and then you can set them with these methods.

Parameters:

password - a String value cotains user password.

getUserPassword

public java.lang.String getUserPassword()

getUserPassword method returns user password used during authorization process. User name can be taken from URI or from data received in setUserName(Strin name) method.

Returns:

a String value cotains user password.

setDebug

public void setDebug(boolean debug)

Method setDebug sets debug mode.

Parameters:

debug - a boolean value of debug mode.

isDebug

public boolean isDebug()