HTTPClient API: Class HTTPConnection

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

HTTPClient
Class HTTPConnection

java.lang.Object
  |
  +--HTTPClient.HTTPConnection

public class HTTPConnection
extends Object
implements HTTPClient.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(), getText(), 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(rsp.getText());
         }
         else
             data = rsp.getData();

         rsp = con.Get("/another_file");
         if (rsp.getStatusCode() >= 300)
         {
             System.err.println("Received Error: "+rsp.getReasonLine());
             System.err.println(rsp.getText());
         }
         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(rsp.getText());
         }
         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(rsp.getText());
         }
         else
             text = rsp.getText();
     }
     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-3 06/05/2001
Author:: Ronald Tschalär

Field Summary

static String version
          The current version of this package.

Fields inherited from interface HTTPClient.GlobalConstants

CD_0, CD_CHUNKED, CD_CLOSE, CD_CONTLEN, CD_HDRS, CD_MP_BR, CD_NONE, HTTP, HTTP_1_0, HTTP_1_1, HTTP_NG, HTTPS, SHTTP

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(Applet applet)
          Constructs a connection to the host from where the applet was loaded.

HTTPConnection(String host)
          Constructs a connection to the specified host on port 80

HTTPConnection(String host, int port)
          Constructs a connection to the specified host on the specified port

HTTPConnection(String prot, 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(String prot, String host, int port, InetAddress localAddr, int localPort)
          Constructs a connection to the specified host on the specified port, using the specified protocol (currently only "http" is supported), local address, and local port.

HTTPConnection(URI uri)
          Constructs a connection to the host (port) as given in the uri.

HTTPConnection(URL url)
          Constructs a connection to the host (port) as given in the url.

Method Summary

void addBasicAuthorization(String realm, String user, String passwd)
          Adds an authorization entry for the "basic" authorization scheme to the list.

static boolean addDefaultModule(Class module, int pos)
          Adds a module to the default list.

void addDigestAuthorization(String realm, String user, String passwd)
          Adds an authorization entry for the "digest" authorization scheme to the list.

boolean addModule(Class module, int pos)
          Adds a module to the current list.

HTTPResponse Delete(String file)
          Requests that file be DELETEd from the server.

HTTPResponse Delete(String file, NVPair[] headers)
          Requests that file be DELETEd from the server.

static void dontProxyFor(String host)
          Add host to the list of hosts which should be accessed directly, not via any proxy set by setProxyServer().

static void dontProxyFor(String[] hosts)
          Convenience method to add a number of hosts at once.

static boolean doProxyFor(String host)
          Remove host from the list of hosts for which the proxy should not be used.

HTTPResponse ExtensionMethod(String method, String file, byte[] data, NVPair[] headers)
          This is here to allow an arbitrary, non-standard request to be sent.

HTTPResponse ExtensionMethod(String method, String file, HttpOutputStream os, NVPair[] headers)
          This is here to allow an arbitrary, non-standard request to be sent.

HTTPResponse Get(String file)
          GETs the file.

HTTPResponse Get(String file, NVPair[] form_data)
          GETs the file with a query consisting of the specified form-data.

HTTPResponse Get(String file, NVPair[] form_data, NVPair[] headers)
          GETs the file with a query consisting of the specified form-data.

HTTPResponse Get(String file, String query)
          GETs the file using the specified query string.

HTTPResponse Get(String file, 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.

Object getContext()
          Returns the current context.

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

static Object getDefaultContext()
          Returns the default context.

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

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

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

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

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

int getPort()
          Returns the port this connection connects to.

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

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

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

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

HTTPResponse Head(String file)
          Sends the HEAD request.

HTTPResponse Head(String file, NVPair[] form_data)
          Sends the HEAD request.

HTTPResponse Head(String file, NVPair[] form_data, NVPair[] headers)
          Sends the HEAD request.

HTTPResponse Head(String file, String query)
          Sends the HEAD request.

HTTPResponse Head(String file, String query, NVPair[] headers)
          Sends the HEAD request.

boolean isCompatibleWith(URI uri)
          See if the given uri is compatible with this connection.

HTTPResponse Options(String file)
          Request OPTIONS from the server.

HTTPResponse Options(String file, NVPair[] headers)
          Request OPTIONS from the server.

HTTPResponse Options(String file, NVPair[] headers, byte[] data)
          Request OPTIONS from the server.

HTTPResponse Options(String file, NVPair[] headers, HttpOutputStream stream)
          Request OPTIONS from the server.

HTTPResponse Post(String file)
          POSTs to the specified file.

HTTPResponse Post(String file, byte[] data)
          POSTs the raw data to the specified file.

HTTPResponse Post(String file, byte[] data, NVPair[] headers)
          POSTs the raw data to the specified file using the specified headers.

HTTPResponse Post(String file, HttpOutputStream stream)
          POSTs the data written to the output stream to the specified file.

HTTPResponse Post(String file, HttpOutputStream stream, NVPair[] headers)
          POSTs the data written to the output stream to the specified file using the specified headers.

HTTPResponse Post(String file, NVPair[] form_data)
          POSTs form-data to the specified file.

HTTPResponse Post(String file, NVPair[] form_data, NVPair[] headers)
          POST's form-data to the specified file using the specified headers.

HTTPResponse Post(String file, String data)
          POSTs the data to the specified file.

HTTPResponse Post(String file, String data, NVPair[] headers)
          POSTs the data to the specified file using the specified headers.

HTTPResponse Put(String file, byte[] data)
          PUTs the raw data into the specified file.

HTTPResponse Put(String file, byte[] data, NVPair[] headers)
          PUTs the raw data into the specified file using the additional headers.

HTTPResponse Put(String file, HttpOutputStream stream)
          PUTs the data written to the output stream into the specified file.

HTTPResponse Put(String file, HttpOutputStream stream, NVPair[] headers)
          PUTs the data written to the output stream into the specified file using the additional headers.

HTTPResponse Put(String file, String data)
          PUTs the data into the specified file.

HTTPResponse Put(String file, String data, NVPair[] headers)
          PUTs the data into the specified file using the additional headers for the request.

static boolean removeDefaultModule(Class module)
          Removes a module from the default list.

boolean removeModule(Class module)
          Removes a module from the current list.

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

void setContext(Object context)
          Sets the current context.

void setCurrentProxy(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 setProxyServer(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(String host)
          Sets the SOCKS server to use.

static void setSocksServer(String host, int port)
          Sets the SOCKS server to use.

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

protected HTTPResponse setupRequest(String method, 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.

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

HTTPResponse Trace(String file)
          Requests a TRACE.

HTTPResponse Trace(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

version

public static final String version

The current version of this package.

Constructor Detail

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(String prot,
                      String host,
                      int port,
                      InetAddress localAddr,
                      int localPort)
               throws ProtocolNotSuppException

Constructs a connection to the specified host on the specified port, using the specified protocol (currently only "http" is supported), local address, and local port.

Parameters:: prot - the protocol; host - the host; port - the port, or -1 for the default port; localAddr - the local address to bind to; lcoalPort - the local port to bind to
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

HTTPConnection

public HTTPConnection(URI uri)
               throws ProtocolNotSuppException

Constructs a connection to the host (port) as given in the uri.

Parameters:: uri - the uri
Throws:: ProtocolNotSuppException - if the protocol is not HTTP

Method Detail