Copyright 2002-2008 oakland software incorporated, all rights reserved. Readme file for oakland software HTTP client support. See http://www.oaklandsoftware.com/support.html for current known problems. Release Notes ------------------------------------------------ Incompatible Changes since release 2.6.0 ------------------------------------------------ The default value for HttpURLConnection.setMultiCredentialsPerAddress() has been changed to true, so the behavior (by default) is as it was in releases prior to 2.5.0. This effectively reverses the API incompatible change introduced in release 2.5.0. Incompatible Changes since release 2.5.0 ------------------------------------------------ As of release 2.5.0 the default behavior for managing authentication credentials associated with both proxied and normal connections has changed. Previously the credentials were associated with a connection by default and you could have multiple connections to the same host/port with different credentials. Now, with 2.5.0 by default all connections going to the same host/port (or proxied through the same host/port) share the same authentication credentials. This is the typical scenario for most users and the advantage of this is that the HttpUserAgent.get[Proxy]Credential() is only invoked when needed such that hooking this to some user interface is appropriate. If you wish to have different sets of credentials to the same host/port, this is possible by calling HttpURLConnection.setMultiCredentialsPerAddress(true). Incompatible Changes since release 1.x ------------------------------------------------ 1) The HttpURLConnection.setExplicitClose() and HttpURLConnection.isExplicitClose() are now deprecated and don't do anything. The default behavior for the 2.x implementation is the same as using the ExplicitClose option. Configuration Instructions ------------------------------------------------ If you are using this with Apache Axis, you must change the Axis configuration to point to the Oakland Software HTTP Transport. The configuration page linked to below has the details for how to do this. See http://www.oaklandsoftware.com/product_http/config.html Installation Instructions ------------------------------------------------ - Requires JRE 1.4.2 or higher. - Include the file http.jar in the CLASSPATH for your application. It does not depend on anything. - There are various sample programs in the examples directory of this kit. How to Hook Your Code to the HTTP client ------------------------------------------------ 1) If you require complete plug-compatibility with the JRE (no code changes), then set this property before the first HTTP URL connection is opened: System.setProperty("java.protocol.handler.pkgs", "com.oaklandsw"); 2) Alternatively, you can use these other methods to explicitly specify the use of this HTTP client: a) Explicitly open the connection like this: HttpURLConnection urlCon = com.oaklandsw.http.HttpURLConnection .openConnection(url); b) Explicitly specify the Handler objects: // HTTP URL url = new URL("http", "host", 9999, "file", new com.oaklandsw.http.Handler()); // HTTPS URL url = new URL("https", "host", 9999, "file", new com.oaklandsw.https.Handler()); c) Use a URLStreamHandlerFactory: URL.setURLStreamHandlerFactory(new URLStreamHandlerFactory() { public URLStreamHandler createURLStreamHandler(String protocol) { if (protocol.equalsIgnoreCase("http")) return new com.oaklandsw.http.Handler(); else if (protocol.equalsIgnoreCase("https")) return new com.oaklandsw.https.Handler(); return null; } }); However, if the URLStreamHandlerFactory was previously set (by something else), it will give you an error. In that case, you must use method a (explicitly specifying the handlers). 3) For authentication support, you will need to make a class implement the HttpUserAgent interface (see the javadoc for details, and sample below). This class is called when necessary to get the NTLM or basic credentials. Set the object using this code: // Before creating the first connection com.oaklandsw.http.HttpURLConnection. setDefaultUserAgent(new YourHttpUserAgent()); -- or -- // If you set the user agent for a specific connection HttpURLConnection urlCon = (HttpURLConnection)url.openConnection(); ((com.oaklandsw.http.HttpUrlConnection)urlCon). setUserAgent(new YourHttpUserAgent()); 4) Logging is supported using only Apache Log4J version 1.2.x or higher. You must provide the log4j jar file in the classpath. This will automatically be detected if present. If this jar file is not present, no logging will occur. log4j logging (see log4j.properties.sample) ----------------------------------------------------------- . Use all of these statements in the log4j.properties file (which can be found in the current directory, or in the CLASSPATH). To trace the events on the wire do this: log4j.logger.com.oaklandsw.http.wireLog=DEBUG If you don't want to see any messages at all: log4j.logger.com.oaklandsw=OFF If you want to see everything: log4j.logger.com.oaklandsw=DEBUG In general, you can turn logging on for any class in the HTTP client. log4j.logger.com.oaklandsw.http.HttpConnectionManager=DEBUG To programatically set Log4j logging: Properties logProps = new Properties(); logProps.setProperty("log4j.logger.com.oaklandsw", "DEBUG"); PropertyConfigurator.configure(logProps); ---------------------------------------------------- Below is a sample implementation of the HttpUserAgent interface package com.oaklandsw.http.webapp; import java.util.*; import com.oaklandsw.http.*; public class TestUserAgent implements HttpUserAgent { public Credential getCredential(String realm, String url, int scheme) { Credential cred = null; switch (scheme) { case Credential.AUTH_NTLM: NtlmCredential ntlmCred = new NtlmCredential(); ntlmCred.setUser("testuser"); ntlmCred.setPassword("testpass"); ntlmCred.setDomain("testdomain"); ntlmCred.setHost("testhost"); cred = ntlmCred; break; case Credential.AUTH_BASIC: UserCredential basicCred = new UserCredential(); basicCred.setUser("testuser"); basicCred.setPassword("testpass"); cred = basicCred; break; case Credential.AUTH_DIGEST: break; } return cred; } public Credential getProxyCredential(String realm, String url, int scheme) { // As above } }