package.html
1 <!-- $Id: package.html 155418 2005-02-26 13:01:52Z dirkv $ --> 2 <html> 3 <head> 4 <title>Package Documentation for org.apache.commons.httpclient</title> 5 <meta name="author" content="Jeff Dever"> 6 </head> 7 <body> 8 <h3>Classes and interfaces supporting the client side of the HTTP protocol.</h3> 9 <p> 10 The <em>HttpClient</em> component supports the client-side of 11 <a href="http://www.w3.org/Protocols/rfc1945/rfc1945.txt">RFC 1945 (HTTP/1.0)</a> and 12 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">RFC 2616 (HTTP/1.1)</a>, 13 several related specifications 14 (<a href="http://www.w3.org/Protocols/rfc2109/rfc2109.txt">RFC 2109 (Cookies)</a>, 15 <a href="http://www.ietf.org/rfc/rfc2617.txt">RFC 2617 (HTTP Authentication)</a>, 16 etc.), and provides a framework by which new request types (methods) or HTTP 17 extensions can can be easily created or supported. 18 </p> 19 <p> 20 The basis for the abstraction is provided by three types: 21 </p> 22 <ul><dl> 23 <dt>{@link org.apache.commons.httpclient.HttpConnection}</dt> 24 <dd> 25 represents a network connection to some HTTP host. 26 </dd> 27 <dt>{@link org.apache.commons.httpclient.HttpMethod}</dt> 28 <dd> 29 represents a request to be made over some 30 {@link org.apache.commons.httpclient.HttpConnection} 31 and contains the server's response. 32 </dd> 33 <dt>{@link org.apache.commons.httpclient.HttpState}</dt> 34 <dd> 35 contains the HTTP attributes that may persist from 36 request to request, such as cookies and authentication 37 credentials. 38 </dd> 39 </dl></ul> 40 <p> 41 and several simple bean-style classes: 42 </p> 43 <ul><dl> 44 <dt>{@link org.apache.commons.httpclient.Cookie}</dt> 45 <dd> 46 represents HTTP cookie. 47 </dd> 48 <dt>{@link org.apache.commons.httpclient.Credentials}</dt> 49 <dd> 50 an interface representing a set of authentication credentials. 51 </dd> 52 <dt>{@link org.apache.commons.httpclient.Header}</dt> 53 <dd> 54 represents an HTTP request or response header. 55 </dd> 56 <dt>{@link org.apache.commons.httpclient.HeaderElement}</dt> 57 <dd> 58 represents a single element of a multi-part header. 59 </dd> 60 <dt>{@link org.apache.commons.httpclient.UsernamePasswordCredentials}</dt> 61 <dd> 62 a username and password pair. 63 </dd> 64 </dl></ul> 65 <p> 66 {@link org.apache.commons.httpclient.HttpClient} provides a 67 simple "user-agent" implementation that will suffice for many 68 applications, but whose use is not required. 69 </p> 70 <p> 71 <em>HttpClient</em> also provides several utilities that may be 72 useful when extending the framework: 73 </p> 74 <ul><dl> 75 <dt>{@link org.apache.commons.httpclient.HttpMethodBase}</dt> 76 <dd> 77 an abstract base implementation of <tt>HttpMethod</tt>, 78 which may be extended to create new method types or 79 to support additional protocol HTTP features. 80 </dd> 81 <dt>{@link org.apache.commons.httpclient.HttpStatus}</dt> 82 <dd> 83 an enumeration of HttpStatus codes. 84 </dd> 85 <dt>{@link org.apache.commons.httpclient.ChunkedOutputStream}</dt> 86 <dd> 87 an {@link java.io.OutputStream} wrapper supporting the "chunked" 88 transfer encoding. 89 </dd> 90 <dt>{@link org.apache.commons.httpclient.ChunkedInputStream}</dt> 91 <dd> 92 an {@link java.io.InputStream} wrapper supporting the "chunked" 93 transfer encoding. 94 </dd> 95 <dt>{@link org.apache.commons.httpclient.util.URIUtil}</dt> 96 <dd> 97 provides utilities for encoding and decoding URI's in the 98 <tt>%HH</tt> format. 99 </dd> 100 </dl></ul> 101 102 <h4>HttpClient Configuration with Java Properties</h4> 103 Java properties can be set at run time with the <code>-Dname=value<code> 104 command line arguments to the application that uses <i>HttpClient</i>. 105 These properties can also be set programaticly by calling 106 <code>System.getProperties().setProperty(name, value)</code>. 107 This is the list of properties that <i>HttpClient</i> recognizes: 108 <table border=1> 109 <tr><th>Name</th> 110 <th>Type</th> 111 <th>Effect</th> 112 </tr> 113 <tr><th>httpclient.useragent</th> 114 <td>String</td> 115 <td>Sets the User-Agent string to be sent on every HTTP request.</td> 116 </tr> 117 <tr><th>httpclient.authentication.preemptive</th> 118 <td>boolean</td> 119 <td>Sends authorization credentials without requiring explicit requests 120 from the web server</td> 121 </tr> 122 </table> 123 </body> 124 </html>