ewe.net
Class HttpConnection

java.lang.Object
  ewe.net.HttpConnection

public class HttpConnection

extends Object

Use this class to create an HttpConnection with a Web Server and to read in the data for the connection.

To use this do the following:

1. Create an HttpConnection object with a URL or specify the host, port and document to get.
2. Change any of the HttpConnection parameters (including documentIsEncoded if your document is URL encoded - i.e. it has '?' type data within it) and set requestor properties as needed.
3. Call connectAsync() or connect() to make a Socket that is connected with the server. These methods will also send the Http request (e.g. GET or POST), send the requestor parameters and then read in and parse the server response and server parameters. When these methods are complete the next data to be read in from the Socket will be the actual data bytes for the http tranfer.
4. Call redirectTo() to see if the request resulted in a redirection response from the server. If redirectTo() returns a new HttpConnection object, then close the open Socket and go back to step 2 using the new HttpConnection object instead.
5. Call readInData() with the connected Socket to read in the raw data bytes of the requested document or call readInText() to read in and convert the document to text.

Field Summary

String	command This is the command to be sent to the server.
protected Socket	connectedSocket
int	contentLength This is the length of the document read in, valid after a connection call.
static int	DataReady
String	document The document to fetch/submit.
boolean	documentIsEncoded If the document you supplied is already URL encoded, set this to true.
PropertyList	documentProperties This is the list of properties for the server and document.
String	host The host to connect to.
boolean	keepAliveMode Set this to true for keep alive mode requests.
protected Socket	openSocket
int	port The port to connect to.
PropertyList	requestorProperties These are the properties that will be sent to the WebServer.
String	requestVersion This is the version sent to the server.
int	responseCode This is the response code from the server.
static int	SocketConnected

Constructor Summary

HttpConnection(String url)
Create an HttpConnection with an http:// URL.

HttpConnection(String host, int port, String document)
Create a new HttpConnection to the specified host and port to fetch the specified document.

HttpConnection(URL url)

Method Summary

void	addRequestorProperty(String name, String property) Add a non-exclusive requestor property.
Socket	connect() This makes the connection, blocking the current thread.
Handle	connectAsync() Connect asynchronously.
Handle	connectAsync(TextCodec serverTextDecoder) Connect asynchronously.
Socket	connectSocketOnly() Connect to the server and save the socket for later use as the "connectedSocket" field.
String	getEncodedDocument()
InputStream	getInputStream() Get an InputStream to read in the data.
PropertyList	getRequestorProperties() Returns the requestor properties.
ByteArray	readData(Socket connection) Read in the document body from the Socket.
Handle	readInData() Read in all the data from the Socket.
Handle	readInData(Socket connection) Read in all the data from the Socket.
Handle	readInText(Socket connection, TextCodec documentTextDecoder) Read in all the data from the Socket, converting it to text using the specified codec.
CharArray	readText(Socket connection, TextCodec documentTextDecoder) Read in the document body from the Socket.
HttpConnection	redirectTo() Call this after a successful connection.
void	setAlreadyOpenSocket(Socket sock) If a connection has already been made to the server, then you can call this method and the HttpConnection protocol will be done over this Socket.
void	setPostData(Object data) Set the data to post out as either a Stream, InputStream or byte[] or ByteArray.
void	setPostDataLength(int length) This sets the "Content-Length" requestor property to be the specified length.
void	setRequestorProperty(String name, String property) Set an exclusive requestor property.
String	toURLString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

host

public String host

The host to connect to.

port

public int port

The port to connect to.

document

public String document

The document to fetch/submit.

command

public String command

This is the command to be sent to the server. By default it is "GET". If you call setPostData() and command is "GET" then the command will be replaced by "POST".

requestVersion

public String requestVersion

This is the version sent to the server. By default it is "HTTP/1.1". You could change it to something else if necessary.

requestorProperties

public PropertyList requestorProperties

These are the properties that will be sent to the WebServer. These are sent after the initial GET/POST line. This is initially null, so you will have to create a new PropertyList for it, or use one of the setRequestorProperty() or addRequestorProperty() methods.

documentProperties

public PropertyList documentProperties

This is the list of properties for the server and document. It is only valid after a connection has been made since it is sent by the server to the requestor. One properties that will always be in this list will be "response" (the first line sent by the server in response to the request). All other properties will be as specified by the server, and the property names will be converted to all lowercase letters.

responseCode

public int responseCode

This is the response code from the server. It is only valid after a connection has been made.

documentIsEncoded

public boolean documentIsEncoded

If the document you supplied is already URL encoded, set this to true.

keepAliveMode

public boolean keepAliveMode

Set this to true for keep alive mode requests.

contentLength

public int contentLength

This is the length of the document read in, valid after a connection call. If it is -1, then the web server has not provided the length of the document.

openSocket

protected Socket openSocket

connectedSocket

protected Socket connectedSocket

SocketConnected

public static final int SocketConnected

See Also:

Constant Field Values

DataReady

public static final int DataReady

See Also:

Constant Field Values

Constructor Detail

HttpConnection

public HttpConnection(String host,
                      int port,
                      String document)

Create a new HttpConnection to the specified host and port to fetch the specified document.

Parameters:

host - The host to connect to.

port - The port to connect on.

document - the document to get.

HttpConnection

public HttpConnection(String url)

Create an HttpConnection with an http:// URL.

Parameters:

url - The full url, starting with http://

HttpConnection

public HttpConnection(URL url)

Method Detail

getRequestorProperties

public PropertyList getRequestorProperties()

Returns the requestor properties. These are the property commands sent to the server when the connection is made. You can add directly to this OR you can call setRequestorProperty() or addRequestorProperty();

setPostData

public void setPostData(Object data)

Set the data to post out as either a Stream, InputStream or byte[] or ByteArray. If the data is a Stream or InputStream then you must also call setPostDataLength() which in turn sets the "Content-Length" property of the requestor properties - otherwise if "Content-Length" is not already set it will be set to the length of the byte[] or ByteArray.

Parameters:

data - the data to post either as a Stream, InputStream, byte[] or ByteArray

setPostDataLength

public void setPostDataLength(int length)

This sets the "Content-Length" requestor property to be the specified length.

Parameters:

length - the number of bytes to be posted.

setRequestorProperty

public void setRequestorProperty(String name,
                                 String property)

Set an exclusive requestor property. These are sent to the web server after the initial request line.

Parameters:

name - The name of the property.

property - The value of the property.

addRequestorProperty

public void addRequestorProperty(String name,
                                 String property)

Add a non-exclusive requestor property. These are sent to the web server after the initial request line.

Parameters:

name - The name of the property.

property - The value of the property.

setAlreadyOpenSocket

public void setAlreadyOpenSocket(Socket sock)

If a connection has already been made to the server, then you can call this method and the HttpConnection protocol will be done over this Socket.

Parameters:

sock - The already connected socket.

toURLString

public String toURLString()

getEncodedDocument

public String getEncodedDocument()

redirectTo

public HttpConnection redirectTo()

Call this after a successful connection. If the server requested a redirect (a 3xx code) then this will return an HttpConnection to the new location which you can connect to again. You must setup any post data or requestor properties again before re-connecting. If there is no redirection required or possible the method will return this same HttpConnection.

readInData

public Handle readInData(Socket connection)

Read in all the data from the Socket.

Parameters:

connection - The socket returned by a connect() call.

Returns:

A Handle with which you can monitor the connection. When the Handle reports Success, then the returnValue of the Handle will be a ewe.util.ByteArray object that holds the data read in.

readInData

public Handle readInData()

Read in all the data from the Socket.

Returns:

A Handle with which you can monitor the connection. When the Handle reports Success, then the returnValue of the Handle will be a ewe.util.ByteArray object that holds the data read in.

getInputStream

public InputStream getInputStream()
                           throws IOException

Get an InputStream to read in the data. This is a very important method as it is used by the readInData() method.

Throws:

IOException

readData

public ByteArray readData(Socket connection)
                   throws IOException

Read in the document body from the Socket. This method blocks until the complete data is read in. readInData() is a non-blocking version.

Parameters:

connection - The socket returned by a connect() call.

Returns:

A ByteArray containing the read in data.

Throws:

IOException

readInText

public Handle readInText(Socket connection,
                         TextCodec documentTextDecoder)

Read in all the data from the Socket, converting it to text using the specified codec.

Parameters:

connection - The socket returned by a connect() call.

documentTextDecoder - The text codec to use to convert the bytes read in into text. If this is null then a simple Ascii codec will be used.

Returns:

A Handle with which you can monitor the connection. When the Handle reports Success, then the returnValue of the Handle will be a ewe.util.CharArray object that holds the text read in.

readText

public CharArray readText(Socket connection,
                          TextCodec documentTextDecoder)
                   throws IOException

Read in the document body from the Socket. This method blocks until the complete data is read in. readInText() is a non-blocking version.

Parameters:

connection - The socket returned by a connect() call.

documentTextDecoder - The text codec to use to convert the bytes read in into text. If this is null then a simple Ascii codec will be used.

Returns:

A CharArray containing the text that was read in.

Throws:

IOException

connectAsync

public Handle connectAsync()

Connect asynchronously. This makes the connection, sends the request and requestor properties reads in the reply and server properties and then returns the connected Socket ready for for reading in the actual data.

Returns:

A Handle used to monitor the connection. When the Handle reports a state of Success, then the returnValue of the IOHandle will hold the connected socket.

connectAsync

public Handle connectAsync(TextCodec serverTextDecoder)

Connect asynchronously. This makes the connection, sends the request and requestor properties reads in the reply and server properties and then returns the connected Socket ready for for reading in the actual data.

Parameters:

serverTextDecoder - The text decoder to convert the server and requestor properties data into text.

Returns:

A Handle used to monitor the connection. When the Handle reports a state of Success, then the returnValue of the Handle will hold the connected socket.

connect

public Socket connect()
               throws IOException

This makes the connection, blocking the current thread.

Returns:

A Socket that you can read the data from. The document properties will be in the document properties list.

Throws:

IOException - if there was an error connecting or getting the data.

connectSocketOnly

public Socket connectSocketOnly()
                         throws IOException

Connect to the server and save the socket for later use as the "connectedSocket" field.

Returns:

the connected socket - before any data is sent or read.

Throws:

IOException - if a connection could not be made.