home *** CD-ROM | disk | FTP | other *** search
/ Chip 2005 June / ccd0605.iso / Software / Shareware / Programare / httpcurrent / README < prev    next >
Text File  |  2005-04-29  |  7KB  |  250 lines
  1. Copyright 2002-2005 oakland software incorporated, all rights reserved.
  2.  
  3. Readme file for oakland software HTTP client support.
  4.  
  5. HTTP client version 1.4.0
  6.  
  7. See http://www.oaklandsoftware.com/support.html for current known problems.
  8.  
  9.  
  10.  
  11. Fixed in this version
  12. -----------------------------------------------
  13. 983 https does not work with squid proxy
  14.  
  15.  
  16. Installation Instructions
  17. ------------------------------------------------
  18.  
  19.  
  20. The distribution has the following jar files you will need to include in your
  21. CLASSPATH:
  22.  
  23. http.jar - The HTTP Client protocol support.
  24.  
  25. This software has no dependencies on other software, except if you are
  26. using NTLM support, see step 1 and 2 below.  
  27.  
  28.  
  29.  
  30. This requires JRE 1.2.2 (or higher)
  31.  
  32.  
  33. There is a sample program at:
  34.  
  35.    http://www.oaklandsoftware.com/HttpGetSample.java        
  36.  
  37.  
  38. To use the HTTP client support:
  39.  
  40. *** NOTE - if you are using https (SSL) connections and you are
  41.     getting exceptions when trying to connect, this may be caused by
  42.     an expired root CA associated with your JRE.  Please see:
  43.  
  44.     http://sunsolve.sun.com/search/document.do?assetkey=1-26-57436-1
  45.  
  46.     For how to correct the problem.
  47.  
  48.  
  49. 1) If you are using NTLM support, make sure you have a DES cipher
  50.    and MD4 digest algorithms available.  You can get the DES/MD4
  51.    from www.bouncycastle.org.
  52.  
  53.    The recommended Bouncy Castle JAR files are:
  54.  
  55.       JRE 1.4 - bcprov-jdk14-120
  56.       JRE 1.3 - jce-jdk13-120
  57.       JRE 1.2 - jce-jdk12-120
  58.  
  59.    You may use higher versions of the Bouncy Castle libraries if
  60.    they are available.
  61.  
  62.         // DES/MD4 Crypto algorithms - needed for NTLM
  63.         // This line shows how to hook up the Bouncy Castle Providers
  64.         // If you prefer another provider for your crypto algorithms,
  65.         // then replace this with adding your preferred provider.
  66.         Security.addProvider
  67.             (new org.bouncycastle.jce.provider.BouncyCastleProvider());
  68.  
  69.  
  70. 2) Make sure you have the JSSE jar files if you are not using JDK 1.4
  71.    or higher.  Here is the code you must include if you are JDK 1.2 or
  72.    1.3:
  73.  
  74.         // SSL - Uncomment this if you are < JDK 1.4
  75.         Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());
  76.  
  77.  
  78. 3) To enable the HTTP support (you must do this before you open
  79.    the first URL connection):
  80.  
  81.         System.setProperty("java.protocol.handler.pkgs", "com.nogoop");
  82.  
  83.    Alternatively, you can use these other methods to explicitly specify
  84.    the use of this HTTP client:
  85.    
  86.    a) Explicitly specify the Handler objects:
  87.  
  88.       // HTTP
  89.       URL url = new URL("http", "host", 9999, "file", new com.nogoop.http.Handler());
  90.       // HTTPS
  91.       URL url = new URL("https", "host", 9999, "file", new com.nogoop.https.Handler());
  92.  
  93.    b) Use a URLStreamHandlerFactory:
  94.  
  95.             URL.setURLStreamHandlerFactory(new URLStreamHandlerFactory()
  96.             {
  97.                 public URLStreamHandler createURLStreamHandler(String protocol)
  98.                 {
  99.                     if (protocol.equalsIgnoreCase("http"))
  100.                         return new com.nogoop.http.Handler();
  101.                     else if (protocol.equalsIgnoreCase("https"))
  102.                         return new com.nogoop.https.Handler();
  103.                     return null;
  104.                 }
  105.  
  106.             });
  107.  
  108.        However, if the URLStreamHandlerFactory was previously set (by 
  109.        something else), it will give you an error.  In that case, you must
  110.        use method a (explicitly specifying the handlers).
  111.  
  112.  
  113. 4) You will need to make a class implement the HttpUserAgent
  114.    interface (see the javadoc for details, and sample below).  This
  115.    class is called when necessary to get the NTLM or basic
  116.    credentials.
  117.  
  118.    Set the object using this code:
  119.  
  120.         // Before creating the first connection
  121.         com.nogoop.http.HttpURLConnection.
  122.            setDefaultUserAgent(new YourHttpUserAgent());
  123.  
  124.         -- or --   
  125.  
  126.         // If you set the user agent for a specific connection 
  127.         HttpURLConnection urlCon = 
  128.            (HttpURLConnection)url.openConnection();
  129.         ((com.nogoop.http.HttpUrlConnection)urlCon).
  130.            setUserAgent(new YourHttpUserAgent());
  131.  
  132.  
  133.  
  134. 5) The tracing is using either log4j or JDK 1.4 logging.
  135.    If log4j is not present, the JDK1.4 tracing will be used.  If
  136.    that's not present, no tracing will occur.
  137.  
  138.    log4j tracing  (see log4j.properties.sample)
  139.    -----------------------------------------------------------
  140.  
  141. .  Use all of these statements in the log4j.properties file 
  142.    (which can be found in the current directory, or in the CLASSPATH).
  143.  
  144.    To trace the events on the wire do this:
  145.  
  146.       log4j.logger.com.nogoop.http.wireLog=DEBUG
  147.  
  148.    If you don't want to see any messages at all:
  149.  
  150.       log4j.logger.com.nogoop=OFF
  151.  
  152.    If you want to see everything:
  153.  
  154.       log4j.logger.com.nogoop=DEBUG
  155.  
  156.    In general, you can turn tracing on for any class in the HTTP
  157.    client.
  158.  
  159.       log4j.logger.com.nogoop.http.HttpConnectionManager=DEBUG
  160.  
  161.  
  162.  
  163.    JDK 1.4 tracing  (see jdk14.logging.sample)
  164.    -----------------------------------------------------------
  165.  
  166.    Set the logging configuration file as follows:
  167.  
  168.       java -Djava.util.logging.config.file=mylogging.properties 
  169.  
  170.    If you don't set the configuration file, the default file is
  171.    located at your JRE/lib directory and is called
  172.    logging.properties. 
  173.  
  174.    To trace the events on the wire do this:
  175.  
  176.       com.nogoop.http.wireLog.level = ALL
  177.  
  178.    If you don't want to see any messages at all:
  179.  
  180.       com.nogoop.level = OFF
  181.  
  182.    If you want to see everything:
  183.  
  184.       com.nogoop.level = ALL
  185.  
  186.    In general, you can turn tracing on for any class in the HTTP
  187.    client.
  188.  
  189.       com.nogoop.http.HttpConnectionManager.level = ALL
  190.  
  191.  
  192.  
  193.  
  194.  
  195. ----------------------------------------------------
  196. Below is a sample implementation of the HttpUserAgent interface
  197.  
  198.  
  199. package com.nogoop.http.webapp;
  200.  
  201. import java.util.*;
  202.  
  203. import com.nogoop.http.*;
  204.  
  205.  
  206. public class TestUserAgent implements HttpUserAgent
  207. {
  208.  
  209.     public Credential getCredential(String realm,
  210.                                     String url,
  211.                                     int scheme)
  212.     {
  213.  
  214.         Credential cred = null;
  215.  
  216.         switch (scheme)
  217.         {
  218.         case Credential.AUTH_NTLM:
  219.             NtlmCredential ntlmCred = new NtlmCredential();
  220.             ntlmCred.setUser("testuser");
  221.             ntlmCred.setPassword("testpass");
  222.             ntlmCred.setDomain("testdomain");
  223.             ntlmCred.setHost("testhost");
  224.             cred = ntlmCred;
  225.             break;
  226.  
  227.         case Credential.AUTH_BASIC:
  228.             UserCredential basicCred = new UserCredential();
  229.             basicCred.setUser("testuser");
  230.             basicCred.setPassword("testpass");
  231.             cred = basicCred;
  232.             break;
  233.         case Credential.AUTH_DIGEST:
  234.             break;
  235.         }
  236.  
  237.         return cred;
  238.     }
  239.  
  240.  
  241.     public Credential getProxyCredential(String realm,
  242.                                     String url,
  243.                                     int scheme)
  244.     {
  245.         // As above
  246.     }
  247. }
  248.  
  249.  
  250.