Contents

• Changes
• Upgrading

Changes from Version 0.2-3

Here is a (not necessarily complete) list of changes and new features since Version 0.2-3. For more information see the rest of the documentation.

• Two classes have been renamed:
  • AuthTypeNotImplementedException -> AuthSchemeNotImplException
  • ProtocolNotSupportedException -> ProtocolNotSuppException
  This is because of MacOS which is limited to 32 character filenames.

• The properties socksHost, socksPort, and socksVersion have been renamed to HTTPClient.socksHost, HTTPClient.socksPort, and HTTPClient.socksVersion, respectively.

• The properties http.proxyHost and http.proxyPort are recognized (these are new in JDK 1.1).

• The concept of modules has been introduced. Processing, such redirection handling, authorization handling, cookies, etc. is now done in the appropriate module. Modules can be added and removed dynamically to tailor the amount of processing desired. Modules also provide for an easy way to extend the functionality of the client and a way to customize it for special needs, without needing to change the core code. See the Advanced Info for more info.

• The functionality has been greatly enhanced with various modules: In addition to authorization and redirection modules, there is a cookie module, a content encoding module (to allow for and handle compressed data in responses), a transfer encoding module (similar to the content encoding module), and a content-md5 module (verifies the optional MD5 hash of the body).

• All request methods (such a Get(), Post(), etc.) and all methods in HTTPResponse can now throw both an IOException and a (new) ModuleException.

• AuthSchemeNotImplException is now a subclass of ModuleException.

• The whole internal processing has been redesigned so that processing of responses is delayed until necessary. In particular, the response has not been processed when the request method (Get(), Post(), etc) returns. This allows for the pipelining of requests within a single thread. Response processing is triggered with the first call to any method in the HTTPResponse.

• An HttpOutputStream class has been added, together with the corresponding new request methods in HTTPConnection. See the api docs for restrictions and caveats associated with its usage.

• Two new methods dontProxyFor() and doProxyFor() for handling a list of hosts, for which no proxy is to be used, have been added to HTTPConnection. Two properties for initializing this list are now also understood: HTTPClient.nonProxyHosts and http.nonProxyHosts

• The Options() request method has been further overloaded to allow for a body to be included with request.

• A Context concept has been introduced to allow the simulation of multiple independent clients within one application. See the Advanced Info for more info.

• setRawMode() is deprecated. Because response processing is now deferred, this method is not needed anymore. Also, the amount of processing can be controlled through the adding and removing of modules.

• A stop() method has been added to HTTPConnection. This will abort all request currently in progress and close the socket.

• A timeout has been added to HTTPConnection. This will cause socket creating and the reading of response headers to time out if they take too long. See the Advanced Info for more info.

• The class Util is now public and contains a number of (hopefully) useful methods for creating and parsing http headers. Note especially httpDate() which should be used when sending any headers containing dates.

• The method getParameter() has been moved from the Codecs class to the Util class.

• New methods in HTTPConnection for querying the state: getProtocol(), getHost(), getPort(), getProxyHost() and getProxyPort().

• When attempting to create a socket, if the host has multiple IP addresses (i.e. the dns lookup returns multiple A records) then all addresses are tried until one succeeds. Previously only the first address was tried.

• When talking to HTTP/1.0 proxies, the Proxy-Connection is used to attempt persistent connections with the proxy.

• A new method setAllowUserInteraction() has been added to HTTPConnection. Note: setAuthHandler(null) should not be used anymore to disable the authorization popup, as this also disables the handling of the Digest authorization scheme.

• Socket connections are now closed a little more aggresively. The exact conditions under which they are closed is now documented (see the Advanced Info).

• Redirection handling modified: 302 is now handled just like 303 (i.e. the new request is always done using the GET request method), and the new 307 response code is recognized.

• The 305 response code is now only honored a proxy is not already being used.

• The redirection module now reuses the current HTTPConnection instance if the new location refers to the same server (it previously always created a new HTTPConnection instance).

• Permanent redirections (301) are cached; when a request for a permanently redirected url is made then the request is automatically redirected to the new url before being sent.

• The URL returned by getEffectiveURL() now contains the query string sent, if any (previously the query string in this URL was always empty).

• The Digest authentication scheme is now handled by the default authorization handler. Two new convenience methods have been added for this: HTTPConnection.addDigestAuthorization() and AuthorizationInfo.addDigestAuthorization()

• HTTPConnection.addAuthorization() has been removed.

• Authorization info is preemptively sent when reasonable. Proxy authorization info is also automatically sent with every request when using a proxy that requires authentication (previously the info was only sent in response to the corresponding status code).

• The AuthorizationHandler interface has been almost completely changed. This was necessary, because the original interface was only capable of handling the most simple of authorization schemes. The new interface ought to be handle any scheme that follows the basic structure of http authentication. In particular, it is now possible to handle the Digest authentication scheme with this interface.

• HTTPResponse has new methods for accessing trailers (the chunked encoding allows for "headers" to be sent at the end of the body): getTrailer(), getTrailerAsInt(), and getTrailerAsDate().

• Requests are automatically retried if an IOException occurs on the socket. This is subject to certain restrictions though, because of the problem that the sequence of unanswered requests may not be idempotent.

• A new HttpURLConnection class has been added (and the associated URLStreamHandler's). By setting the property java.protocol.handler.pkgs=HTTPClient you can use the HTTPClient as a replacement for the JDK's HttpClient, i.e. URL.openConnection() will return an instance of HTTPClient.HttpURLConnection.

• Debugging for the various parts of the client can be enabled and disabled in the new GlobalConstants class.

• Various bug fixes ...

Upgrading from Version 0.2-3

There have been some changes which prevent V0.3 from being plug-in compatible with V0.2-X. However, these changes are mostly syntactical, and upgrading to V0.3 should be fairly straightforward and easy.

• Two classes have been renamed:
  • AuthTypeNotImplementedException -> AuthSchemeNotImplException
  • ProtocolNotSupportedException -> ProtocolNotSuppException

• The properties socksHost, socksPort, and socksVersion have been renamed to HTTPClient.socksHost, HTTPClient.socksPort, and HTTPClient.socksVersion, respectively.

• All request methods in HTTPConnection (i.e Get(), Head(), Post(), etc) now throw IOException and ModuleException. If you were previously catching the IOException and the AuthTypeNotImplementedException separately, then just replace AuthTypeNotImplementedException by ModuleException. Example:

      catch (AuthTypeNotImplementedException atnie)
      {
  	System.err.println("Can't handle the authorization scheme " +
  			   atnie.getMessage());
      } 

  becomes

      catch (ModuleException me)
      {
  	System.err.println("Error handling request: " + me.getMessage());
      } 

  If you were catching Exception then no changes are required.

• All methods in HTTPResponse now also throw ModuleException (in addition to IOException). Depending on how your code is written you'll need to added extra catch()'s for the ModuleException.

• If you've written your own AuthorizationHandler, then this handler will need to be updated. This involves adding stubs for the new methods fixupAuthInfo, handleAuthHeaders, and handleAuthTrailers and adjusting the signature of getAuthorization(). The stubs are as follows:

      public AuthorizationInfo fixupAuthInfo(AuthorizationInfo info,
  					   RoRequest req,
  					   AuthorizationInfo challenge,
  					   RoResponse resp)
      {
  	return info;
      }
  
      public void handleAuthHeaders(Response resp, RoRequest req,
  				  AuthorizationInfo prev,
  				  AuthorizationInfo prxy)
      {
      }
  
      public void handleAuthTrailers(Response resp, RoRequest req,
  				   AuthorizationInfo prev,
  				   AuthorizationInfo prxy)
      {
      } 

• If you used AuthorizationInfo.setAuthHandler(null) to prevent the auth popup from appearing, then use HTTPConnection.setDefaultAllowUserInteraction(false) instead.

• Change any Codecs.getParameter(...) to Util.getParameter(...).

To ease the transition from Version 0.2-3 you can run the following sed script over your files. It won't do all the work, but it might help. If anybody wants to write a Windoze equivalent I'll put it up here. You can also download it directly.

#!/bin/sh
#
# Tries to upgrade methods from V0.2-3 to V0.3
#
# Those methods that have changed their signature are marked with the
# comment /* NEEDS WORK */
#
# Usage: upgrade < OldCode.java > NewCode.java
#

sed -e '
    s/\<AuthTypeNotImplementedException\>/AuthSchemeNotImplException/g
    s/\<ProtocolNotSupportedException\>/ProtocolNotSuppException/g
    s/\<Codecs.getParameter\>/Util.getParameter/g
    s/\<socksHost\>/HTTPClient.&/g
    s/\<socksPort\>/HTTPClient.&/g
    s/\<socksVersion\>/HTTPClient.&/g
    s/\<HTTPConnection\.addAuthorizationInfo\>/AuthorizationInfo\.addAuthorizationInfo \/* NEEDS WORK *\/ /g
    s/\<AuthorizationInfo\.setAuthHandler(null)/HTTPConnection\.setDefaultAllowUserInteraction(false)/g
'

# the end