Understanding HttpClient

The basic object when working with HttpClient is, of course, HttpClient, as shown in Figure 3-3. This object represents a complete HTTP client, keeping track of state (e.g., cookies and authentication management), and it includes support for things like connection pooling and persistent connections.

Figure 3-3. HttpClient class.

To actually make a connection, create a "method" object, corresponding to the type of request desired (for example, GET, POST, PUT, OPTIONS, HEAD, etc.). The most common methods are GET (a simple URI retrieval, e.g., "http://www.cascadetg.com/") and POST (sending form data back to a URI). For more information on the other methods, you may want to consult the RFC for HTTP 1.1 at http://www.ietf.org/rfc/rfc2616.txt. The hierarchy of methods can be found in Figure 3-4.

Figure 3-4. HTTP methods relationship diagram.

The main methods of interest for HttpMethod and HttpUrlMethod are shown in Figure 3-5.

Figure 3-5. HttpMethod interface.

You may want to inquire about the current status of the client, for example to determine the current state of the cookies that have been set. To do this, you use the HttpClient.getState() method. This returns an HttpState object, as shown in Figure 3-6.

Figure 3-6. HttpState.

So, to recap, you'll use an HttpClient object as a single representation of a client, you'll create an HttpMethod to make a connection, and you'll inspect the HttpState object to get data about the current client state.

Content Type

Given a particular URI, you may be curious about the type of content being downloaded. The content type is typically expressed in a notation known as MIME (see http://www.iana.org/assignments/media-types/). For example, text/plain indicates an ordinary text file, image/png indicates a PNG file, and application/msword indicates a Microsoft Word document. Depending on the type of content downloaded, you may want to take different action for dealing with the data.

Generally speaking, you have three options for determining the MIME type of a bit of content: the information supplied by the server, the file name, and guessing based on the actual bytes of the file content.

Ideally, the server should be configured to return the MIME of the data sent as a header, in which case you would use the HttpMethod.getRequestHeader("Content-Type") method to obtain the content MIME type. Unfortunately, the server may be set to send the incorrect type. In this case, you can use the static method java.net.URLConnection .guessContentTypeFromName(String fname) to attempt to guess the file type based on the file name and extension. Finally, if that doesn't work, you may want to try java.net.URLConnection.guessContentTypeFromStream (InputStream is). None of these methods is guaranteed to be correctdepending on your application, you may want to default to a particular method and document this behavior in your user documentation.