All Packages Class Hierarchy This Package Previous Next Index
Class HTTPClient.HTTPConnection
java.lang.Object
|
+----HTTPClient.HTTPConnection
- public class HTTPConnection
- extends Object
- implements GlobalConstants, HTTPClientModuleConstants
This class implements http protocol requests; it contains most of HTTP/1.1
and ought to be unconditionally compliant.
Redirections are automatically handled, and authorizations requests are
recognized and dealt with via an authorization handler.
Only full HTTP/1.0 and HTTP/1.1 requests are generated. HTTP/1.1, HTTP/1.0
and HTTP/0.9 responses are recognized.
Using the HTTPClient should be quite simple. First add the import
statement 'import HTTPClient.*;
' to your file(s). Request
can then be sent using one of the methods Head(),
Get(), Post(), etc in HTTPConnection.
These methods all return an instance of HTTPResponse which
has methods for accessing the response headers (getHeader(),
getHeaderAsInt(), etc), various response info
(getStatusCode(), getReasonLine(), etc) and the
reponse data (getData() and getInputStream()).
Following are some examples.
If this is in an applet you can retrieve files from your server
as follows:
try
{
HTTPConnection con = new HTTPConnection(this);
HTTPResponse rsp = con.Get("/my_file");
if (rsp.getStatusCode() >= 300)
{
System.err.println("Received Error: "+rsp.getReasonLine());
System.err.println(new String(rsp.getData(),0));
}
else
data = rsp.getData();
rsp = con.Get("/another_file");
if (rsp.getStatusCode() >= 300)
{
System.err.println("Received Error: "+rsp.getReasonLine());
System.err.println(new String(rsp.getData(),0));
}
else
other_data = rsp.getData();
}
catch (IOException ioe)
{
System.err.println(ioe.toString());
}
catch (ModuleException me)
{
System.err.println("Error handling request: " + me.getMessage());
}
This will get the files "/my_file" and "/another_file" and put their
contents into byte[]s accessible via getData()
. Note that
you need to only create a new HTTPConnection when sending a
request to a new server (different host or port); although you may create
a new HTTPConnection for every request to the same server this
not recommended, as various information about the server
is cached after the first request (to optimize subsequent requests) and
persistent connections are used whenever possible.
To POST form data you would use something like this (assuming you
have two fields called name and e-mail, whose
contents are stored in the variables name and email):
try
{
NVPair form_data[] = new NVPair[2];
form_data[0] = new NVPair("name", name);
form_data[1] = new NVPair("e-mail", email);
HTTPConnection con = new HTTPConnection(this);
HTTPResponse rsp = con.Post("/cgi-bin/my_script", form_data);
if (rsp.getStatusCode() >= 300)
{
System.err.println("Received Error: "+rsp.getReasonLine());
System.err.println(new String(rsp.getData(),0));
}
else
stream = rsp.getInputStream();
}
catch (IOException ioe)
{
System.err.println(ioe.toString());
}
catch (ModuleException me)
{
System.err.println("Error handling request: " + me.getMessage());
}
Here the response data is read at leasure via an InputStream
instead of all at once into a byte[].
As another example, if you have a URL you're trying to send a request
to you would do something like the following:
try
{
URL url = new URL("http://www.mydomain.us/test/my_file");
HTTPConnection con = new HTTPConnection(url);
HTTPResponse rsp = con.Put(url.getFile(), "Hello World");
if (rsp.getStatusCode() >= 300)
{
System.err.println("Received Error: "+rsp.getReasonLine());
System.err.println(new String(rsp.getData(),0));
}
else
data = rsp.getData();
}
catch (IOException ioe)
{
System.err.println(ioe.toString());
}
catch (ModuleException me)
{
System.err.println("Error handling request: " + me.getMessage());
}
There are a whole number of methods for each request type; however the
general forms are ([...] means that the enclosed is optional):
- Head ( file [, form-data [, headers ] ] )
- Head ( file [, query [, headers ] ] )
- Get ( file [, form-data [, headers ] ] )
- Get ( file [, query [, headers ] ] )
- Post ( file [, form-data [, headers ] ] )
- Post ( file [, data [, headers ] ] )
- Post ( file [, stream [, headers ] ] )
- Put ( file , data [, headers ] )
- Put ( file , stream [, headers ] )
- Delete ( file [, headers ] )
- Options ( file [, headers [, data] ] )
- Options ( file [, headers [, stream] ] )
- Trace ( file [, headers ] )
- Version:
- 0.3 30/01/1998
- Author:
- Ronald Tschalär
-
version
- The current version of this package.
-
HTTPConnection(Applet)
- Constructs a connection to the host from where the applet was loaded.
-
HTTPConnection(String)
- Constructs a connection to the specified host on port 80
-
HTTPConnection(String, int)
- Constructs a connection to the specified host on the specified port
-
HTTPConnection(String, String, int)
- Constructs a connection to the specified host on the specified port,
using the specified protocol (currently only "http" is supported).
-
HTTPConnection(URL)
- Constructs a connection to the host (port) as given in the url.
-
addBasicAuthorization(String, String, String)
- Adds an authorization entry for the "basic" authorization scheme to
the list.
-
addDefaultModule(Class, int)
- Adds a module to the default list.
-
addDigestAuthorization(String, String, String)
- Adds an authorization entry for the "digest" authorization scheme to
the list.
-
addModule(Class, int)
- Adds a module to the current list.
-
Delete(String)
- Requests that file be DELETEd from the server.
-
Delete(String, NVPair[])
- Requests that file be DELETEd from the server.
-
dontProxyFor(String)
- Add host to the list of hosts which should be accessed
directly, not via any proxy set by
setProxyServer()
.
-
doProxyFor(String)
- Remove host from the list of hosts for which the proxy
should not be used.
-
ExtensionMethod(String, String, byte[], NVPair[])
- This is here to allow an arbitrary, non-standard request to be sent.
-
ExtensionMethod(String, String, HttpOutputStream, NVPair[])
- This is here to allow an arbitrary, non-standard request to be sent.
-
Get(String)
- GETs the file.
-
Get(String, NVPair[])
- GETs the file with a query consisting of the specified form-data.
-
Get(String, NVPair[], NVPair[])
- GETs the file with a query consisting of the specified form-data.
-
Get(String, String)
- GETs the file using the specified query string.
-
Get(String, String, NVPair[])
- GETs the file using the specified query string.
-
getAllowUserInteraction()
- returns whether modules are allowed to prompt or popup dialogs
if neccessary.
-
getContext()
- Returns the current context.
-
getDefaultAllowUserInteraction()
- Gets the default allow-user-action.
-
getDefaultHeaders()
- Gets the current list of default http headers.
-
getDefaultModules()
- Returns the default list of modules.
-
getDefaultTimeout()
- Gets the default timeout value to be used for each new HTTPConnection.
-
getHost()
- Returns the host this connection is talking to.
-
getModules()
- Returns the list of modules used currently.
-
getPort()
- Returns the port this connection connects to.
-
getProtocol()
- Returns the protocol this connection is talking.
-
getProxyHost()
- Returns the host of the proxy this connection is using.
-
getProxyPort()
- Returns the port of the proxy this connection is using.
-
getTimeout()
- Gets the timeout used for reading response data.
-
Head(String)
- Sends the HEAD request.
-
Head(String, NVPair[])
- Sends the HEAD request.
-
Head(String, NVPair[], NVPair[])
- Sends the HEAD request.
-
Head(String, String)
- Sends the HEAD request.
-
Head(String, String, NVPair[])
- Sends the HEAD request.
-
Options(String)
- Request OPTIONS from the server.
-
Options(String, NVPair[])
- Request OPTIONS from the server.
-
Options(String, NVPair[], byte[])
- Request OPTIONS from the server.
-
Options(String, NVPair[], HttpOutputStream)
- Request OPTIONS from the server.
-
Post(String)
- POSTs to the specified file.
-
Post(String, byte[])
- POSTs the raw data to the specified file.
-
Post(String, byte[], NVPair[])
- POSTs the raw data to the specified file using the specified headers.
-
Post(String, HttpOutputStream)
- POSTs the data written to the output stream to the specified file.
-
Post(String, HttpOutputStream, NVPair[])
- POSTs the data written to the output stream to the specified file
using the specified headers.
-
Post(String, NVPair[])
- POSTs form-data to the specified file.
-
Post(String, NVPair[], NVPair[])
- POST's form-data to the specified file using the specified headers.
-
Post(String, String)
- POSTs the data to the specified file.
-
Post(String, String, NVPair[])
- POSTs the data to the specified file using the specified headers.
-
Put(String, byte[])
- PUTs the raw data into the specified file.
-
Put(String, byte[], NVPair[])
- PUTs the raw data into the specified file using the additional
headers.
-
Put(String, HttpOutputStream)
- PUTs the data written to the output stream into the specified file.
-
Put(String, HttpOutputStream, NVPair[])
- PUTs the data written to the output stream into the specified file
using the additional headers.
-
Put(String, String)
- PUTs the data into the specified file.
-
Put(String, String, NVPair[])
- PUTs the data into the specified file using the additional headers
for the request.
-
removeDefaultModule(Class)
- Removes a module from the default list.
-
removeModule(Class)
- Removes a module from the current list.
-
setAllowUserInteraction(boolean)
- Controls whether modules are allowed to prompt the user or pop up
dialogs if neccessary.
-
setContext(Object)
- Sets the current context.
-
setCurrentProxy(String, int)
- Sets the proxy used by this instance.
-
setDefaultAllowUserInteraction(boolean)
- Sets the default allow-user-action.
-
setDefaultHeaders(NVPair[])
- Sets the default http headers to be sent with each request.
-
setDefaultTimeout(int)
- Sets the default timeout value to be used for each new HTTPConnection.
-
setProxyServer(String, int)
- Sets the default proxy server to use.
-
setRawMode(boolean)
- Sets/Resets raw mode.
Deprecated.
-
setSocksServer(String)
- Sets the SOCKS server to use.
-
setSocksServer(String, int)
- Sets the SOCKS server to use.
-
setSocksServer(String, int, int)
- Sets the SOCKS server to use.
-
setTimeout(int)
- Sets the timeout to be used for creating connections and reading
responses.
-
stop()
- Aborts all the requests currently in progress on this connection and
closes all associated sockets.
-
toString()
- Generates a string of the form protocol://host.domain:port .
-
Trace(String)
- Requests a TRACE.
-
Trace(String, NVPair[])
- Requests a TRACE.
version
public static final String version
- The current version of this package.
HTTPConnection
public HTTPConnection(Applet applet) throws ProtocolNotSuppException
- Constructs a connection to the host from where the applet was loaded.
Note that current security policies only let applets connect home.
- Parameters:
- applet - the current applet
HTTPConnection
public HTTPConnection(String host)
- Constructs a connection to the specified host on port 80
- Parameters:
- host - the host
HTTPConnection
public HTTPConnection(String host,
int port)
- Constructs a connection to the specified host on the specified port
- Parameters:
- host - the host
- port - the port
HTTPConnection
public HTTPConnection(String prot,
String host,
int port) throws ProtocolNotSuppException
- Constructs a connection to the specified host on the specified port,
using the specified protocol (currently only "http" is supported).
- Parameters:
- prot - the protocol
- host - the host
- port - the port, or -1 for the default port
- Throws:
ProtocolNotSuppException
- if the protocol is not HTTP
HTTPConnection
public HTTPConnection(URL url) throws ProtocolNotSuppException
- Constructs a connection to the host (port) as given in the url.
- Parameters:
- url - the url
- Throws:
ProtocolNotSuppException
- if the protocol is not HTTP
Head
public HTTPResponse Head(String file) throws IOException, ModuleException
- Sends the HEAD request. This request is just like the corresponding
GET except that it only returns the headers and no data.
- Parameters:
- file - the absolute path of the file
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
- See Also:
- Get
Head
public HTTPResponse Head(String file,
NVPair[] form_data) throws IOException, ModuleException
- Sends the HEAD request. This request is just like the corresponding
GET except that it only returns the headers and no data.
- Parameters:
- file - the absolute path of the file
- form_data - an array of Name/Value pairs
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
- See Also:
- Get
Head
public HTTPResponse Head(String file,
NVPair[] form_data,
NVPair[] headers) throws IOException, ModuleException
- Sends the HEAD request. This request is just like the corresponding
GET except that it only returns the headers and no data.
- Parameters:
- file - the absolute path of the file
- form_data - an array of Name/Value pairs
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
- See Also:
- Get
Head
public HTTPResponse Head(String file,
String query) throws IOException, ModuleException
- Sends the HEAD request. This request is just like the corresponding
GET except that it only returns the headers and no data.
- Parameters:
- file - the absolute path of the file
- query - the query string; it will be urlencoded
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
- See Also:
- Get
Head
public HTTPResponse Head(String file,
String query,
NVPair[] headers) throws IOException, ModuleException
- Sends the HEAD request. This request is just like the corresponding
GET except that it only returns the headers and no data.
- Parameters:
- file - the absolute path of the file
- query - the query string; it will be urlencoded
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
- See Also:
- Get
Get
public HTTPResponse Get(String file) throws IOException, ModuleException
- GETs the file.
- Parameters:
- file - the absolute path of the file
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Get
public HTTPResponse Get(String file,
NVPair[] form_data) throws IOException, ModuleException
- GETs the file with a query consisting of the specified form-data.
The data is urlencoded, turned into a string of the form
"name1=value1&name2=value2" and then sent as a query string.
- Parameters:
- file - the absolute path of the file
- form_data - an array of Name/Value pairs
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Get
public HTTPResponse Get(String file,
NVPair[] form_data,
NVPair[] headers) throws IOException, ModuleException
- GETs the file with a query consisting of the specified form-data.
The data is urlencoded, turned into a string of the form
"name1=value1&name2=value2" and then sent as a query string.
- Parameters:
- file - the absolute path of the file
- form_data - an array of Name/Value pairs
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Get
public HTTPResponse Get(String file,
String query) throws IOException, ModuleException
- GETs the file using the specified query string. The query string
is first urlencoded.
- Parameters:
- file - the absolute path of the file
- query - the query
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Get
public HTTPResponse Get(String file,
String query,
NVPair[] headers) throws IOException, ModuleException
- GETs the file using the specified query string. The query string
is first urlencoded.
- Parameters:
- file - the absolute path of the file
- query - the query string
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Post
public HTTPResponse Post(String file) throws IOException, ModuleException
- POSTs to the specified file. No data is sent.
- Parameters:
- file - the absolute path of the file
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Post
public HTTPResponse Post(String file,
NVPair[] form_data) throws IOException, ModuleException
- POSTs form-data to the specified file. The data is first urlencoded
and then turned into a string of the form "name1=value1&name2=value2".
A Content-type header with the value
application/x-www-form-urlencoded is added.
- Parameters:
- file - the absolute path of the file
- form_data - an array of Name/Value pairs
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Post
public HTTPResponse Post(String file,
NVPair[] form_data,
NVPair[] headers) throws IOException, ModuleException
- POST's form-data to the specified file using the specified headers.
The data is first urlencoded and then turned into a string of the
form "name1=value1&name2=value2". If no Content-type header
is given then one is added with a value of
application/x-www-form-urlencoded.
- Parameters:
- file - the absolute path of the file
- form_data - an array of Name/Value pairs
- headers - additional headers
- Returns:
- a HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Post
public HTTPResponse Post(String file,
String data) throws IOException, ModuleException
- POSTs the data to the specified file. The data is converted to an
array of bytes using the lower byte of each character.
The request is sent using the content-type "application/octet-stream".
- Parameters:
- file - the absolute path of the file
- data - the data
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
- See Also:
- java.lang.String#getBytes(int, int, byte[], int)
Post
public HTTPResponse Post(String file,
String data,
NVPair[] headers) throws IOException, ModuleException
- POSTs the data to the specified file using the specified headers.
- Parameters:
- file - the absolute path of the file
- data - the data
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Post
public HTTPResponse Post(String file,
byte[] data) throws IOException, ModuleException
- POSTs the raw data to the specified file.
The request is sent using the content-type "application/octet-stream"
- Parameters:
- file - the absolute path of the file
- data - the data
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Post
public HTTPResponse Post(String file,
byte[] data,
NVPair[] headers) throws IOException, ModuleException
- POSTs the raw data to the specified file using the specified headers.
- Parameters:
- file - the absolute path of the file
- data - the data
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Post
public HTTPResponse Post(String file,
HttpOutputStream stream) throws IOException, ModuleException
- POSTs the data written to the output stream to the specified file.
The request is sent using the content-type "application/octet-stream"
- Parameters:
- file - the absolute path of the file
- stream - the output stream on which the data is written
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Post
public HTTPResponse Post(String file,
HttpOutputStream stream,
NVPair[] headers) throws IOException, ModuleException
- POSTs the data written to the output stream to the specified file
using the specified headers.
- Parameters:
- file - the absolute path of the file
- stream - the output stream on which the data is written
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Put
public HTTPResponse Put(String file,
String data) throws IOException, ModuleException
- PUTs the data into the specified file. The data is converted to an
array of bytes using the lower byte of each character.
The request ist sent using the content-type "application/octet-stream".
- Parameters:
- file - the absolute path of the file
- data - the data
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
- See Also:
- java.lang.String#getBytes(int, int, byte[], int)
Put
public HTTPResponse Put(String file,
String data,
NVPair[] headers) throws IOException, ModuleException
- PUTs the data into the specified file using the additional headers
for the request.
- Parameters:
- file - the absolute path of the file
- data - the data
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Put
public HTTPResponse Put(String file,
byte[] data) throws IOException, ModuleException
- PUTs the raw data into the specified file.
The request is sent using the content-type "application/octet-stream".
- Parameters:
- file - the absolute path of the file
- data - the data
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Put
public HTTPResponse Put(String file,
byte[] data,
NVPair[] headers) throws IOException, ModuleException
- PUTs the raw data into the specified file using the additional
headers.
- Parameters:
- file - the absolute path of the file
- data - the data
- headers - any additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Put
public HTTPResponse Put(String file,
HttpOutputStream stream) throws IOException, ModuleException
- PUTs the data written to the output stream into the specified file.
The request is sent using the content-type "application/octet-stream".
- Parameters:
- file - the absolute path of the file
- stream - the output stream on which the data is written
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Put
public HTTPResponse Put(String file,
HttpOutputStream stream,
NVPair[] headers) throws IOException, ModuleException
- PUTs the data written to the output stream into the specified file
using the additional headers.
- Parameters:
- file - the absolute path of the file
- stream - the output stream on which the data is written
- headers - any additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Options
public HTTPResponse Options(String file) throws IOException, ModuleException
- Request OPTIONS from the server. If file is "*" then
the request applies to the server as a whole; otherwise it applies
only to that resource.
- Parameters:
- file - the absolute path of the resource, or "*"
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Options
public HTTPResponse Options(String file,
NVPair[] headers) throws IOException, ModuleException
- Request OPTIONS from the server. If file is "*" then
the request applies to the server as a whole; otherwise it applies
only to that resource.
- Parameters:
- file - the absolute path of the resource, or "*"
- headers - the headers containing optional info.
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Options
public HTTPResponse Options(String file,
NVPair[] headers,
byte[] data) throws IOException, ModuleException
- Request OPTIONS from the server. If file is "*" then
the request applies to the server as a whole; otherwise it applies
only to that resource.
- Parameters:
- file - the absolute path of the resource, or "*"
- headers - the headers containing optional info.
- data - any data to be sent in the optional body
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Options
public HTTPResponse Options(String file,
NVPair[] headers,
HttpOutputStream stream) throws IOException, ModuleException
- Request OPTIONS from the server. If file is "*" then
the request applies to the server as a whole; otherwise it applies
only to that resource.
- Parameters:
- file - the absolute path of the resource, or "*"
- headers - the headers containing optional info.
- stream - an output stream for sending the optional body
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Delete
public HTTPResponse Delete(String file) throws IOException, ModuleException
- Requests that file be DELETEd from the server.
- Parameters:
- file - the absolute path of the resource
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Delete
public HTTPResponse Delete(String file,
NVPair[] headers) throws IOException, ModuleException
- Requests that file be DELETEd from the server.
- Parameters:
- file - the absolute path of the resource
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Trace
public HTTPResponse Trace(String file,
NVPair[] headers) throws IOException, ModuleException
- Requests a TRACE. Headers of particular interest here are "Via"
and "Max-Forwards".
- Parameters:
- file - the absolute path of the resource
- headers - additional headers
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
Trace
public HTTPResponse Trace(String file) throws IOException, ModuleException
- Requests a TRACE.
- Parameters:
- file - the absolute path of the resource
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
ExtensionMethod
public HTTPResponse ExtensionMethod(String method,
String file,
byte[] data,
NVPair[] headers) throws IOException, ModuleException
- This is here to allow an arbitrary, non-standard request to be sent.
I'm assuming you know what you are doing...
- Parameters:
- method - the extension method
- file - the absolute path of the resource, or null
- data - optional data, or null
- headers - optional headers, or null
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
ExtensionMethod
public HTTPResponse ExtensionMethod(String method,
String file,
HttpOutputStream os,
NVPair[] headers) throws IOException, ModuleException
- This is here to allow an arbitrary, non-standard request to be sent.
I'm assuming you know what you are doing...
- Parameters:
- method - the extension method
- file - the absolute path of the resource, or null
- stream - optional output stream, or null
- headers - optional headers, or null
- Returns:
- an HTTPResponse structure containing the response
- Throws:
IOException
- when an exception is returned from
the socket.
- Throws:
ModuleException
- if an exception is encountered in any module.
stop
public void stop()
- Aborts all the requests currently in progress on this connection and
closes all associated sockets.
Note: there is a small window where a request method such as
Get()
may have been invoked but the request has not
been built and added to the list. Any request in this window will
not be aborted.
setDefaultHeaders
public void setDefaultHeaders(NVPair[] headers)
- Sets the default http headers to be sent with each request. The
actual headers sent are determined as follows: for each header
specified in multiple places a value given as part of the request
takes priority over any default values set by this method, which
in turn takes priority over any built-in default values. A different
way of looking at it is that we start off with a list of all headers
specified with the request, then add any default headers set by this
method which aren't already in our list, and finally add any built-in
headers which aren't yet in the list. There are two exceptions to this
rule: "Content-length" and "Host" headers are always ignored; and when
posting form-data any default "Content-type" is ignored in favor of
the built-in "application/x-www-form-urlencoded" (however it will be
overriden by any content-type header specified as part of the request).
Typical headers you might want to set here are "Accept" and its
"Accept-*" relatives, "Connection", "From", "User-Agent", etc.
- Parameters:
- headers - an array of header-name/value pairs (do not give the
separating ':').
getDefaultHeaders
public NVPair[] getDefaultHeaders()
- Gets the current list of default http headers.
- Returns:
- an array of header/value pairs.
getProtocol
public String getProtocol()
- Returns the protocol this connection is talking.
- Returns:
- a string containing the protocol
getHost
public String getHost()
- Returns the host this connection is talking to.
- Returns:
- a string containing the host name.
getPort
public int getPort()
- Returns the port this connection connects to.
- Returns:
- the port number
getProxyHost
public String getProxyHost()
- Returns the host of the proxy this connection is using.
- Returns:
- a string containing the host name.
getProxyPort
public int getProxyPort()
- Returns the port of the proxy this connection is using.
- Returns:
- the port number
setRawMode
public void setRawMode(boolean raw)
- Note: setRawMode() is deprecated.
This is not really needed anymore; in V0.2 request were
synchronous and therefore to do pipelining you needed
to disable the processing of responses.
- Sets/Resets raw mode. In raw mode all modules are bypassed, meaning
the automatic handling of authorization requests, redirections,
cookies, etc. is turned off.
The default is false.
- Parameters:
- raw - if true removes all modules (except for the retry module)
- See Also:
- removeModule
setDefaultTimeout
public static void setDefaultTimeout(int time)
- Sets the default timeout value to be used for each new HTTPConnection.
The default is 0.
- Parameters:
- time - the timeout in milliseconds.
- See Also:
- setTimeout
getDefaultTimeout
public static int getDefaultTimeout()
- Gets the default timeout value to be used for each new HTTPConnection.
- Returns:
- the timeout in milliseconds.
- See Also:
- setTimeout
setTimeout
public void setTimeout(int time)
- Sets the timeout to be used for creating connections and reading
responses. When a timeout expires the operation will throw an
InterruptedIOException. The operation may be restarted again
afterwards.
When creating new sockets the timeout will limit the time spent
doing the host name translation and establishing the connection with
the server.
The timeout also influences the reading of the response headers.
However, it does not specify a how long, for example, getStatusCode()
may take, as might be assumed. Instead it specifies how long a read
on the socket may take. If the response dribbles in slowly with
packets arriving quicker than the timeout then the method will
complete normally. I.e. the exception is only thrown if nothing
arrives on the socket for the specified time. Furthermore, the
timeout only influences the reading of the headers, not the reading
of the body.
Read Timeouts are associated with responses, so that you may change
this value before each request and it won't affect the reading of
responses to previous requests.
Note: The read timeout only works with JDK 1.1 or later.
Using this method with JDK 1.0.2 or earlier will only influence the
connection creation.
- Parameters:
- time - the time in milliseconds. A time of 0 means wait
indefinitely.
getTimeout
public int getTimeout()
- Gets the timeout used for reading response data.
- Returns:
- the current timeout value
- See Also:
- setTimeout
setAllowUserInteraction
public void setAllowUserInteraction(boolean allow)
- Controls whether modules are allowed to prompt the user or pop up
dialogs if neccessary.
- Parameters:
- allow - if true allows modules to interact with user.
getAllowUserInteraction
public boolean getAllowUserInteraction()
- returns whether modules are allowed to prompt or popup dialogs
if neccessary.
- Returns:
- true if modules are allowed to interact with user.
setDefaultAllowUserInteraction
public static void setDefaultAllowUserInteraction(boolean allow)
- Sets the default allow-user-action.
- Parameters:
- allow - if true allows modules to interact with user.
getDefaultAllowUserInteraction
public static boolean getDefaultAllowUserInteraction()
- Gets the default allow-user-action.
- Returns:
- true if modules are allowed to interact with user.
getDefaultModules
public static Class[] getDefaultModules()
- Returns the default list of modules.
- Returns:
- an array of classes
addDefaultModule
public static boolean addDefaultModule(Class module,
int pos)
- Adds a module to the default list. It must implement the
HTTPClientModule interface. If the module is already in
the list then this method does nothing.
Example:
HTTPConnection.addDefaultModule(Class.forName("HTTPClient.CookieModule"), 1);
adds the cookie module as the second module in the list.
The default list is created at class initialization time from the
property HTTPClient.Modules. This must contain a "|"
separated list of classes in the order they're to be invoked. If this
property is not set it defaults to:
"HTTPClient.RetryModule | HTTPClient.CookieModule |
HTTPClient.RedirectionModule | HTTPClient.AuthorizationModule |
HTTPClient.DefaultModule | HTTPClient.TransferEncodingModule |
HTTPClient.ContentMD5Module | HTTPClient.ContentEncodingModule"
- Parameters:
- module - the module's Class object
- pos - the position of this module in the list; if pos
>= 0 then this is the absolute position in the list (0 is
the first position); if pos < 0 then this is
the position relative to the end of the list (-1 means
the last element, -2 the second to last element, etc).
- Returns:
- true if module was successfully added; false if the
module is already in the list.
- Throws:
ArrayIndexOutOfBoundsException
- if pos >
list-size or if pos < -(list-size).
- Throws:
ClassCastException
- if module does not
implement the HTTPClientModule interface.
- Throws:
RuntimeException
- if module cannot be
instantiated.
- See Also:
- HTTPClientModule
removeDefaultModule
public static boolean removeDefaultModule(Class module)
- Removes a module from the default list. If the module is not in the
list it does nothing.
- Parameters:
- module - the module's Class object
- Returns:
- true if module was successfully removed; false otherwise
getModules
public Class[] getModules()
- Returns the list of modules used currently.
- Returns:
- an array of classes
addModule
public boolean addModule(Class module,
int pos)
- Adds a module to the current list. It must implement the
HTTPClientModule interface. If the module is already in
the list then this method does nothing.
- Parameters:
- module - the module's Class object
- pos - the position of this module in the list; if pos
>= 0 then this is the absolute position in the list (0 is
the first position); if pos < 0 then this is
the position relative to the end of the list (-1 means
the last element, -2 the second to last element, etc).
- Returns:
- true if module was successfully added; false if the
module is already in the list.
- Throws:
ArrayIndexOutOfBoundsException
- if pos >
list-size or if pos < -(list-size).
- Throws:
ClassCastException
- if module does not
implement the HTTPClientModule interface.
- Throws:
RuntimeException
- if module cannot be
instantiated.
- See Also:
- HTTPClientModule
removeModule
public boolean removeModule(Class module)
- Removes a module from the current list. If the module is not in the
list it does nothing.
- Parameters:
- module - the module's Class object
- Returns:
- true if module was successfully removed; false otherwise
setContext
public void setContext(Object context)
- Sets the current context. The context is used by modules such as
the AuthorizationModule and the CookieModule which keep lists of
info that is normally shared between all instances of HTTPConnection.
This is usually the desired behaviour. However, in some cases one
would like to simulate multiple independent clients within the
same application and hence the sharing of such info should be
restricted. This is where the context comes in. Modules will only
share their info between requests using the same context (i.e. they
keep multiple lists, one for each context). The context may be any
object.
When a new HTTPConnection is created it is initialized with a
default context which is the same for all instances. This method
must be invoked immediately after a new HTTPConnection is created
and before any request method is invoked. Furthermore, this method
may only be called once (i.e. the context is "sticky").
- Parameters:
- context - the new context; must be non-null
- Throws:
IllegalArgumentException
- if context is null
- Throws:
RuntimeException
- if the context has already been set
getContext
public Object getContext()
- Returns the current context.
- Returns:
- the current context, or the default context if
setContext()
hasn't been invoked - See Also:
- setContext
addDigestAuthorization
public void addDigestAuthorization(String realm,
String user,
String passwd)
- Adds an authorization entry for the "digest" authorization scheme to
the list. If an entry already exists for the "digest" scheme and the
specified realm then it is overwritten.
This is a convenience method and just invokes the corresponding
method in AuthorizationInfo.
- Parameters:
- realm - the realm
- user - the username
- passw - the password
- See Also:
- addDigestAuthorization
addBasicAuthorization
public void addBasicAuthorization(String realm,
String user,
String passwd)
- Adds an authorization entry for the "basic" authorization scheme to
the list. If an entry already exists for the "basic" scheme and the
specified realm then it is overwritten.
This is a convenience method and just invokes the corresponding
method in AuthorizationInfo.
- Parameters:
- realm - the realm
- user - the username
- passw - the password
- See Also:
- addBasicAuthorization
setProxyServer
public static void setProxyServer(String host,
int port)
- Sets the default proxy server to use. The proxy will only be used
for new HTTPConnections created after this call and will
not affect currrent instances of HTTPConnection. A null
or empty string host parameter disables the proxy.
In an application or using the Appletviewer an alternative to
this method is to set the following properties (either in the
properties file or on the command line):
http.proxyHost and http.proxyPort. Whether
http.proxyHost is set or not determines whether a proxy
server is used.
If the proxy server requires authorization and you wish to set
this authorization information in the code, then you may use any
of the AuthorizationInfo.addXXXAuthorization() methods to
do so. Specify the same host and port as in
this method. If you have not given any authorization info and the
proxy server requires authorization then you will be prompted for
the necessary info via a popup the first time you do a request.
- Parameters:
- host - the host on which the proxy server resides.
- port - the port the proxy server is listening on.
- See Also:
- setCurrentProxy
setCurrentProxy
public void setCurrentProxy(String host,
int port)
- Sets the proxy used by this instance. This can be used to override
the proxy setting inherited from the default proxy setting. A null
or empty string host parameter disables the proxy.
- Parameters:
- host - the host the proxy runs on
- port - the port the proxy is listening on
- See Also:
- setProxyServer
dontProxyFor
public static void dontProxyFor(String host) throws ParseException
- Add host to the list of hosts which should be accessed
directly, not via any proxy set by
setProxyServer()
.
The host may be any of:
- a complete host name (e.g. "www.disney.com")
- a domain name; domain names must begin with a dot (e.g.
".disney.com")
- an IP-address (e.g. "12.34.56.78")
- an IP-subnet, specified as an IP-address and a netmask separated
by a "/" (e.g. 34.56.78/255.255.255.192"); a 0 bit in the netmask
means that that bit won't be used in the comparison (i.e. the
addresses are AND'ed with the netmask before comparison).
The two properties HTTPClient.nonProxyHosts and
http.nonProxyHosts are used when this class is loaded to
initialize the list of non-proxy hosts. The second property is only
read if the first one is not set; the second property is also used
the JDK's URLConnection. These properties must contain a "|"
separated list of entries which conform to the above rules for the
host parameter (e.g. "11.22.33.44|.disney.com").
- Parameters:
- host - a host name, domain name, IP-address or IP-subnet.
- Throws:
ParseException
- if the length of the netmask does not match
the length of the IP-address
doProxyFor
public static boolean doProxyFor(String host) throws ParseException
- Remove host from the list of hosts for which the proxy
should not be used. The syntax for host is specified in
dontProxyFor()
.
- Parameters:
- host - a host name, domain name, IP-address or IP-subnet.
- Returns:
- true if the remove was sucessful, false otherwise
- Throws:
ParseException
- if the length of the netmask does not match
the length of the IP-address
- See Also:
- dontProxyFor
setSocksServer
public static void setSocksServer(String host)
- Sets the SOCKS server to use. The server will only be used
for new HTTPConnections created after this call and will not affect
currrent instances of HTTPConnection. A null or empty string host
parameter disables SOCKS.
The code will try to determine the SOCKS version to use at
connection time. This might fail for a number of reasons, however,
in which case you must specify the version explicitly.
- Parameters:
- host - the host on which the proxy server resides. The port
used is the default port 1080.
- See Also:
- setSocksServer
setSocksServer
public static void setSocksServer(String host,
int port)
- Sets the SOCKS server to use. The server will only be used
for new HTTPConnections created after this call and will not affect
currrent instances of HTTPConnection. A null or empty string host
parameter disables SOCKS.
The code will try to determine the SOCKS version to use at
connection time. This might fail for a number of reasons, however,
in which case you must specify the version explicitly.
- Parameters:
- host - the host on which the proxy server resides.
- port - the port the proxy server is listening on.
- See Also:
- setSocksServer
setSocksServer
public static void setSocksServer(String host,
int port,
int version) throws SocksException
- Sets the SOCKS server to use. The server will only be used
for new HTTPConnections created after this call and will not affect
currrent instances of HTTPConnection. A null or empty string host
parameter disables SOCKS.
In an application or using the Appletviewer an alternative to
this method is to set the following properties (either in the
properties file or on the command line):
HTTPClient.socksHost, HTTPClient.socksPort
and HTTPClient.socksVersion. Whether
HTTPClient.socksHost is set or not determines whether a
SOCKS server is used; if HTTPClient.socksPort is not set
it defaults to 1080; if HTTPClient.socksVersion is not
set an attempt will be made to automatically determine the version
used by the server.
Note: If you have also set a proxy server then a connection
will be made to the SOCKS server, which in turn then makes a
connection to the proxy server (possibly via other SOCKS servers),
which in turn makes the final connection.
If the proxy server is running SOCKS version 5 and requires
username/password authorization, and you wish to set
this authorization information in the code, then you may use the
AuthorizationInfo.addAuthorization() method to do so.
Specify the same host and port as in this
method, give the scheme "SOCKS5" and the realm
"USER/PASS", set the cookie to null and the
params to an array containing a single NVPair
in turn containing the username and password. Example:
NVPair[] up = { new NVPair(username, password) };
AuthorizationInfo.addAuthorization(host, port, "SOCKS5", "USER/PASS",
null, up);
If you have not given any authorization info and the proxy server
requires authorization then you will be prompted for the necessary
info via a popup the first time you do a request.
- Parameters:
- host - the host on which the proxy server resides.
- port - the port the proxy server is listening on.
- version - the SOCKS version the server is running. Currently
this must be '4' or '5'.
- Throws:
SocksException
- If version is not '4' or '5'.
toString
public String toString()
- Generates a string of the form protocol://host.domain:port .
- Returns:
- the string
- Overrides:
- toString in class Object
All Packages Class Hierarchy This Package Previous Next Index