2
* $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v 1.23.2.5 2004/06/13 20:24:48 olegk Exp $
3
* $Revision: 1.23.2.5 $
4
* $Date: 2004/06/13 20:24:48 $
6
* ====================================================================
8
* Copyright 1999-2004 The Apache Software Foundation
10
* Licensed under the Apache License, Version 2.0 (the "License");
11
* you may not use this file except in compliance with the License.
12
* You may obtain a copy of the License at
14
* http://www.apache.org/licenses/LICENSE-2.0
16
* Unless required by applicable law or agreed to in writing, software
17
* distributed under the License is distributed on an "AS IS" BASIS,
18
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19
* See the License for the specific language governing permissions and
20
* limitations under the License.
21
* ====================================================================
23
* This software consists of voluntary contributions made by many
24
* individuals on behalf of the Apache Software Foundation. For more
25
* information on the Apache Software Foundation, please see
26
* <http://www.apache.org/>.
28
* [Additional notices, if required by prior licensing conditions]
32
package org.apache.commons.httpclient;
34
import java.io.IOException;
35
import java.io.InputStream;
39
* HttpMethod interface represents a request to be sent via a
40
* {@link HttpConnection HTTP connection} and a corresponding response.
42
* @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
43
* @author Rod Waldhoff
44
* @author <a href="jsdever@apache.org">Jeff Dever</a>
45
* @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
46
* @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
48
* @version $Revision: 1.23.2.5 $ $Date: 2004/06/13 20:24:48 $
52
public interface HttpMethod {
54
// ------------------------------------------- Property Setters and Getters
57
* Obtains the name of the HTTP method as used in the HTTP request line,
58
* for example <tt>"GET"</tt> or <tt>"POST"</tt>.
60
* @return the name of this method
65
* Gets the host configuration for this method. The configuration specifies
66
* the server, port, protocol, and proxy server via which this method will
67
* send its HTTP request.
69
* @return the HostConfiguration or <code>null</code> if none is set
71
HostConfiguration getHostConfiguration();
74
* Sets the path of the HTTP method.
75
* It is responsibility of the caller to ensure that the path is
76
* properly encoded (URL safe).
78
* @param path The path of the HTTP method. The path is expected
81
void setPath(String path);
84
* Returns the path of the HTTP method.
86
* Calling this method <em>after</em> the request has been executed will
87
* return the <em>actual</em> path, following any redirects automatically
88
* handled by this HTTP method.
90
* @return the path of the HTTP method, in URL encoded form
95
* Returns the URI for this method. The URI will be absolute if the host
96
* configuration has been set and relative otherwise.
98
* @return the URI for this method
100
* @throws URIException if a URI cannot be constructed
102
URI getURI() throws URIException;
105
* Defines how strictly the method follows the HTTP protocol specification.
106
* (See RFC 2616 and other relevant RFCs.) In the strict mode the method precisely
107
* implements the requirements of the specification, whereas in non-strict mode
108
* it attempts to mimic the exact behaviour of commonly used HTTP agents,
109
* which many HTTP servers expect.
111
* @param strictMode <tt>true</tt> for strict mode, <tt>false</tt> otherwise
113
* @see #isStrictMode()
115
void setStrictMode(boolean strictMode);
118
* Returns the value of the strict mode flag.
120
* @return <tt>true</tt> if strict mode is enabled, <tt>false</tt> otherwise
122
* @see #setStrictMode(boolean)
124
boolean isStrictMode();
127
* Sets the specified request header, overwriting any previous value.
128
* Note that header-name matching is case insensitive.
130
* @param headerName the header's name
131
* @param headerValue the header's value
133
* @see #setRequestHeader(Header)
134
* @see #getRequestHeader(String)
135
* @see #removeRequestHeader(String)
137
void setRequestHeader(String headerName, String headerValue);
140
* Sets the specified request header, overwriting any previous value.
141
* Note that header-name matching is case insensitive.
143
* @param header the header to be set
145
* @see #setRequestHeader(String,String)
146
* @see #getRequestHeader(String)
147
* @see #removeRequestHeader(String)
149
void setRequestHeader(Header header);
152
* Adds the specified request header, <em>not</em> overwriting any previous value.
153
* If the same header is added multiple times, perhaps with different values,
154
* multiple instances of that header will be sent in the HTTP request.
155
* Note that header-name matching is case insensitive.
157
* @param headerName the header's name
158
* @param headerValue the header's value
160
* @see #addRequestHeader(Header)
161
* @see #getRequestHeader(String)
162
* @see #removeRequestHeader(String)
164
void addRequestHeader(String headerName, String headerValue);
167
* Adds the specified request header, <em>not</em> overwriting any previous value.
168
* If the same header is added multiple times, perhaps with different values,
169
* multiple instances of that header will be sent in the HTTP request.
170
* Note that header-name matching is case insensitive.
172
* @param header the header
174
* @see #addRequestHeader(String,String)
175
* @see #getRequestHeader(String)
176
* @see #removeRequestHeader(String)
178
void addRequestHeader(Header header);
181
* Gets the request header with the given name.
182
* If there are multiple headers with the same name,
183
* there values will be combined with the ',' separator as specified by RFC2616.
184
* Note that header-name matching is case insensitive.
186
* @param headerName the header name
189
Header getRequestHeader(String headerName);
192
* Removes all request headers with the given name.
193
* Note that header-name matching is case insensitive.
195
* @param headerName the header name
197
void removeRequestHeader(String headerName);
200
* Returns <tt>true</tt> if the HTTP method should automatically follow HTTP redirects
201
* (status code 302, etc.), <tt>false</tt> otherwise.
203
* @return <tt>true</tt> if the method will automatically follow HTTP redirects,
204
* <tt>false</tt> otherwise
206
boolean getFollowRedirects();
209
* Sets whether or not the HTTP method should automatically follow HTTP redirects
210
* (status code 302, etc.)
212
* @param followRedirects <tt>true</tt> if the method will automatically follow redirects,
213
* <tt>false</tt> otherwise
215
void setFollowRedirects(boolean followRedirects);
218
* Sets the query string of the HTTP method.
219
* It is responsibility of the caller to ensure that the path is
220
* properly encoded (URL safe). The string must not include an initial '?' character.
222
* @param queryString the query to be used in the request, with no leading '?' character
224
* @see #getQueryString()
225
* @see #setQueryString(NameValuePair[])
227
void setQueryString(String queryString);
230
* Sets the query string of this HTTP method. The pairs are encoded as UTF-8 characters.
231
* To use a different charset the parameters can be encoded manually using EncodingUtil
232
* and set as a single String.
234
* @param params An array of <code>NameValuePair</code>s to use as the query string.
235
* The name/value pairs will be automatically URL encoded and should not
236
* have been encoded previously.
238
* @see #getQueryString()
239
* @see #setQueryString(String)
240
* @see org.apache.commons.httpclient.util.EncodingUtil#formUrlEncode(NameValuePair[], String)
242
void setQueryString(NameValuePair[] params);
245
* Returns the query string of this HTTP method.
247
* @return the query string in URL encoded form, without a leading '?'.
249
* @see #setQueryString(NameValuePair[])
250
* @see #setQueryString(String)
252
String getQueryString();
255
* Returns the current request headers for this HTTP method. The returned headers
256
* will be in the same order that they were added with <code>addRequestHeader</code>.
257
* If there are multiple request headers with the same name (e.g. <code>Cookie</code>),
258
* they will be returned as multiple entries in the array.
260
* @return an array containing all of the request headers
262
* @see #addRequestHeader(Header)
263
* @see #addRequestHeader(String,String)
265
Header[] getRequestHeaders();
267
// ---------------------------------------------------------------- Queries
270
* Returns <tt>true</tt> the method is ready to execute, <tt>false</tt> otherwise.
272
* @return <tt>true</tt> if the method is ready to execute, <tt>false</tt> otherwise.
277
* Returns the status code associated with the latest response.
279
* @return The status code from the most recent execution of this method.
280
* If the method has not yet been executed, the result is undefined.
285
* Returns the status text (or "reason phrase") associated with the latest
288
* @return The status text from the most recent execution of this method.
289
* If the method has not yet been executed, the result is undefined.
291
String getStatusText();
294
* Returns the response headers from the most recent execution of this request.
296
* @return A newly-created array containing all of the response headers,
297
* in the order in which they appeared in the response.
299
Header[] getResponseHeaders();
302
* Returns the specified response header. Note that header-name matching is
305
* @param headerName The name of the header to be returned.
307
* @return The specified response header. If the repsonse contained multiple
308
* instances of the header, its values will be combined using the ','
309
* separator as specified by RFC2616.
311
Header getResponseHeader(String headerName);
314
* Returns the response footers from the most recent execution of this request.
316
* @return an array containing the response footers in the order that they
317
* appeared in the response. If the response had no footers,
318
* an empty array will be returned.
320
Header[] getResponseFooters();
323
* Return the specified response footer. Note that footer-name matching is
326
* @param footerName The name of the footer.
327
* @return The response footer.
329
Header getResponseFooter(String footerName);
332
* Returns the response body of the HTTP method, if any, as an array of bytes.
333
* If the method has not yet been executed or the response has no body, <code>null</code>
334
* is returned. Note that this method does not propagate I/O exceptions.
335
* If an error occurs while reading the body, <code>null</code> will be returned.
337
* @return The response body, or <code>null</code> if the
338
* body is not available.
340
byte[] getResponseBody();
343
* Returns the response body of the HTTP method, if any, as a {@link String}.
344
* If response body is not available or cannot be read, <tt>null</tt> is returned.
345
* The raw bytes in the body are converted to a <code>String</code> using the
346
* character encoding specified in the response's <tt>Content-Type</tt> header, or
347
* ISO-8859-1 if the response did not specify a character set.
349
* Note that this method does not propagate I/O exceptions.
350
* If an error occurs while reading the body, <code>null</code> will be returned.
352
* @return The response body converted to a <code>String</code>, or <code>null</code>
353
* if the body is not available.
355
String getResponseBodyAsString();
358
* Returns the response body of the HTTP method, if any, as an InputStream.
359
* If the response had no body or the method has not yet been executed,
360
* <code>null</code> is returned. Additionally, <code>null</code> may be returned
361
* if {@link #releaseConnection} has been called or
362
* if this method was called previously and the resulting stream was closed.
364
* @return The response body, or <code>null</code> if it is not available
366
* @throws IOException if an I/O (transport) problem occurs
368
InputStream getResponseBodyAsStream() throws IOException;
371
* Returns <tt>true</tt> if the HTTP method has been already {@link #execute executed},
372
* but not {@link #recycle recycled}.
374
* @return <tt>true</tt> if the method has been executed, <tt>false</tt> otherwise
376
boolean hasBeenUsed();
378
// --------------------------------------------------------- Action Methods
381
* Executes this method using the specified <code>HttpConnection</code> and
382
* <code>HttpState</code>.
384
* @param state the {@link HttpState state} information to associate with this method
385
* @param connection the {@link HttpConnection connection} used to execute
388
* @throws IOException If an I/O (transport) error occurs. Some transport exceptions
389
* can be recovered from.
390
* @throws HttpException If a protocol exception occurs. Usually protocol exceptions
391
* cannot be recovered from.
393
* @return the integer status code if one was obtained, or <tt>-1</tt>
395
int execute(HttpState state, HttpConnection connection)
396
throws HttpException, IOException;
399
* Recycles the HTTP method so that it can be used again.
400
* Note that all of the instance variables will be reset
401
* once this method has been called. This method will also
402
* release the connection being used by this HTTP method.
404
* @see #releaseConnection()
406
* @deprecated no longer supported and will be removed in the future
407
* version of HttpClient
412
* Releases the connection being used by this HTTP method. In particular the
413
* connection is used to read the response (if there is one) and will be held
414
* until the response has been read. If the connection can be reused by other
415
* HTTP methods it is NOT closed at this point.
417
* After this method is called, {@link #getResponseBodyAsStream} will return
418
* <code>null</code>, and {@link #getResponseBody} and {@link #getResponseBodyAsString}
419
* <em>may</em> return <code>null</code>.
421
void releaseConnection();
424
* Add a footer to this method's response.
426
* <b>Note:</b> This method is for
427
* internal use only and should not be called by external clients.
429
* @param footer the footer to add
433
void addResponseFooter(Header footer);
436
* Returns the Status-Line from the most recent response for this method,
437
* or <code>null</code> if the method has not been executed.
439
* @return the status line, or <code>null</code> if the method has not been executed
443
StatusLine getStatusLine();
446
* Returns <tt>true</tt> if the HTTP method should automatically handle HTTP
447
* authentication challenges (status code 401, etc.), <tt>false</tt> otherwise
449
* @return <tt>true</tt> if authentication challenges will be processed
450
* automatically, <tt>false</tt> otherwise.
454
* @see #setDoAuthentication(boolean)
456
boolean getDoAuthentication();
459
* Sets whether or not the HTTP method should automatically handle HTTP
460
* authentication challenges (status code 401, etc.)
462
* @param doAuthentication <tt>true</tt> to process authentication challenges
463
* automatically, <tt>false</tt> otherwise.
467
* @see #getDoAuthentication()
469
void setDoAuthentication(boolean doAuthentication);
added
removed
src/java/org/apache/commons/httpclient/HttpMethod.java
