Java Doc for HTTPConnection.java in  » Net » SkunkDAV » HTTPClient » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

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

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

• 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 ] )

The host may be any of:

• a complete host name (e.g.

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.

This is a convenience method and just invokes the corresponding method in AuthorizationInfo.
Parameters:
  realm - the realm
Parameters:
  user - the username
Parameters:
  passw - the password
See Also:   AuthorizationInfo.addBasicAuthorization(java.lang.Stringintjava.lang.Stringjava.lang.Stringjava.lang.String)

Example:

 HTTPConnection.addDefaultModule(Class.forName("HTTPClient.CookieModule"), 1);
 

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"
See Also:   HTTPClientModule
Parameters:
  module - the module's Class object
Parameters:
  pos - the position of this module in the list; if pos>= 0 then this is the absolute position in the list (0 isthe first position); if pos < 0 then this isthe position relative to the end of the list (-1 meansthe last element, -2 the second to last element, etc). true if module was successfully added; false if themodule is already in the list.
exception:
  ArrayIndexOutOfBoundsException - if pos >list-size or if pos < -(list-size).
exception:
  ClassCastException - if module does notimplement the HTTPClientModule interface.
exception:
  RuntimeException - if module cannot beinstantiated.

This is a convenience method and just invokes the corresponding method in AuthorizationInfo.
Parameters:
  realm - the realm
Parameters:
  user - the username
Parameters:
  passw - the password
See Also:   AuthorizationInfo.addDigestAuthorization(java.lang.Stringintjava.lang.Stringjava.lang.Stringjava.lang.String)

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.
exception:
  ParseException - if the length of the netmask does not matchthe length of the IP-address

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").
Parameters:
  context - the new context; must be non-null
exception:
  IllegalArgumentException - if context is null
exception:
  RuntimeException - if the context has already been set

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.
See Also:   HTTPConnection.setProxyServer(java.lang.String,int)
Parameters:
  host - the host the proxy runs on
Parameters:
  port - the port the proxy is listening on

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 theseparating ':').

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.
See Also:   HTTPConnection.setCurrentProxy(java.lang.String,int)
Parameters:
  host - the host on which the proxy server resides.
Parameters:
  port - the port the proxy server is listening on.

The default is false.
See Also:   HTTPConnection.removeModule(java.lang.Class)
Parameters:
  raw - if true removes all modules (except for the retry module)

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.
See Also:   HTTPConnection.setSocksServer(java.lang.String,int,int)
Parameters:
  host - the host on which the proxy server resides. The portused is the default port 1080.

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.
See Also:   HTTPConnection.setSocksServer(java.lang.String,int,int)
Parameters:
  host - the host on which the proxy server resides.
Parameters:
  port - the port the proxy server is listening on.

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

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 waitindefinitely.
See Also:   HTTPConnection.stop()

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