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()


Copyright GNU, wttools developers Team.