<?xml version="1.0" encoding="ISO-8859-1"?>

<document>

  <properties>
    <title>Head Method</title>
    <author email="adrian@ephox.com">Adrian Sutton</author>
    <revision>$Id$</revision>
  </properties>

  <body>

    <section name="Introduction">
      <p>The HEAD method is identical to the <a href="get.html">GET</a> method
      except that the server <i>must not</i> return a message-body in the
      response.  The metainformation contained in the HTTP headers in response
      to a HEAD request <i>should</i> be identical to the information sent in
      response to a GET request.  This allows a client to obtain
      meta-information about a resource without actually transferring the
      resource itself.</p>

      <p>The head method is often used for testing hyperlinks, accessibility
      and for determining if a document has been recently modifed.</p>

      <p>When your program is implementing caching, it is important to note
      that if the HEAD response indicates that the cached entity differs from
      the current entity, such as by a change in the Content-Length,
      Content-MD5, ETag or Last-Modified, the cache <b>must</b> treat the
      cached entry as stale.</p>
    </section>

    <section name="Typical Usage">
      <p>Typically the head method is used to retrieve the meta-information for
      a resource, perhaps to check if the resource has been modifed.  There are
      no methods specific to HeadMethod as the headers can be retreived using
      <code>getResponseHeaders()</code> as with any other method.</p>

      <source><![CDATA[
        HeadMethod head = new HeadMethod("http://jakarta.apache.org");
        // execute the method and handle any error responses.
        ...
        // Retrieve all the headers.
        Header[] headers = head.getResponseHeaders();

        // Retrieve just the last modified header value.
        String lastModified =
            head.getResponseHeader("last-modified").getValue();
        ]]>
      </source>
    </section>

    <section name="Common Problems">
      <p>None.</p>
    </section>

    <section name="RFC Section">
      <p>The head method is defined in section 8.2 of <a
      href="http://www.ietf.org/rfc/rfc1945.txt">RFC1945</a> and similarly
      redefined for HTTP 1.1 in section 9.4 of <a
      href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>.</p>
    </section>

  </body>

</document>
