mbecke 2003/03/09 20:08:06
Modified: httpclient/xdocs authentication.xml navigation.xml
Added: httpclient/xdocs charencodings.xml tutorial.xml
troubleshooting.xml userguide.xml redirects.xml
developerguide.xml methods.xml
Log:
New developer documentation.
PR: 10809
Submitted by: Adrian Sutton
Revision Changes Path
1.2 +109 -101 jakarta-commons/httpclient/xdocs/authentication.xml
Index: authentication.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/authentication.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- authentication.xml 20 Feb 2003 00:43:52 -0000 1.1
+++ authentication.xml 10 Mar 2003 04:08:06 -0000 1.2
@@ -12,101 +12,102 @@
<body>
<section name="Introduction">
- HttpClient supports three different types of http authentication schemes:
+ <p>HttpClient supports three different types of http authentication schemes:
Basic, Digest and NTLM. These can be used to authenticate with http servers
- or proxies.
+ or proxies.</p>
</section>
- <section name="Server Authentication">
- <p>HttpClient handles authenticating with servers almost transparently,
- the only thing a developer must do is actually provide the login
- credentials. These credentials are stored in the HttpState instance
- and can be set or retrieved using the <code>setCredentials(String realm,
- Credentials cred)</code> and <code>getCredentials(String realm)</code>
- methods.</p>
-
- <p>Note: To set default Credentials for any realm that has not been
- explicitly specified, pass in <code>null</code> as the value of
- <code>realm</code>.</p>
-
- <p>The automatic authorization built in to HttpClient can be disabled
- with the method <code>setDoAuthentication(boolean doAuthentication)</code>
- in the HttpMethod class. The change only affects that method instance.</p>
-
- <p>Preemptive authentication can be enabled within HttpClient. In this
- mode HttpClient will send the basic authentication response even before
- the server gives an unauthorized response in certain situations, thus
- reducing the overhead of making the connection. To enable this use the
- following:</p>
-
- <p><code>setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY, "true");
- </code></p>
-
- <p>The preemptive authentication conforms to rfc2617:
-
- <blockquote>A client SHOULD assume that all paths at or deeper than the
depth
- of the last symbolic element in the path field of the Request-URI also
- are within the protection space specified by the Basic realm value
- of the current challenge. A client MAY preemptively send the
- corresponding Authorization header with requests for resources in
- that space without receipt of another challenge from the server.
- Similarly, when a client sends a request to a proxy, it may reuse
- a userid and password in the Proxy-Authorization header field without
- receiving another challenge from the proxy server.</blockquote>
- </p>
- </section>
-
- <section name="Proxy Authentication">
- <p>Proxy authentication in HttpClient is almost identical to server
- authentication with the exception that the credentials for each are
- stored independantly. So for proxy authentication you must use
- <code>setProxyCredentials(String realm, Credentials cred)</code> and
- <code>getProxyCredentials(String realm)</code>. As with server
- authentication, passing <code>null</code> as the realm sets or returns
- the default credentials.</p>
- </section>
-
- <section name="Basic">
- <p>Basic authentication is the original and most compatible authentication
- scheme for HTTP. Unfortunately, it is also the least secure as it sends
- the username and password unencrypted to the server. Basic authentication
- requires an instance of UsernamePasswordCredentials (which NTCredentials
- extends) to be available, either for the specific realm specified by the
- server or as the default credentials.</p>
- </section>
-
- <section name="Digest">
- <p>Digest authentication was added in the HTTP 1.1 protocol and while
- not being as widely supported as Basic authentication there is a great
- deal of support for it. Digest authentication is significantly more
- secure than basic authentication as it never transfers the actual
- password across the network, but instead uses it to encrypt a "nonce"
- value sent from the server.</p>
-
- <p>Digest authentication requires an instance of
- UsernamePasswordCredentials (which NTCredentials extends) to be
- available either for the specific realm specified by the server or as
- the default credentials.</p>
- </section>
-
- <section name="NTLM">
- <p>NTLM is the most complex of the authentication protocols supported
- by HttpClient. It is a proprietary protocol designed by Microsoft
- with no publicly available specification. Early version of NTLM were
- less secure than Digest authentication due to faults in the design,
- however these were fixed in a service pack for Window NT 4 and the
- protocol is now considered more secure than Digest authentication.</p>
-
- <p>NTLM authentication requires an instance of NTCredentials be
- available for the <i>domain name</i> of the server or the default
- credentials. Note that since NTLM does not use the notion of realms
- HttpClient uses the domain name of the server as the name of the realm.</p>
-
- <p>There are some significant differences in the way that NTLM works
- compared with basic and digest authentication. These differences
- are generally handled by HttpClient, however having an
- understanding of these differences can help avoid problems when using
- NTLM authentication.</p>
+ <section name="Server Authentication">
+ <p>HttpClient handles authenticating with servers almost transparently,
+ the only thing a developer must do is actually provide the login
+ credentials. These credentials are stored in the HttpState instance
+ and can be set or retrieved using the <code>setCredentials(String
realm,
+ Credentials cred)</code> and <code>getCredentials(String realm)</code>
+ methods.</p>
+
+ <p><i>Note:</i> To set default Credentials for any realm that has not
been
+ explicitly specified, pass in <code>null</code> as the value of
+ <code>realm</code>.</p>
+
+ <p>The automatic authorization built in to HttpClient can be disabled
+ with the method <code>setDoAuthentication(boolean
doAuthentication)</code>
+ in the HttpMethod class. The change only affects that method
instance.</p>
+
+ <subsection name="Preemptive Authentication">
+ <p>Preemptive authentication can be enabled within HttpClient. In this
+ mode HttpClient will send the basic authentication response even before
+ the server gives an unauthorized response in certain situations, thus
reducing the overhead
+ of making the connection. To enable this use the following:</p>
+
+ <source>setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY,
"true");</source>
+
+ <p>The preemptive authentication conforms to rfc2617:</p>
+
+ <blockquote>A client SHOULD assume that all paths at or deeper than
the depth
+ of the last symbolic element in the path field of the Request-URI also
+ are within the protection space specified by the Basic realm value
+ of the current challenge. A client MAY preemptively send the
+ corresponding Authorization header with requests for resources in
+ that space without receipt of another challenge from the server.
+ Similarly, when a client sends a request to a proxy, it may reuse
+ a userid and password in the Proxy-Authorization header field without
+ receiving another challenge from the proxy server.</blockquote>
+ </subsection>
+ </section>
+
+ <section name="Proxy Authentication">
+ <p>Proxy authentication in HttpClient is almost identical to server
+ authentication with the exception that the credentials for each are
+ stored independantly. So for proxy authentication you must use
+ <code>setProxyCredentials(String realm, Credentials cred)</code> and
+ <code>getProxyCredentials(String realm)</code>. As with server
+ authentication, passing <code>null</code> as the realm sets or returns
+ the default credentials.</p>
+ </section>
+
+ <section name="Authentication Schemes">
+ <p>The following authentication schemes are supported by HttpClient.</p>
+ <subsection name="Basic">
+ <p>Basic authentication is the original and most compatible authentication
+ scheme for HTTP. Unfortunately, it is also the least secure as it sends
+ the username and password unencrypted to the server. Basic authentication
+ requires an instance of UsernamePasswordCredentials (which NTCredentials
+ extends) to be available, either for the specific realm specified by the
+ server or as the default credentials.</p>
+ </subsection>
+
+ <subsection name="Digest">
+ <p>Digest authentication was added in the HTTP 1.1 protocol and while
+ not being as widely supported as Basic authentication there is a great
+ deal of support for it. Digest authentication is significantly more
+ secure than basic authentication as it never transfers the actual
+ password across the network, but instead uses it to encrypt a "nonce"
+ value sent from the server.</p>
+
+ <p>Digest authentication requires an instance of
+ UsernamePasswordCredentials (which NTCredentials extends) to be
+ available either for the specific realm specified by the server or as
+ the default credentials.</p>
+ </subsection>
+
+ <subsection name="NTLM">
+ <p>NTLM is the most complex of the authentication protocols supported
+ by HttpClient. It is a proprietary protocol designed by Microsoft
+ with no publicly available specification. Early version of NTLM were
+ less secure than Digest authentication due to faults in the design,
+ however these were fixed in a service pack for Windows NT 4 and the
+ protocol is now considered more secure than Digest authentication.</p>
+
+ <p>NTLM authentication requires an instance of NTCredentials be
+ available for the <i>domain name</i> of the server or the default
+ credentials. Note that since NTLM does not use the notion of realms
+ HttpClient uses the domain name of the server as the name of the
realm.</p>
+
+ <p>There are some significant differences in the way that NTLM works
+ compared with basic and digest authentication. These differences
+ are generally handled by HttpClient, however having an
+ understanding of these differences can help avoid problems when using
+ NTLM authentication.</p>
<p>
<ol>
@@ -118,22 +119,29 @@
<li>The realm for NTLM authentication is the domain name of the computer
being connected to, this can be troublesome as servers often have
- multiple domain names that refer to them. Only the domain name
- that HttpClient connects to (as specified by the HostConfiguration)
- is used to look up the credentials.
+ multiple domain names that refer to them. Only the domain name
+ that HttpClient connects to (as specified by the
HostConfiguration)
+ is used to look up the credentials.
It is generally advised that while initially testing NTLM
- authentication, you pass the realm in as null which is used as
- the default.</li>
+ authentication, you pass the realm in as null which is used as
+ the default.</li>
<li>NTLM authenticates a connection and not a request, so you need to
authenticate every time a new connection is made and keeping the
connection
open during authentication is vital. Due to this, NTLM cannot
- be used to authenticate with both a proxy and the server, nor can
- NTLM be used with HTTP 1.0 connections or servers that do not
- support HTTP keep-alives.</li>
+ be used to authenticate with both a proxy and the server, nor
can
+ NTLM be used with HTTP 1.0 connections or servers that do not
+ support HTTP keep-alives.</li>
</ol>
</p>
- </section>
+ </subsection>
+ </section>
+
+ <section name="Examples">
+ <p>There is an example of using authentication available in the
+ <a
href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/";>example
directory</a> in CVS. The particulary example is the
+ <a
href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/BasicAuthenticationExample.java";>BasicAuthenticationExample</a>.</p>
+ </section>
</body>
1.5 +16 -7 jakarta-commons/httpclient/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/navigation.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- navigation.xml 20 Feb 2003 00:43:52 -0000 1.4
+++ navigation.xml 10 Mar 2003 04:08:06 -0000 1.5
@@ -5,6 +5,7 @@
<properties>
<title>HttpClient</title>
<author email="[EMAIL PROTECTED]">Jeff Dever</author>
+ <author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id$</revision>
</properties>
@@ -15,12 +16,20 @@
<item name="Status" href="/status.html"/>
<item name="Download" href="/downloads.html"/>
<item name="Applications" href="/applications.html"/>
- <item name="Logging Guide" href="/logging.html"/>
- <item name="Webapp Test Guide" href="/testwebapp.html"/>
- <item name="Authentication Guide" href="/authentication.html"/>
- <item name="Sample Code"
href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/"/>
- <item name="Release Process" href="/releases.html"/>
+ <item name="User Guide" href="/userguide.html">
+ <item name="Authentication Guide" href="/authentication.html"/>
+ <item name="Character Encodings" href="/charencodings.html"/>
+ <item name="Cross Host Redirects" href="/redirects.html"/>
+ <item name="Logging Guide" href="/logging.html"/>
+ <item name="Methods" href="/methods.html"/>
+ <item name="Sample Code"
href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/"/>
+ <item name="Trouble Shooting" href="/troubleshooting.html"/>
+ <item name="Tutorial" href="/tutorial.html"/>
+ </item>
+ <item name="Developer Guide" href="/developerguide.html">
+ <item name="Release Process" href="/releases.html"/>
+ <item name="Webapp Test Guide" href="/testwebapp.html"/>
+ </item>
</menu>
</body>
-
</project>
1.1 jakarta-commons/httpclient/xdocs/charencodings.xml
Index: charencodings.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Character Encodings</title>
<author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id: charencodings.xml,v 1.1 2003/03/10 04:08:06 mbecke Exp
$</revision>
</properties>
<body>
<section name="Introduction">
<p>This document provides an overview of how HttpClient handles character
encodings and how to use HttpClient in an encoding safe way. There are
three main sections, HTTP headers, request/response body and URLs.</p>
</section>
<section name="HTTP Headers">
<p>The headers of a HTTP request or response must be in US-ASCII format.
It is not possible to use non US-ASCII characters in the header of a
request or response. Generally this is not an issue however, because the
HTTP headers are designed to facilite the transfer of data rather than to
actually transfer the data itself.</p>
</section>
<section name="Request/Response Body">
<p>The request or response body can be any encoding, but by default is
ISO-8859-1. The encoding may be specified in the Content-Type header,
for example:</p>
<blockquote>Content-Type: text/html; charset=UTF-8</blockquote>
<p>In this case the application should be careful to use UTF-8 encoding
when converting the body to a String or some characters may be corrupt.
You can set the content type header for a request with the
<code>addRequestHeader</code> method in each method and retrieve the
encoding for the response body with the <code>getResponseCharSet</code>
method.</p>
<p>If the response is known to be a String, you can use the
<code>getResponseBodyAsString</code> method which will automatically use
the encoding specified in the Content-Type header or ISO-8859-1 if no
charset is specified.</p>
<p>Note that some document types, such as HTML and XML allow the author
to specify the content type of the file. In this case, you should
consult the appropriate standards regarding how to resovle any conflicts
in the reported charsets.</p>
</section>
<section name="URLs">
<p>The standard for URLs (<a
href="http://www.w3c.org/Addressing/rfc1738.txt";>RFC1738</a>) explictly
states that URLs may only contain graphic printable characters of the
US-ASCII coded character set and is defined in terms of octets.
The octets 80-FF hexadecimal are not used in US-ASCII and the octets
OO-1F hexadecimal represent control characters; characters in these
ranges must be encoded.</p>
<p>Characters which cannot be represented by an 8-bit ASCII code, can not
be used in an URL as there is no way to reliably encode them (the
encoding scheme for URLs is based off of octets). Despite this, some
servers do support varying means of encoding double byte characters in
URLs, the most common technique seems to be to use UTF-8 encoding and
encode each octet separately even if a pair of octets represents one
character. This however, is not specified by the standard and is highly
prone to error, so it is recommended that URLs be restricted to the 8-bit
ASCII range.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/tutorial.xml
Index: tutorial.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>HttpClient Tutorial</title>
<author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id: tutorial.xml,v 1.1 2003/03/10 04:08:06 mbecke Exp $</revision>
</properties>
<body>
<section name="Overview">
<p>This tutorial is designed to provide a basic overview of how to use
HttpClient. When you have completed the tutorial you will have written
a simple application that downloads a page using HttpClient.</p>
<p>It is assumed that you have an understanding of how to program in
Java and are familiar with the development environment you are using.</p>
</section>
<section name="Getting Ready">
<p>The first thing you need to do is get a copy of HttpClient and it's
dependencies. Currently the only required dependency is
<a href="/commons/logging/">commons-logging</a>. This tutorial was
written for HttpClient 2.0 and at a minimum requires HttpClient 2.0 Alpha
2. You will also need JDK 1.2.2 or above.</p>
<p>Once you've downloaded HttpClient and commons-logging you'll need to
put them on your classpath. There is also an optional dependency on JSSE
which is required for HTTPS connections; this is not required for this
tutorial.</p>
</section>
<section name="Concepts">
<p>The general process for using HttpClient consists of a number of
steps:</p>
<ol>
<li>Create an instance of HttpClient.</li>
<li>Create an instance of one of the methods (GetMethod in this
case). The URL to connect to is passed in to the the method
constructor.</li>
<li>Tell HttpClient to execute the message.</li>
<li>Read the response.</li>
<li>Release the connection.</li>
<li>Deal with the response.</li>
</ol>
<p>We'll cover how to perform each of these steps below. Notice that we
go through the entire process regardless of whether the server returned
an error or not. This is important because HTTP 1.1 allows multiple
requests to use the same connection by simply sending the requests one
after the other. Obviously, if we don't read the entire response to
the first request, the left over data will get in the way of the second
response. HttpClient tries to handle this but to avoid problems it is
important to always read the entire response and release the connection.</p>
<div style="font-style: italic; border: 1px solid #888; margin-left: 7px;
margin-right: 7px; margin-top: 1em; margin-bottom: 1px;">
<p>
It is important to always read the entire
response and release the connection regardless of whether the server
returned an error or not.
</p>
</div>
</section>
<section name="Instantiating HttpClient">
<p>The no argument constructor for HttpClient provides a good set of
defaults for most situations so that is what we'll use.</p>
<source>HttpClient client = new HttpClient();</source>
</section>
<section name="Creating a Method">
<p>The various methods defined by the HTTP specification correspond to
the various classes in HttpClient which implement the HttpMethod
interface. These classes are all found in the package
<code>org.apache.commons.httpclient.methods</code>.</p>
<p>We will be using the Get method which is a simple method that simply
takes a URL and gets the document the URL points to.</p>
<source>HttpMethod method = new GetMethod(url);</source>
</section>
<section name="Execute the Method">
<p>The actual execution of the method is performed by calling
<code>executeMethod</code> on the client and passing in the method to
execute. Since networks connections are unreliable, we also need to deal
with any errors that occur.</p>
<p>There are two kinds of exceptions that could be thrown by
executeMethod, <code>HttpRecoverableException</code> and
<code>IOException</code>.</p>
<subsection name="HttpRecoverableException">
<p>A HttpRecoverableException is thrown when an error occurs that is
likely to be a once-off problem. Usually the request will succeed on
a second attempt, so retrying the connection is generally
recommended. Note that HttpRecoverableException actually extends
IOException so you can just ignore it and catch the IOException if
your application does not retry the request.</p>
</subsection>
<subsection name="IOException">
<p>An IOException is thrown when the request cannot be sent at all
and retrying the connection is also likely to fail. This may be
caused by a number of situations including the server being down,
inability to resolve the domain name or the server refusing the
connection.</p>
</subsection>
<p>The other useful piece of information is the status code that is
returned by the server. This code is returned by executeMethod as an
int and can be used to determine if the request was successful or not
and can sometimes indicate that further action is required by the
client such as providing authentication credentials.</p>
<source><![CDATA[
int statusCode = -1;
int attempt = 0;
// We will retry up to 3 times.
while (statusCode == -1 && attempt < 3) {
try {
// execute the method.
statusCode = client.executeMethod(method);
} catch (HttpRecoverableException e) {
System.err.println("A recoverable exception occurred,
retrying. " + e.getMessage());
} catch (IOException e) {
System.err.println("Failed to download file.");
e.printStackTrace();
System.exit(-1);
}
}
// Check that we didn't run out of retries.
if (statusCode == -1) {
System.err.println("Failed to recover from exception.");
System.exit(-2);
}]]>
</source>
</section>
<section name="Read the Response">
<p>It is vital that the response body is always read regardless of the
status returned by the server. There are three ways to do this:</p>
<ul>
<li>Call <code>method.getResponseBody()</code>. This will return a
byte array containing the data in the response body.</li>
<li>Call <code>method.getResponseBodyAsString()</code>. This will
return a String containing the response body. Be warned though that
the conversion from bytes to a String is done using the default
encoding so this method may not be portable across all platforms.</li>
<li>Call <code>method.getResponseBodyAsStream()</code> and read the
entire contents of the stream then call <code>stream.close()</code>.
This method is best if it is possible for a lot of data to be received
as it can be buffered to a file or processed as it is read. Be sure to
always read the entirety of the data and call close on the stream.</li>
</ul>
<p>For this tutorial we will use getResponseBody() for simplicity.</p>
<source>byte[] responseBody = method.getResponseBody();</source>
</section>
<section name="Release the Connection">
<p>This is a crucial step to keep things flowing. We must tell
HttpClient that we are done with the connection and that it can now be
reused. Without doing this HttpClient will wait indefinitely for a
connection to free up so that it can be reused.</p>
<source>method.releaseConnection();</source>
</section>
<section name="Deal with the Repsonse">
<p>We've now completed our interaction with HttpClient and can just
concentrate on doing what we need to do with the data. In our case,
we'll just print it out to the console.</p>
<p>It's worth noting that if you were retrieving the response as a stream
and processing it as it is read, this step would actually be combined
with reading the connection, and when you'd finished processing all the
data, you'd then close the input stream and release the connection.</p>
<p>Note: We should pay attention to character encodings here instead of
just using the system default.</p>
<source>System.err.println(new String(responseBody));</source>
</section>
<section name="Final Source Code">
<p>When we put all of that together plus a little bit of glue code we get
the program below.</p>
<source><![CDATA[
import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.methods.*;
import java.io.*;
public class HttpClientTutorial {
private static String url = "http://www.apache.org/";;
public static void main(String[] args) {
// Create an instance of HttpClient.
HttpClient client = new HttpClient();
// Create a method instance.
HttpMethod method = new GetMethod(url);
// Execute the method.
int statusCode = -1;
int attempt = 0;
// We will retry up to 3 times.
while (statusCode == -1 && attempt < 3) {
try {
// execute the method.
statusCode = client.executeMethod(method);
} catch (HttpRecoverableException e) {
System.err.println(
"A recoverable exception occurred, retrying." +
e.getMessage());
} catch (IOException e) {
System.err.println("Failed to download file.");
e.printStackTrace();
System.exit(-1);
}
}
// Check that we didn't run out of retries.
if (statusCode == -1) {
System.err.println("Failed to recover from exception.");
System.exit(-2);
}
// Read the response body.
byte[] responseBody = method.getResponseBody();
// Release the connection.
method.releaseConnection();
// Deal with the response.
System.err.println(new String(responseBody));
}
}
]]></source>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/troubleshooting.xml
Index: troubleshooting.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Trouble Shooting HttpClient</title>
<author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id: troubleshooting.xml,v 1.1 2003/03/10 04:08:06 mbecke Exp
$</revision>
</properties>
<body>
<section name="Introduction">
<p>This document outlines some of the techniques that often help when
trying to track down a problem in HttpClient. Please try the suggestions
on this page before emailing the user or dev lists with questions. If
none of these things help, please provide the information they provide to
help the developers track down the problem.</p>
</section>
<section name="Things To Try">
<ol>
<li>Try connecting with a normal browser and make sure the server gives
the right response.</li>
<li>If you're using a proxy server try without it if possible.</li>
<li>Try the same code on a different server (preferably running
different server software).</li>
<li>Check that your code matches the general pattern for using
HttpClient as described in the <a
href="tutorial.html">tutorial</a>.</li>
<li>Set the <a href="logging.html">logging level</a> to debug and check
the output for the cause of the problem.</li>
<li>Enable the <a href="logging.html">wire trace</a> and follow the
communication between the client and server to determine where the
problem is occurring.</li>
<li>Use telnet or netcat to manually send the request to the server.
This is particularly useful once you think you know what the problem is
and you want to easily test that changing what HttpClient sends will
fix it.</li>
<li>Use netcat in listen mode to act as the server and check how
HttpClient handles various responses.</li>
<li>Try updating to the latest nightly build of HttpClient. Bugs
happen and they are generally fixed pretty quickly so testing against
the latest build is often worthwhile.</li>
</ol>
</section>
<section name="Asking For Help">
<p>If you've tried the things above and still can't work out how to fix
the problem, it might be time to contact the <a
href="mail-lists.html">mailing lists</a> for support. Which list to
contact depends on exactly where you think the problem lies. If you
think you've just got an error in your code somewhere, probably the
commons-user list is the best place, but if you think that HttpClient is
at fault, the commons-httpclient-dev list is probably a better choice.</p>
<p style="color: red">Please do not cross-post to both lists.</p>
<p>When you do send off the email, please include as much detail as you
can, including attaching wire trace logs if you think they'll help (they
often do). If you are seeing exceptions being thrown the full stack
trace is essential to tracking down the problem. Any of the information
you gained from the "things to try" section above are probably worth
mentioning.</p>
</section>
<section name="Reporting Bugs">
<p>If you're fairly certain that the problem is a bug in HttpClient or
something that HttpClient doesn't currently support but probably should,
log it in <a href="http://nagoya.apache.org/bugzilla/";>Bugzilla</a>.
Make sure you spend some time searching the existing bugs to make sure it
hasn't already been logged. If you're unsure about whether or not to log
something in Bugzilla, it's probably worth bringing it up on the
developer mailing list to clarify the situation.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/userguide.xml
Index: userguide.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>HttpClient User Guide</title>
<author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id: userguide.xml,v 1.1 2003/03/10 04:08:06 mbecke Exp $</revision>
</properties>
<body>
<section name="User Guide">
<p>The HttpClient user guide is designed to help developers use
HttpClient in their applications. While the concept of a user guide
being for developers may seem strange, the term developer guide is
already in use for helping people develop HttpClient.</p>
</section>
<section name="Overview">
<table>
<tr>
<th>Document</th>
<th>Description</th>
</tr>
<tr>
<td><a href="authentication.html">Authentication Guide</a></td>
<td>This document describes the authentication schemes supported by
HttpClient and how to use them.</td>
</tr>
<tr>
<td><a href="charencodings.html">Character Encodings</a></td>
<td>To be completed. Guidelines for correctly detecting the
character encoding to use when sending and receiving data with
HttpClient.</td>
</tr>
<tr>
<td><a href="redirects.html">Cross Host Redirects</a></td>
<td>To be completed. Provide sample code for handling redirects
across hosts.</td>
</tr>
<tr>
<td><a href="logging.html">Logging Guide</a></td>
<td>This document describes the logging mechanism used by HttpClient
and how to control what it outputs.</td>
</tr>
<tr>
<td><a href="methods.html">Methods</a></td>
<td>To be completed. This document describes the various methods
that are provided by HttpClient and how to use them.</td>
</tr>
<tr>
<td><a
href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/";>Sample
Code</a></td>
<td>This is a link to the sample code for using HttpClient that is
stored in the CVS repository and is available in source releases
of HttpClient.</td>
</tr>
<tr>
<td><a href="troubleshooting.html">Trouble Shooting</a></td>
<td>This document provides hints and tips for debugging problems with
HttpClient.</td>
</tr>
<tr>
<td><a href="tutorial.html">Tutorial</a></td>
<td>This document provides a simple introductory tutorial for new users
of HttpClient.</td>
</tr>
</table>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/redirects.xml
Index: redirects.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Cross Host Redirects</title>
<author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id: redirects.xml,v 1.1 2003/03/10 04:08:06 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>This document provides a brief guide to handling cross host redirects
with HttpClient. In future versions of HttpClient it is anticipated that
this will be handled by HttpClient automatically, however due to
technical constraints and the desire to stabilise the API for a 2.0
release sooner rather than later, this ability is yet to be implemented.
Redirects to a different URL on the same host is supported however.</p>
</section>
<section name="Handling Redirects">
<p>When a server returns a redirect instruction to HttpClient that
requires connecting to a different host, HttpClient will simply return
the redirect status code as the response status. This will be one of:</p>
<ul>
<li>301 Moved Permanently.
<code>HttpStatus.SC_MOVED_PERMANENTLY</code></li>
<li>302 Moved Temporarily.
<code>HttpStatus.SC_MOVED_TEMPORARILY</code></li>
<li>303 See Other. <code>HttpStatus.SC_SEE_OTHER</code></li>
<li>307 Temporary Redirect.
<code>HttpStatus.SC_TEMPORARY_REDIRECT</code></li>
</ul>
<p>When your application receives one of these codes it should extract
the new URL to use and retry downloading from that URL. Additionally, it
is usually a good idea to limit the number of redirects that will be
followed in the redirects point to each other.</p>
<p>The URL to connect to can be extracted from the <code>Location</code>
header.</p>
<source><![CDATA[
String redirectLocation;
Header locationHeader = method.getResponseHeader("location");
if (locationHeader != null) {
redirectLocation = locationHeader.getValue();
} else {
// The response is invalid and did not provide the new location for
// the resource. Report an error or possibly handle the response
// like a 404 Not Found error.
}
]]></source>
<p>Once you have determined the new location, you can reattempt the
connection as normal. See the <a href="tutorial.html">Tutorial</a> for
more information on this.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/developerguide.xml
Index: developerguide.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>HttpClient Developer Guide</title>
<author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id: developerguide.xml,v 1.1 2003/03/10 04:08:06 mbecke Exp
$</revision>
</properties>
<body>
<section name="Developer Guide">
<p>This section contains supplementary information relating to the
development of HttpClient. You should be sure to read the
<a href="/site/getinvolved.html">general jakarta documentation</a> and
the commons specific <a href="/commons/volunteering.html">volunteering</a>
page. These pages describe how to contribute to any Jakarta project and
will not only help you contribute, but give you a grounding in what
Apache and the Jakarta project is all about.</p>
<p>Some other links that may be of interest:</p>
<ul>
<li><a href="/site/mission.html">The Jakarta Mission</a></li>
<li><a href="http://www.apache.org/foundation/contributing.html";>
Contributing to the Apache Software Foundation</a></li>
<li><a href="http://incubator.apache.org/index.html";>The Incubator
Project</a> - A large part of this project is providing documentation
on how the Apache Foundation works.</li>
<li><a href="http://www.apache.org/foundation/faq.html";>The Apache
FAQ</a></li>
</ul>
</section>
<section name="Overview">
<table>
<tr>
<th>Document</th>
<th>Description</th>
</tr>
<tr>
<td><a href="releases.html">Release Guide</a></td>
<td>This document describes the release process for HttpClient.</td>
</tr>
<tr>
<td><a href="testwebapp.html">Webapp Test Guide</a></td>
<td>This document describes how to setup the testing webapp and run
the localhost tests.</td>
</tr>
</table>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/methods.xml
Index: methods.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>HttpClient Methods</title>
<author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id: methods.xml,v 1.1 2003/03/10 04:08:06 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>These documents provide a brief introduction to using the methods
provided by HttpClient. The information here does not cover all the
possible options, but covers enough of the basics to get you up and
running. For more information on the available options, refer to the <a
href="apidocs/index.html">API Reference</a>.</p>
<p>The examples on the following pages are not complete and are only used
to highlight the important methods that are unique to each method. For
complete examples, please refer to the <a
href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/";>sample
code</a>.</p>
</section>
<section name="Overview">
<table>
<tr>
<th>Document</th>
<th>Description</th>
</tr>
<tr>
<td><a href="methods/options.html">Options</a></td>
<td>The OPTIONS method represents a request for information about the
communication options available.</td>
</tr>
<tr>
<td><a href="methods/get.html">Get</a></td>
<td>The GET method means retrieve whatever information is identified
by the requested URL. Also refer to the
<a href="tutorial.html">tutorial</a>.</td>
</tr>
<tr>
<td><a href="methods/head.html">Head</a></td>
<td>The HEAD method is identical to GET except that the server
<i>must not</i> return a message-body in the response. This method
can be used for obtaining metainformation about the document implied
by the request without transferring the document itself.</td>
</tr>
<tr>
<td><a href="methods/post.html">Post</a></td>
<td>The POST method is used to request that the origin server accept
the data enclosed in the request as a new child of the request URL.
POST is designed to allow a uniform method to cover a variety of
functions such as appending to a database, providing data to a
data-handling process or posting to a message board.</td>
</tr>
<tr>
<td><a href="methods/multipartpost.html">Multipart Post</a></td>
<td>The multipart post method is identical to the POST method,
except that the request body is separated into multiple parts. This
method is generally used when uploading files to the server.</td>
</tr>
<tr>
<td><a href="methods/put.html">Put</a></td>
<td>The PUT method requests that the enclosed document be stored under
the supplied URL. This method is generally disabled on publicly
available servers because it is generally undesireable to allow
clients to put new files on the server or to replace existing
files.</td>
</tr>
<tr>
<td><a href="methods/delete.html">Delete</a></td>
<td>The DELETE method requests that the server delete the resource
identified by the request URL. This method is generally disabled on
publicly available servers because it is generally undesireable to
allow clients to delete files on the server.</td>
</tr>
<tr>
<td><a href="methods/trace.html">Trace</a></td>
<td>The TRACE method is used to invoke a remote, application-layer
loop-back of the request message. This allows the client to see what
is being received at the other end of the request chain and use that
data for testing or diagnostic information.</td>
</tr>
</table>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
