Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

HTTPClient
Class HTTPConnection  view HTTPConnection download HTTPConnection.java

java.lang.Object
  extended byHTTPClient.HTTPConnection
All Implemented Interfaces:
GlobalConstants, HTTPClientModuleConstants

public class HTTPConnection
extends java.lang.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()));
         }
         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()));
         }
         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()));
         }
         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()));
         }
         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):

Version:
0.3-2E 13/11/1999

Nested Class Summary
private  class HTTPConnection.EstablishConnection
           
private  class HTTPConnection.MSLargeWritesBugStream
          M$ has yet another bug in their WinSock: if you try to write too much data at once it'll hang itself.
 
Field Summary
private  boolean AllowUI
          controls whether modules are allowed to interact with user
static int CD_0
           
static int CD_CHUNKED
           
static int CD_CLOSE
           
static int CD_CONTLEN
           
static int CD_HDRS
           
static int CD_MP_BR
           
static int CD_NONE
          Content delimiters
private  java.lang.Object Context
          The current context
static boolean DebugAll
          Debug variables
static boolean DebugAuth
           
static boolean DebugConn
           
static boolean DebugDemux
           
static boolean DebugMods
           
static boolean DebugResp
           
static boolean DebugSocks
           
static boolean DebugURLC
           
private static java.lang.String Default_Proxy_Host
          The default proxy host to use (if any)
private static int Default_Proxy_Port
          The default proxy port
private static SocksClient Default_Socks_client
          The default socks server to use
private static boolean DefaultAllowUI
          controls whether modules are allowed to interact with user
private  NVPair[] DefaultHeaders
          The list of default http headers
private static java.util.Vector DefaultModuleList
          The default list of modules (as a Vector of Class objects)
private static int DefaultTimeout
          the default timeout to use for new connections
(package private)  LinkedList DemuxList
          a list of active stream demultiplexors
private static java.lang.Object dflt_context
          The default context
private  boolean DoesKeepAlive
          does the server support keep-alive's?
private  Response early_stall
          These mark the response to stall the next request on, if any
private static boolean force_1_0
          hack to force HTTP/1.0 requests
private static boolean haveMSLargeWritesBug
          hack to work around M$ bug
private  java.lang.String Host
          The remote host this connection is associated with
static int HTTP
          possible http protocols we (might) handle
static int HTTP_1_0
          some known http versions
static int HTTP_1_1
           
static int HTTP_NG
           
static int HTTPS
           
private  StreamDemultiplexor input_demux
          the current stream demultiplexor
private  int KeepAliveReqLeft
          the number of requests over a HTTP/1.0 keep-alive connection left
private  int KeepAliveReqMax
          the maximum number of requests over a HTTP/1.0 keep-alive connection
private  boolean KeepAliveUnknown
          have we been able to determine the above yet?
protected static java.lang.String keyStoreLocation
           
protected static java.lang.String keyStorePassword
          Variable that hold SSL information and their setter methods
private  Response late_stall
           
private  java.util.Vector ModuleList
          The list of modules (as a Vector of Class objects)
private static boolean NeverPipeline
          hack to be able to disable pipelining
private static boolean no_chunked
          hack to force buffering of data instead of using chunked T-E
private static boolean NoKeepAlives
          hack to be able to disable keep-alives
private static java.util.Vector non_proxy_addr_list
           
private static java.util.Vector non_proxy_dom_list
           
private static CIHashtable non_proxy_host_list
          The list of hosts for which no proxy is to be used
private static java.util.Vector non_proxy_mask_list
           
private  boolean output_finished
          This marks the socket output stream as still being used
private  int Port
          The remote port this connection is attached to
private  Response prev_resp
           
private  int Protocol
          The protocol used on this connection
private  java.lang.String Proxy_Host
          The current proxy host to use (if any)
private  int Proxy_Port
          The current proxy port
private  LinkedList RequestList
          a list of active requests
private  java.lang.String RequestProtocolVersion
          The protocol version we send in a request; this is always HTTP/1.1 unless we're talking to a broken server in which case it's HTTP/1.0
(package private)  int ServerProtocolVersion
          The server's protocol version; M.m stored as (M<<16 | m)
(package private)  boolean ServProtVersKnown
          Have we gotten the server's protocol version yet?
static int SHTTP
           
private  SocksClient Socks_client
          The socks server to use
protected static com.sun.net.ssl.SSLContext sslContext
           
private  int Timeout
          the timeout to use for reading responses
static java.lang.String version
          The current version of this package.
 
Fields inherited from interface HTTPClient.HTTPClientModuleConstants
REQ_CONTINUE, REQ_NEWCON_RST, REQ_NEWCON_SND, REQ_RESPONSE, REQ_RESTART, REQ_RETURN, REQ_SHORTCIRC, RSP_CONTINUE, RSP_NEWCON_REQ, RSP_NEWCON_SND, RSP_REQUEST, RSP_RESTART, RSP_SEND, RSP_SHORTCIRC
 
Constructor Summary
HTTPConnection(java.applet.Applet applet)
          Constructs a connection to the host from where the applet was loaded.
HTTPConnection(java.lang.String host)
          Constructs a connection to the specified host on port 80
HTTPConnection(java.lang.String host, int port)
          Constructs a connection to the specified host on the specified port
HTTPConnection(java.lang.String prot, java.lang.String host, int port)
          Constructs a connection to the specified host on the specified port, using the specified protocol (currently only "http" is supported).
HTTPConnection(java.net.URL url)
          Constructs a connection to the host (port) as given in the url.
 
Method Summary
 void addBasicAuthorization(java.lang.String realm, java.lang.String user, java.lang.String passwd)
          Adds an authorization entry for the "basic" authorization scheme to the list.
static void addCustomX509TrustManager()
          Method to add custom trust manager that mimics browser behavior to allow untrusted peers.
static boolean addDefaultModule(java.lang.Class module, int pos)
          Adds a module to the default list.
 void addDigestAuthorization(java.lang.String realm, java.lang.String user, java.lang.String passwd)
          Adds an authorization entry for the "digest" authorization scheme to the list.
 boolean addModule(java.lang.Class module, int pos)
          Adds a module to the current list.
private  java.lang.String[] assembleHeaders(Request req, java.io.ByteArrayOutputStream hdr_buf)
          This writes out the headers on the hdr_buf.
private static void checkCert(javax.security.cert.X509Certificate cert, java.lang.String host)
          Check whether the name in the certificate matches the host we're talking to.
(package private)  void closeDemux(java.io.IOException ioe, boolean was_reset)
           
 HTTPResponse Delete(java.lang.String file)
          Requests that file be DELETEd from the server.
 HTTPResponse Delete(java.lang.String file, NVPair[] headers)
          Requests that file be DELETEd from the server.
private  void determineKeepAlive(Response resp)
           
static void dontProxyFor(java.lang.String host)
          Add host to the list of hosts which should be accessed directly, not via any proxy set by setProxyServer().
static void dontProxyFor(java.lang.String[] hosts)
          Convenience method to add a number of hosts at once.
static boolean doProxyFor(java.lang.String host)
          Remove host from the list of hosts for which the proxy should not be used.
private  Response enableSSLTunneling(java.net.Socket[] sock, Request req, int timeout)
          Enable SSL Tunneling if we're talking to a proxy.
 HTTPResponse ExtensionMethod(java.lang.String method, java.lang.String file, byte[] data, NVPair[] headers)
          This is here to allow an arbitrary, non-standard request to be sent.
 HTTPResponse ExtensionMethod(java.lang.String method, java.lang.String file, HttpOutputStream os, NVPair[] headers)
          This is here to allow an arbitrary, non-standard request to be sent.
private  HTTPClientModule[] gen_mod_insts()
          Generate an array of instances of the current modules.
 HTTPResponse Get(java.lang.String file)
          GETs the file.
 HTTPResponse Get(java.lang.String file, NVPair[] form_data)
          GETs the file with a query consisting of the specified form-data.
 HTTPResponse Get(java.lang.String file, NVPair[] form_data, NVPair[] headers)
          GETs the file with a query consisting of the specified form-data.
 HTTPResponse Get(java.lang.String file, java.lang.String query)
          GETs the file using the specified query string.
 HTTPResponse Get(java.lang.String file, java.lang.String query, NVPair[] headers)
          GETs the file using the specified query string.
 boolean getAllowUserInteraction()
          returns whether modules are allowed to prompt or popup dialogs if neccessary.
 java.lang.Object getContext()
          Returns the current context.
static boolean getDefaultAllowUserInteraction()
          Gets the default allow-user-action.
(package private) static java.lang.Object getDefaultContext()
          Returns the default context.
 NVPair[] getDefaultHeaders()
          Gets the current list of default http headers.
static java.lang.Class[] getDefaultModules()
          Returns the default list of modules.
static int getDefaultTimeout()
          Gets the default timeout value to be used for each new HTTPConnection.
 java.lang.String getHost()
          Returns the host this connection is talking to.
 java.lang.Class[] getModules()
          Returns the list of modules used currently.
 int getPort()
          Returns the port this connection connects to.
 java.lang.String getProtocol()
          Returns the protocol this connection is talking.
 java.lang.String getProxyHost()
          Returns the host of the proxy this connection is using.
 int getProxyPort()
          Returns the port of the proxy this connection is using.
private  java.net.Socket getSocket(int con_timeout)
          Gets a socket.
 int getTimeout()
          Gets the timeout used for reading response data.
(package private)  boolean handleFirstRequest(Request req, Response resp)
          The very first request is special in that we use it to figure out the protocol version the server (or proxy) is compliant with.
(package private)  void handleRequest(Request req, HTTPResponse http_resp, Response resp, boolean usemodules)
          handles the Request.
 HTTPResponse Head(java.lang.String file)
          Sends the HEAD request.
 HTTPResponse Head(java.lang.String file, NVPair[] form_data)
          Sends the HEAD request.
 HTTPResponse Head(java.lang.String file, NVPair[] form_data, NVPair[] headers)
          Sends the HEAD request.
 HTTPResponse Head(java.lang.String file, java.lang.String query)
          Sends the HEAD request.
 HTTPResponse Head(java.lang.String file, java.lang.String query, NVPair[] headers)
          Sends the HEAD request.
 boolean isCompatibleWith(URI uri)
          See if the given uri is compatible with this connection.
private  boolean matchNonProxy(java.lang.String host)
          Determines if the given host matches any entry in the non-proxy list.
private  NVPair[] mergedHeaders(NVPair[] spec)
          This merges built-in default headers, user-specified default headers, and method-specified headers.
 HTTPResponse Options(java.lang.String file)
          Request OPTIONS from the server.
 HTTPResponse Options(java.lang.String file, NVPair[] headers)
          Request OPTIONS from the server.
 HTTPResponse Options(java.lang.String file, NVPair[] headers, byte[] data)
          Request OPTIONS from the server.
 HTTPResponse Options(java.lang.String file, NVPair[] headers, HttpOutputStream stream)
          Request OPTIONS from the server.
(package private)  void outputFinished()
           
 HTTPResponse Post(java.lang.String file)
          POSTs to the specified file.
 HTTPResponse Post(java.lang.String file, byte[] data)
          POSTs the raw data to the specified file.
 HTTPResponse Post(java.lang.String file, byte[] data, NVPair[] headers)
          POSTs the raw data to the specified file using the specified headers.
 HTTPResponse Post(java.lang.String file, HttpOutputStream stream)
          POSTs the data written to the output stream to the specified file.
 HTTPResponse Post(java.lang.String file, HttpOutputStream stream, NVPair[] headers)
          POSTs the data written to the output stream to the specified file using the specified headers.
 HTTPResponse Post(java.lang.String file, NVPair[] form_data)
          POSTs form-data to the specified file.
 HTTPResponse Post(java.lang.String file, NVPair[] form_data, NVPair[] headers)
          POST's form-data to the specified file using the specified headers.
 HTTPResponse Post(java.lang.String file, java.lang.String data)
          POSTs the data to the specified file.
 HTTPResponse Post(java.lang.String file, java.lang.String data, NVPair[] headers)
          POSTs the data to the specified file using the specified headers.
(package private) static java.lang.String ProtVers2String(int prot_vers)
           
 HTTPResponse Put(java.lang.String file, byte[] data)
          PUTs the raw data into the specified file.
 HTTPResponse Put(java.lang.String file, byte[] data, NVPair[] headers)
          PUTs the raw data into the specified file using the additional headers.
 HTTPResponse Put(java.lang.String file, HttpOutputStream stream)
          PUTs the data written to the output stream into the specified file.
 HTTPResponse Put(java.lang.String file, HttpOutputStream stream, NVPair[] headers)
          PUTs the data written to the output stream into the specified file using the additional headers.
 HTTPResponse Put(java.lang.String file, java.lang.String data)
          PUTs the data into the specified file.
 HTTPResponse Put(java.lang.String file, java.lang.String data, NVPair[] headers)
          PUTs the data into the specified file using the additional headers for the request.
static boolean removeDefaultModule(java.lang.Class module)
          Removes a module from the default list.
 boolean removeModule(java.lang.Class module)
          Removes a module from the current list.
(package private)  Response sendRequest(Request req, int con_timeout)
          sends the request over the line.
 void setAllowUserInteraction(boolean allow)
          Controls whether modules are allowed to prompt the user or pop up dialogs if neccessary.
 void setContext(java.lang.Object context)
          Sets the current context.
 void setCurrentProxy(java.lang.String host, int port)
          Sets the proxy used by this instance.
static void setDefaultAllowUserInteraction(boolean allow)
          Sets the default allow-user-action.
 void setDefaultHeaders(NVPair[] headers)
          Sets the default http headers to be sent with each request.
static void setDefaultTimeout(int time)
          Sets the default timeout value to be used for each new HTTPConnection.
static void setKeyStoreLocation(java.lang.String loc)
           
static void setKeyStorePassword(java.lang.String passwd)
           
static void setProxyServer(java.lang.String host, int port)
          Sets the default proxy server to use.
 void setRawMode(boolean raw)
          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.
static void setSocksServer(java.lang.String host)
          Sets the SOCKS server to use.
static void setSocksServer(java.lang.String host, int port)
          Sets the SOCKS server to use.
static void setSocksServer(java.lang.String host, int port, int version)
          Sets the SOCKS server to use.
 void setTimeout(int time)
          Sets the timeout to be used for creating connections and reading responses.
private  void Setup(int prot, java.lang.String host, int port)
          Sets the class variables.
private  HTTPResponse setupRequest(java.lang.String method, java.lang.String resource, NVPair[] headers, byte[] entity, HttpOutputStream stream)
          Sets up the request, creating the list of headers to send and creating instances of the modules.
 void stop()
          Aborts all the requests currently in progress on this connection and closes all associated sockets.
private static byte[] string2arr(java.lang.String ip)
          Turn an IP-address string into an array (e.g.
(package private) static int String2ProtVers(java.lang.String prot_vers)
           
private  java.lang.String stripRef(java.lang.String file)
          Removes the #...
 java.lang.String toString()
          Generates a string of the form protocol://host.domain:port .
 HTTPResponse Trace(java.lang.String file)
          Requests a TRACE.
 HTTPResponse Trace(java.lang.String file, NVPair[] headers)
          Requests a TRACE.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

keyStorePassword

protected static java.lang.String keyStorePassword
Variable that hold SSL information and their setter methods


keyStoreLocation

protected static java.lang.String keyStoreLocation

sslContext

protected static com.sun.net.ssl.SSLContext sslContext

version

public static final java.lang.String version
The current version of this package.

See Also:
Constant Field Values

dflt_context

private static final java.lang.Object dflt_context
The default context


Context

private java.lang.Object Context
The current context


Protocol

private int Protocol
The protocol used on this connection


ServerProtocolVersion

int ServerProtocolVersion
The server's protocol version; M.m stored as (M<<16 | m)


ServProtVersKnown

boolean ServProtVersKnown
Have we gotten the server's protocol version yet?


RequestProtocolVersion

private java.lang.String RequestProtocolVersion
The protocol version we send in a request; this is always HTTP/1.1 unless we're talking to a broken server in which case it's HTTP/1.0


no_chunked

private static boolean no_chunked
hack to force buffering of data instead of using chunked T-E


force_1_0

private static boolean force_1_0
hack to force HTTP/1.0 requests


Host

private java.lang.String Host
The remote host this connection is associated with


Port

private int Port
The remote port this connection is attached to


Proxy_Host

private java.lang.String Proxy_Host
The current proxy host to use (if any)


Proxy_Port

private int Proxy_Port
The current proxy port


Default_Proxy_Host

private static java.lang.String Default_Proxy_Host
The default proxy host to use (if any)


Default_Proxy_Port

private static int Default_Proxy_Port
The default proxy port


non_proxy_host_list

private static CIHashtable non_proxy_host_list
The list of hosts for which no proxy is to be used


non_proxy_dom_list

private static java.util.Vector non_proxy_dom_list

non_proxy_addr_list

private static java.util.Vector non_proxy_addr_list

non_proxy_mask_list

private static java.util.Vector non_proxy_mask_list

Socks_client

private SocksClient Socks_client
The socks server to use


Default_Socks_client

private static SocksClient Default_Socks_client
The default socks server to use


input_demux

private StreamDemultiplexor input_demux
the current stream demultiplexor


DemuxList

LinkedList DemuxList
a list of active stream demultiplexors


RequestList

private LinkedList RequestList
a list of active requests


DoesKeepAlive

private boolean DoesKeepAlive
does the server support keep-alive's?


KeepAliveUnknown

private boolean KeepAliveUnknown
have we been able to determine the above yet?


KeepAliveReqMax

private int KeepAliveReqMax
the maximum number of requests over a HTTP/1.0 keep-alive connection


KeepAliveReqLeft

private int KeepAliveReqLeft
the number of requests over a HTTP/1.0 keep-alive connection left


NeverPipeline

private static boolean NeverPipeline
hack to be able to disable pipelining


NoKeepAlives

private static boolean NoKeepAlives
hack to be able to disable keep-alives


haveMSLargeWritesBug

private static boolean haveMSLargeWritesBug
hack to work around M$ bug


DefaultTimeout

private static int DefaultTimeout
the default timeout to use for new connections


Timeout

private int Timeout
the timeout to use for reading responses


DefaultHeaders

private NVPair[] DefaultHeaders
The list of default http headers


DefaultModuleList

private static java.util.Vector DefaultModuleList
The default list of modules (as a Vector of Class objects)


ModuleList

private java.util.Vector ModuleList
The list of modules (as a Vector of Class objects)


DefaultAllowUI

private static boolean DefaultAllowUI
controls whether modules are allowed to interact with user


AllowUI

private boolean AllowUI
controls whether modules are allowed to interact with user


early_stall

private Response early_stall
These mark the response to stall the next request on, if any


late_stall

private Response late_stall

prev_resp

private Response prev_resp

output_finished

private boolean output_finished
This marks the socket output stream as still being used


DebugAll

public static final boolean DebugAll
Debug variables

See Also:
Constant Field Values

DebugConn

public static final boolean DebugConn
See Also:
Constant Field Values

DebugResp

public static final boolean DebugResp
See Also:
Constant Field Values

DebugDemux

public static final boolean DebugDemux
See Also:
Constant Field Values

DebugAuth

public static final boolean DebugAuth
See Also:
Constant Field Values

DebugSocks

public static final boolean DebugSocks
See Also:
Constant Field Values

DebugMods

public static final boolean DebugMods
See Also:
Constant Field Values

DebugURLC

public static final boolean DebugURLC
See Also:
Constant Field Values

HTTP

public static final int HTTP
possible http protocols we (might) handle

See Also:
Constant Field Values

HTTPS

public static final int HTTPS
See Also:
Constant Field Values

SHTTP

public static final int SHTTP
See Also:
Constant Field Values

HTTP_NG

public static final int HTTP_NG
See Also:
Constant Field Values

HTTP_1_0

public static final int HTTP_1_0
some known http versions

See Also:
Constant Field Values

HTTP_1_1

public static final int HTTP_1_1
See Also:
Constant Field Values

CD_NONE

public static final int CD_NONE
Content delimiters

See Also:
Constant Field Values

CD_HDRS

public static final int CD_HDRS
See Also:
Constant Field Values

CD_0

public static final int CD_0
See Also:
Constant Field Values

CD_CLOSE

public static final int CD_CLOSE
See Also:
Constant Field Values

CD_CONTLEN

public static final int CD_CONTLEN
See Also:
Constant Field Values

CD_CHUNKED

public static final int CD_CHUNKED
See Also:
Constant Field Values

CD_MP_BR

public static final int CD_MP_BR
See Also:
Constant Field Values
Constructor Detail

HTTPConnection

public HTTPConnection(java.applet.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.


HTTPConnection

public HTTPConnection(java.lang.String host)
Constructs a connection to the specified host on port 80


HTTPConnection

public HTTPConnection(java.lang.String host,
                      int port)
Constructs a connection to the specified host on the specified port


HTTPConnection

public HTTPConnection(java.lang.String prot,
                      java.lang.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).


HTTPConnection

public HTTPConnection(java.net.URL url)
               throws ProtocolNotSuppException
Constructs a connection to the host (port) as given in the url.

Method Detail

setKeyStorePassword

public static void setKeyStorePassword(java.lang.String passwd)

setKeyStoreLocation

public static void setKeyStoreLocation(java.lang.String loc)

addCustomX509TrustManager

public static void addCustomX509TrustManager()
Method to add custom trust manager that mimics browser behavior to allow untrusted peers. This method must be called after keystore password and keystore location is set.


Setup

private void Setup(int prot,
                   java.lang.String host,
                   int port)
Sets the class variables. Must not be public.


matchNonProxy

private boolean matchNonProxy(java.lang.String host)
Determines if the given host matches any entry in the non-proxy list.


Head

public HTTPResponse Head(java.lang.String file)
                  throws java.io.IOException,
                         ModuleException
Sends the HEAD request. This request is just like the corresponding GET except that it only returns the headers and no data.


Head

public HTTPResponse Head(java.lang.String file,
                         NVPair[] form_data)
                  throws java.io.IOException,
                         ModuleException
Sends the HEAD request. This request is just like the corresponding GET except that it only returns the headers and no data.


Head

public HTTPResponse Head(java.lang.String file,
                         NVPair[] form_data,
                         NVPair[] headers)
                  throws java.io.IOException,
                         ModuleException
Sends the HEAD request. This request is just like the corresponding GET except that it only returns the headers and no data.


Head

public HTTPResponse Head(java.lang.String file,
                         java.lang.String query)
                  throws java.io.IOException,
                         ModuleException
Sends the HEAD request. This request is just like the corresponding GET except that it only returns the headers and no data.


Head

public HTTPResponse Head(java.lang.String file,
                         java.lang.String query,
                         NVPair[] headers)
                  throws java.io.IOException,
                         ModuleException
Sends the HEAD request. This request is just like the corresponding GET except that it only returns the headers and no data.


Get

public HTTPResponse Get(java.lang.String file)
                 throws java.io.IOException,
                        ModuleException
GETs the file.


Get

public HTTPResponse Get(java.lang.String file,
                        NVPair[] form_data)
                 throws java.io.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.


Get

public HTTPResponse Get(java.lang.String file,
                        NVPair[] form_data,
                        NVPair[] headers)
                 throws java.io.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.


Get

public HTTPResponse Get(java.lang.String file,
                        java.lang.String query)
                 throws java.io.IOException,
                        ModuleException
GETs the file using the specified query string. The query string is first urlencoded.


Get

public HTTPResponse Get(java.lang.String file,
                        java.lang.String query,
                        NVPair[] headers)
                 throws java.io.IOException,
                        ModuleException
GETs the file using the specified query string. The query string is first urlencoded.


Post

public HTTPResponse Post(java.lang.String file)
                  throws java.io.IOException,
                         ModuleException
POSTs to the specified file. No data is sent.


Post

public HTTPResponse Post(java.lang.String file,
                         NVPair[] form_data)
                  throws java.io.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.


Post

public HTTPResponse Post(java.lang.String file,
                         NVPair[] form_data,
                         NVPair[] headers)
                  throws java.io.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.


Post

public HTTPResponse Post(java.lang.String file,
                         java.lang.String data)
                  throws java.io.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".


Post

public HTTPResponse Post(java.lang.String file,
                         java.lang.String data,
                         NVPair[] headers)
                  throws java.io.IOException,
                         ModuleException
POSTs the data to the specified file using the specified headers.


Post

public HTTPResponse Post(java.lang.String file,
                         byte[] data)
                  throws java.io.IOException,
                         ModuleException
POSTs the raw data to the specified file. The request is sent using the content-type "application/octet-stream"


Post

public HTTPResponse Post(java.lang.String file,
                         byte[] data,
                         NVPair[] headers)
                  throws java.io.IOException,
                         ModuleException
POSTs the raw data to the specified file using the specified headers.


Post

public HTTPResponse Post(java.lang.String file,
                         HttpOutputStream stream)
                  throws java.io.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"


Post

public HTTPResponse Post(java.lang.String file,
                         HttpOutputStream stream,
                         NVPair[] headers)
                  throws java.io.IOException,
                         ModuleException
POSTs the data written to the output stream to the specified file using the specified headers.


Put

public HTTPResponse Put(java.lang.String file,
                        java.lang.String data)
                 throws java.io.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".


Put

public HTTPResponse Put(java.lang.String file,
                        java.lang.String data,
                        NVPair[] headers)
                 throws java.io.IOException,
                        ModuleException
PUTs the data into the specified file using the additional headers for the request.


Put

public HTTPResponse Put(java.lang.String file,
                        byte[] data)
                 throws java.io.IOException,
                        ModuleException
PUTs the raw data into the specified file. The request is sent using the content-type "application/octet-stream".


Put

public HTTPResponse Put(java.lang.String file,
                        byte[] data,
                        NVPair[] headers)
                 throws java.io.IOException,
                        ModuleException
PUTs the raw data into the specified file using the additional headers.


Put

public HTTPResponse Put(java.lang.String file,
                        HttpOutputStream stream)
                 throws java.io.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".


Put

public HTTPResponse Put(java.lang.String file,
                        HttpOutputStream stream,
                        NVPair[] headers)
                 throws java.io.IOException,
                        ModuleException
PUTs the data written to the output stream into the specified file using the additional headers.


Options

public HTTPResponse Options(java.lang.String file)
                     throws java.io.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.


Options

public HTTPResponse Options(java.lang.String file,
                            NVPair[] headers)
                     throws java.io.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.


Options

public HTTPResponse Options(java.lang.String file,
                            NVPair[] headers,
                            byte[] data)
                     throws java.io.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.


Options

public HTTPResponse Options(java.lang.String file,
                            NVPair[] headers,
                            HttpOutputStream stream)
                     throws java.io.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.


Delete

public HTTPResponse Delete(java.lang.String file)
                    throws java.io.IOException,
                           ModuleException
Requests that file be DELETEd from the server.


Delete

public HTTPResponse Delete(java.lang.String file,
                           NVPair[] headers)
                    throws java.io.IOException,
                           ModuleException
Requests that file be DELETEd from the server.


Trace

public HTTPResponse Trace(java.lang.String file,
                          NVPair[] headers)
                   throws java.io.IOException,
                          ModuleException
Requests a TRACE. Headers of particular interest here are "Via" and "Max-Forwards".


Trace

public HTTPResponse Trace(java.lang.String file)
                   throws java.io.IOException,
                          ModuleException
Requests a TRACE.


ExtensionMethod

public HTTPResponse ExtensionMethod(java.lang.String method,
                                    java.lang.String file,
                                    byte[] data,
                                    NVPair[] headers)
                             throws java.io.IOException,
                                    ModuleException
This is here to allow an arbitrary, non-standard request to be sent. I'm assuming you know what you are doing...


ExtensionMethod

public HTTPResponse ExtensionMethod(java.lang.String method,
                                    java.lang.String file,
                                    HttpOutputStream os,
                                    NVPair[] headers)
                             throws java.io.IOException,
                                    ModuleException
This is here to allow an arbitrary, non-standard request to be sent. I'm assuming you know what you are doing...


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.

Since:
V0.2-3

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.


getDefaultHeaders

public NVPair[] getDefaultHeaders()
Gets the current list of default http headers.


getProtocol

public java.lang.String getProtocol()
Returns the protocol this connection is talking.


getHost

public java.lang.String getHost()
Returns the host this connection is talking to.


getPort

public int getPort()
Returns the port this connection connects to. This is always the actual port number, never -1.


getProxyHost

public java.lang.String getProxyHost()
Returns the host of the proxy this connection is using.


getProxyPort

public int getProxyPort()
Returns the port of the proxy this connection is using.


isCompatibleWith

public boolean isCompatibleWith(URI uri)
See if the given uri is compatible with this connection. Compatible means that the given uri can be retrieved using this connection object.

Since:
V0.3-2

setRawMode

public void setRawMode(boolean raw)
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.


setDefaultTimeout

public static void setDefaultTimeout(int time)
Sets the default timeout value to be used for each new HTTPConnection. The default is 0.


getDefaultTimeout

public static int getDefaultTimeout()
Gets the default timeout value to be used for each new HTTPConnection.


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. If the operation is not restarted and it is a read operation (i.e HTTPResponse.xxxx()) then stop() should be invoked.

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.


getTimeout

public int getTimeout()
Gets the timeout used for reading response data.


setAllowUserInteraction

public void setAllowUserInteraction(boolean allow)
Controls whether modules are allowed to prompt the user or pop up dialogs if neccessary.


getAllowUserInteraction

public boolean getAllowUserInteraction()
returns whether modules are allowed to prompt or popup dialogs if neccessary.


setDefaultAllowUserInteraction

public static void setDefaultAllowUserInteraction(boolean allow)
Sets the default allow-user-action.


getDefaultAllowUserInteraction

public static boolean getDefaultAllowUserInteraction()
Gets the default allow-user-action.


getDefaultModules

public static java.lang.Class[] getDefaultModules()
Returns the default list of modules.


addDefaultModule

public static boolean addDefaultModule(java.lang.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"


removeDefaultModule

public static boolean removeDefaultModule(java.lang.Class module)
Removes a module from the default list. If the module is not in the list it does nothing.


getModules

public java.lang.Class[] getModules()
Returns the list of modules used currently.


addModule

public boolean addModule(java.lang.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.


removeModule

public boolean removeModule(java.lang.Class module)
Removes a module from the current list. If the module is not in the list it does nothing.


setContext

public void setContext(java.lang.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. Contexts are considered equal if equals() returns true. Examples of useful context objects are threads (e.g. if you are running multiple clients, one per thread) and sockets (e.g. if you are implementing a gateway).

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").


getContext

public java.lang.Object getContext()
Returns the current context.


getDefaultContext

static java.lang.Object getDefaultContext()
Returns the default context.


addDigestAuthorization

public void addDigestAuthorization(java.lang.String realm,
                                   java.lang.String user,
                                   java.lang.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.


addBasicAuthorization

public void addBasicAuthorization(java.lang.String realm,
                                  java.lang.String user,
                                  java.lang.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.


setProxyServer

public static void setProxyServer(java.lang.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.


setCurrentProxy

public void setCurrentProxy(java.lang.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.

Note that if you set a proxy for the connection using this method, and a request made over this connection is redirected to a different server, then the connection used for new server will not pick this proxy setting, but instead will use the default proxy settings.


dontProxyFor

public static void dontProxyFor(java.lang.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").


dontProxyFor

public static void dontProxyFor(java.lang.String[] hosts)
Convenience method to add a number of hosts at once. If any one host is null or cannot be parsed it is ignored.

Since:
V0.3-2

doProxyFor

public static boolean doProxyFor(java.lang.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().


string2arr

private static byte[] string2arr(java.lang.String ip)
Turn an IP-address string into an array (e.g. "12.34.56.78" into { 12, 34, 56, 78 }).


setSocksServer

public static void setSocksServer(java.lang.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.


setSocksServer

public static void setSocksServer(java.lang.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.


setSocksServer

public static void setSocksServer(java.lang.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.


stripRef

private final java.lang.String stripRef(java.lang.String file)
Removes the #... part. Returns the stripped name, or "" if either the file is null or is the empty string (after stripping).


setupRequest

private HTTPResponse setupRequest(java.lang.String method,
                                  java.lang.String resource,
                                  NVPair[] headers,
                                  byte[] entity,
                                  HttpOutputStream stream)
                           throws java.io.IOException,
                                  ModuleException
Sets up the request, creating the list of headers to send and creating instances of the modules.


mergedHeaders

private NVPair[] mergedHeaders(NVPair[] spec)
This merges built-in default headers, user-specified default headers, and method-specified headers. Method-specified take precedence over user defaults, which take precedence over built-in defaults. The following headers are removed if found: "Host" and "Content-length".


gen_mod_insts

private HTTPClientModule[] gen_mod_insts()
Generate an array of instances of the current modules.


handleRequest

void handleRequest(Request req,
                   HTTPResponse http_resp,
                   Response resp,
                   boolean usemodules)
             throws java.io.IOException,
                    ModuleException
handles the Request. First the request handler for each module is is invoked, and then if no response was generated the request is sent.


sendRequest

Response sendRequest(Request req,
                     int con_timeout)
               throws java.io.IOException,
                      ModuleException
sends the request over the line.


getSocket

private java.net.Socket getSocket(int con_timeout)
                           throws java.io.IOException
Gets a socket. Creates a socket to the proxy if set, or else to the actual destination.


enableSSLTunneling

private Response enableSSLTunneling(java.net.Socket[] sock,
                                    Request req,
                                    int timeout)
                             throws java.io.IOException,
                                    ModuleException
Enable SSL Tunneling if we're talking to a proxy. See ietf draft draft-luotonen-ssl-tunneling-03 for more info.


checkCert

private static void checkCert(javax.security.cert.X509Certificate cert,
                              java.lang.String host)
                       throws java.io.IOException
Check whether the name in the certificate matches the host we're talking to.


assembleHeaders

private java.lang.String[] assembleHeaders(Request req,
                                           java.io.ByteArrayOutputStream hdr_buf)
                                    throws java.io.IOException
This writes out the headers on the hdr_buf. It takes special precautions for the following headers:
Content-typeThis is only written if the request has an entity. If the request has an entity and no content-type header was given for the request it defaults to "application/octet-stream"
Content-lengthThis header is generated if the request has an entity and the entity isn't being sent with the Transfer-Encoding "chunked".
User-Agent If not present it will be generated with the current HTTPClient version strings. Otherwise the version string is appended to the given User-Agent string.
Connection This header is only written if no proxy is used. If no connection header is specified and the server is not known to understand HTTP/1.1 or later then a "Connection: keep-alive" header is generated.
Proxy-ConnectionThis header is only written if a proxy is used. If no connection header is specified and the proxy is not known to understand HTTP/1.1 or later then a "Proxy-Connection: keep-alive" header is generated.
Keep-Alive This header is only written if the Connection or Proxy-Connection header contains the Keep-Alive token.
Expect If there is no entity and this header contains the "100-continue" token then this token is removed. before writing the header.
TE If this header does not exist, it is created; else if the "trailers" token is not specified this token is added; else the header is not touched.
Furthermore, it escapes various characters in request-URI.


handleFirstRequest

boolean handleFirstRequest(Request req,
                           Response resp)
                     throws java.io.IOException
The very first request is special in that we use it to figure out the protocol version the server (or proxy) is compliant with.


determineKeepAlive

private void determineKeepAlive(Response resp)
                         throws java.io.IOException

outputFinished

void outputFinished()

closeDemux

void closeDemux(java.io.IOException ioe,
                boolean was_reset)

ProtVers2String

static final java.lang.String ProtVers2String(int prot_vers)

String2ProtVers

static final int String2ProtVers(java.lang.String prot_vers)

toString

public java.lang.String toString()
Generates a string of the form protocol://host.domain:port .