You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by mb...@apache.org on 2003/03/10 05:07:41 UTC
cvs commit: jakarta-commons/httpclient/xdocs/methods put.xml trace.xml post.xml get.xml options.xml delete.xml multipartpost.xml head.xml
mbecke 2003/03/09 20:07:41
Added: httpclient/xdocs/methods put.xml trace.xml post.xml get.xml
options.xml delete.xml multipartpost.xml head.xml
Log:
New developer documentation.
PR: 10809
Submitted by: Adrian Sutton
Revision Changes Path
1.1 jakarta-commons/httpclient/xdocs/methods/put.xml
Index: put.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Put Method</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
<revision>$Id: put.xml,v 1.1 2003/03/10 04:07:40 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>The PUT method requests that the enclosed entity be stored under the
supplied URL. If the URL refers to an already existing resource, the
enclosed entity <i>should</i> be considered as a modified version of the
one residing on teh origin server. If the URL does not point to an
existing resource, and that URL is capable of being defined as a new
resource by the requesting user agent, the origin server can create the
resource with that URL.</p>
<p>If the request passes through a cache and the URL identifies one or
more currently cached entities, those entries <i>should</i> be treated as
stale. Responses to this method are not cacheable.</p>
<p>The fundamental difference between <a href="post.html">POST</a> and
PUT requests is reflected in the different meaning of the request URL.
The URL in a POST request identifies the resource that will handle the
enclosed entity. That resource might be a data-accepting process, a
gateway to some other protocol, or a separate entity that accepts
annotations. In contrast, the URL in a PUT request identifies the entity
enclosed with the request -- the user agent knows what URL is intended
and the server <b>must not</b> attempt to apply the request to some other
resource.</p>
<p>Unless otherwise specified for a particular entity-header, the
entity-headers in the PUT request <i>should</i> be applied to the
resource created or modified by the PUT.</p>
</section>
<section name="Typical Usage">
<p>The put method is very simple, it takes a URL to put to and requires
that the body of the request method be set to the data to upload. The
body can be set with an input stream or a string.</p>
<source><![CDATA[
PutMethod put = new PutMethod("http://jakarta.apache.org");
put.setRequestBody(new FileInputStream("UploadMe.gif"));
// execute the method and handle any error responses.
...
// Handle the response. Note that a successful response may not be
// 200, but may also be 201 Created, 204 No Content or any of the other
// 2xx range responses.
]]>
</source>
</section>
<section name="Common Problems">
<p>The PUT method is not widely supported on public servers due to
security concerns and generally FTP is used to upload new and modified
files to the webserver. Before executing a PUT method on a URL, it may
be worth checking that PUT is supported using the <a
href="options.html">OPTIONS</a> method.</p>
</section>
<section name="RFC Section">
<p>The put method is defined in section 9.6 of <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/methods/trace.xml
Index: trace.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Trace Method</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
<revision>$Id: trace.xml,v 1.1 2003/03/10 04:07:40 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>The TRACE method is primarily used for debugging and testing purposes,
and simply requests that the server echo back the request it received.
This can be useful for identifying any changes to the request that is
made by proxies.</p>
<p>The TRACE method is used to invoke a remote, application-layer
loop-back of the request message. The final recipient of the request
<i>should</i> reflect the message received back to the client as the
entity-body of a 200 (OK) response. The final recipient is either the
origin server or the first proxy or gateway to receive a max-Forwards
value of zero (0) in the request (see section 14.31 of <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>).</p>
</section>
<section name="Typical Usage">
<p>The trace method simply requires providing a URL and reading the
response received. Additional headers can be added with the
<code>addRequestHeader</code> method as with any other HttpMethod.</p>
<source><![CDATA[
TraceMethod trace = new TraceMethod("http://jakarata.apache.org");
// Execute the method and handle any errors.
...
// Read the response body.
String request = trace.getResponseBodyAsString();
trace.releaseConnection();
]]>
</source>
</section>
<section name="Common Problems">
<p>None.</p>
</section>
<section name="RFC Section">
<p>The trace method is defined in section 9.6 of <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/methods/post.xml
Index: post.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Post Method</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
<revision>$Id: post.xml,v 1.1 2003/03/10 04:07:40 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>The post method is used to request that the origin server accept the
entity enclosed in the request as a new subordinate of the resource
identified by the Request-URI in the Request-Line. Essentially this
means that the POST data will be stored by the server and usually will be
processed by a server side application.</p>
<p>Post is designed to allow a uniform method to cover the following
functions:</p>
<ul>
<li>Annotation of existing resources.</li>
<li>Posting a message to a bulletin board, newsgroup, mailing list, or
similar group of articles.</li>
<li>Providing a block of data, such as the result of submitting a form,
to a data-handling process.</li>
<li>Extending a database through an append operation.</li>
</ul>
<p>It is generally expected that a POST request will have some side
effect on the server such as writing to a database, and the HTTP
specification suggests that user agents represent user actions which
result in a POST request in a special way, so that the user is made aware
of the fact that a possibly unsafe action is being requested. This
however, is not a requirement.</p>
</section>
<section name="Typical Usage">
<p>There are two major steps to using the POST method, firstly providing
the data for the request and secondly reading the response from the
server.</p>
<p>The request data is supplied by one of the variants of
<code>setRequestBody</code> which can either take an
<code>InputStream</code> an array of <code>NameValuePair</code> objects
or a <code>String</code>. The simplest form is to pass in a
NameValuePair and allow HttpClient to format the request body according
to the standard, however this requires that the full content be stored in
memory which may not be desireable. In this case, passing in an
InputStream would be more appropriate.</p>
<p>The body of the method can be read using any of the methods in the <a
href="get.html">GET</a> method.</p>
<source><![CDATA[
PostMethod post = new PostMethod("http://jakarata.apache.org/");
NameValuePair[] data = {
new NameValuePair("user", "joe"),
new NameValuePair("password", "bloggs")
};
post.setRequestBody(data);
// execute method and handle any error responses.
...
InputStream in = post.getResponseBodyAsStream();
// handle response.
]]>
</source>
</section>
<section name="Common Problems">
<p>The most common problem when using the post method is not reading the
entire response body and calling releaseConnection regardless of the
response received from the server or whether or not the response body is
useful to your application.</p>
</section>
<section name="RFC Section">
<p>The post method is defined in section 8.3 of <a
href="http://www.ietf.org/rfc/rfc1945.txt">RFC1945</a> and similarly
redefined for HTTP 1.1 in section 9.5 of <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/methods/get.xml
Index: get.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Get Method</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
<revision>$Id: get.xml,v 1.1 2003/03/10 04:07:40 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>The GET method means retrieve whatever information (int hte form of an
entity) is identified by the Request-URI. If the Request-URI refers to a
data-producing process, it is the produced data which shall be returned
as the entity in the response and not the source text of the process,
unless that text happens to be the output of the process.</p>
<p>The semantics of the GET method change to a "conditional GET" if the
request message includes an If-ModifiedSince, If-Unmodified-Since,
If-Match, If-None-Match, or If-Range header field. A conditional GET
method requests that the entity be transferred only under the
circumstances described by the conditional header field(s). This reduces
unnecessary network usage by allowing cached entities to be refreshed
without requiring multiple requests or transferring data already held by
the client.</p>
<p>If a Range header field is included, the request is for only the part
of the entity specified by the range header. This allows partially
retrieved entities to be completed without transferring previously
received data.</p>
</section>
<section name="Typical Usage">
<p>Typically the get method is used to download a document from a web
server. This can be achieved with the method, getResponseBody,
getResponseBodyAsStream or getResponseBodyAsString. Of these methods,
getResponseBodyAsStream is generally the best choice as it avoids
unnessecary buffering of all data into memory before processing.</p>
<p>See the <a href="../tutorial.html">tutorial</a> for a full example
of using the GET method. There are also a number of examples in the <a
href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/">sample
code</a>.</p>
<source><![CDATA[
GetMethod get = new GetMethod("http://jakarta.apache.org");
// execute method and handle any error responses.
...
InputStream in = get.getResponseBodyAsStream();
// Process the data from the input stream.
get.releaseConnection();
]]>
</source>
</section>
<section name="Common Problems">
<p>The most common mistake when using the GET method is failing to read
the entire response body, even if an error code, redirect or any other
response status is received. Also be sure to call releaseConnection() on
the method regardless of the response code received.</p>
</section>
<section name="RFC Section">
<p>The get method is defined in section 8.1 of <a
href="http://www.ietf.org/rfc/rfc1945.txt">RFC1945</a> and similarly
defined for HTTP 1.1 in section 9.3 of <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/methods/options.xml
Index: options.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Options Method</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
<revision>$Id: options.xml,v 1.1 2003/03/10 04:07:40 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>The OPTIONS method represents a request for information about the
communication options available on the request/response chain identified
by the request URL. This method allows the client to determine the
options and/or requirements associated with a resource, or the
capabilities of a server, without implying a resource action or
initiating a resource retrieval.</p>
</section>
<section name="Typical Usage">
<p>Typically the options method is used to determine what methods are
supported by the server, and this is accomodated by the
<code>getAllowedMethods</code> function.</p>
<source><![CDATA[
OptionsMethod options = new OptionsMethod("http://jakarta.apache.org");
// execute method and handle any error responses.
...
Enumeration allowedMethods = options.getAllowedMethods();
options.releaseConnection();
]]>
</source>
</section>
<section name="Common Problems">
<p>None.</p>
</section>
<section name="RFC Section">
<p>The options method is defined in section 9.2 of <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/methods/delete.xml
Index: delete.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Delete Method</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
<revision>$Id: delete.xml,v 1.1 2003/03/10 04:07:40 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>The delete method requests that the origin server delete the resource
identified by the request URL. This method <i>may</i> be overridden by
human intervention (or other means) on the origin server. The client
cannot be guaranteed that the operation has been carried out, even if the
status code returned from the origin server indicates that the action has
been completed successfully. However, the server <i>should not</i>
indicate success unless, at the time the response is given, it intends to
delete the resource or move it to an inaccessible location.</p>
<p>A successful response <i>should</i> be 200 (OK) if the response
includes a response body describing the status, 202 (Accepted) if the
action has not yet been enacted, or 204 (No Content) if the action has
been enacted but the response does not include a response body.</p>
<p>If the request passes through a cache and the URL identifies one or
more currently cached entities, those entries <i>should</i> be treated as
stale. Responses to this method are not cacheable.</p>
</section>
<section name="Typical Usage">
<p>The delete method is used by supplying a URL to delete the resource at
and reading the response from the server.</p>
<source><![CDATA[
DeleteMethod delete = new DeleteMethod("http://jakarata.apache.org");
// execute the method and handle any error responses.
...
// Ensure that if there is a response body it is read, then release the
// connection.
...
delete.releaseConnection();
]]>
</source>
</section>
<section name="Common Problems">
<p>The DELETE method is not widely supported on public servres due to
security concerns and generally FTP is used to delete files on the
webserver. Before executing a DELETE method, it may be worth checking
that DELETE is supported using the <a href="options.html">OPTIONS</a>
method.</p>
</section>
<section name="RFC Section">
<p>The delete method is defined in section 9.7 of <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/methods/multipartpost.xml
Index: multipartpost.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Multipart Post Method</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
<revision>$Id: multipartpost.xml,v 1.1 2003/03/10 04:07:40 mbecke Exp $</revision>
</properties>
<body>
<section name="Introduction">
<p>The multipart post method is a different request body format for a
<a href="post.html">POST</a> method. The media-type multipart/form-data
follows the rules of all multipart MIME data streams as outlined in RFC
1521. It is intended for use in returning the data that comes about from
filling out a form, particularly when the form requires binary data to
be uploaded such as the contents of a file.</p>
</section>
<section name="Typical Usage">
<p>Like for the standard POST method, there are two main steps to using
the multipart post method, setting the request data and retrieving the
response data.</p>
<p>The request data is specified by adding parameters to the method,
these are defined by the
<code>org.apache.commons.httpclient.methods.multipart.Part</code> class
and it's various subclasses. A description of each of these is below.</p>
<table>
<tr>
<th>Part</th>
<th>Description</th>
</tr>
<tr>
<td>StringPart</td>
<td>The string part is a simple part that takes a name for the part
and the value of the part as a string. This is typically used for
standard form elements such as a text area within a multipart
form.</td>
</tr>
<tr>
<td>FilePart</td>
<td>The file part is actually a very generic type of part that can
contain any type of data and specify a name, content type and charset
for the data. In it's simplest form, it takes just a name and a File
object and uploads the contents of the file, however it can also be
passed a <code>PartSource</code> object to upload. See the part
source section below for more information.</td>
</tr>
</table>
<subsection name="Part Sources">
<p>The <code>PartSource</code> interface provides a generic container
for providing data to the FilePart class. There are two concrete
implementations of PartSource provided with HttpClient (described
below) but you can also provide your own implementation easily. The
input for the multipart post could come from anywhere, perhaps it's
being received from another server or process, and all that the
PartSource class needs to be able to do is provide the length of the
data that will be provided, an input stream to retrieve the data from
and a file name (or some name identifying the data).</p>
<p>The two concrete implementations of PartSource are FilePartSource
and ByteArrayPartSource. FilePartSource simply takes a File to upload
whereas ByteArrayPartSource allows for the case where the data has been
cached in memory and takes a file name and a byte array to upload.</p>
</subsection>
</section>
<section name="Common Problems">
<p>The most common problem people run into with multipart uploads is that
the length of the data must be known before hand. If the length of the
data can not be determined in advance, it needs to be cached either in
memory or to a file and then uploaded using either ByteArrayPartSource or
FilePartSource. The HTTP specification does not allow for POST data to
be of an unknown length.</p>
</section>
<section name="RFC Section">
<p>The multipart form data uses the POST method from the HTTP standard
which is defined in section 8.3 of <a
href="http://www.ietf.org/rfc//rfc1945.txt">RFC1945</a> and similarly
redefined for HTTP 1.1 in section 9.5 of <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>.</p>
<p>The multipart/form-data MIME type used to format the body of the
request is defined in <a
href="http://www.ietf.org/rfc/rfc1867.txt">RFC1867</a>.</p>
</section>
</body>
</document>
1.1 jakarta-commons/httpclient/xdocs/methods/head.xml
Index: head.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Head Method</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
<revision>$Id: head.xml,v 1.1 2003/03/10 04:07:40 mbecke Exp $</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
teh 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>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org