1 /*
2 * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v 1.23 2003/01/28 04:40:20 jsdever Exp $
3 * $Revision: 1.23 $
4 * $Date: 2003/01/28 04:40:20 $
5 *
6 * ====================================================================
7 *
8 * The Apache Software License, Version 1.1
9 *
10 * Copyright (c) 1999-2003 The Apache Software Foundation. All rights
11 * reserved.
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 *
17 * 1. Redistributions of source code must retain the above copyright
18 * notice, this list of conditions and the following disclaimer.
19 *
20 * 2. Redistributions in binary form must reproduce the above copyright
21 * notice, this list of conditions and the following disclaimer in
22 * the documentation and/or other materials provided with the
23 * distribution.
24 *
25 * 3. The end-user documentation included with the redistribution, if
26 * any, must include the following acknowlegement:
27 * "This product includes software developed by the
28 * Apache Software Foundation (http://www.apache.org/)."
29 * Alternately, this acknowlegement may appear in the software itself,
30 * if and wherever such third-party acknowlegements normally appear.
31 *
32 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
33 * Foundation" must not be used to endorse or promote products derived
34 * from this software without prior written permission. For written
35 * permission, please contact apache@apache.org.
36 *
37 * 5. Products derived from this software may not be called "Apache"
38 * nor may "Apache" appear in their names without prior written
39 * permission of the Apache Group.
40 *
41 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
42 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
43 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
45 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
47 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
48 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
49 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
50 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
51 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
52 * SUCH DAMAGE.
53 * ====================================================================
54 *
55 * This software consists of voluntary contributions made by many
56 * individuals on behalf of the Apache Software Foundation. For more
57 * information on the Apache Software Foundation, please see
58 * <http://www.apache.org/>.
59 *
60 * [Additional notices, if required by prior licensing conditions]
61 *
62 */
63
64 package org.apache.commons.httpclient;
65
66 import java.io.IOException;
67 import java.io.InputStream;
68
69 /***
70 * <p>
71 * A request to be applied to an {@link HttpConnection}, and a container for the
72 * associated response.
73 * </p>
74 * @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
75 * @author Rod Waldhoff
76 * @author <a href="jsdever@apache.org">Jeff Dever</a>
77 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
78 *
79 * @version $Revision: 1.23 $ $Date: 2003/01/28 04:40:20 $
80 * @since 1.0
81 */
82 public interface HttpMethod {
83
84 // ------------------------------------------- Property Setters and Getters
85
86 /***
87 * Obtain the name of this method, suitable for use in the "request line",
88 * for example <tt>"GET"</tt> or <tt>"POST"</tt>.
89 * @return the name of this method
90 */
91 String getName();
92
93 /***
94 * Gets the host configuration for this method.
95 *
96 * @return the HostConfiguration or <code>null</code> if none is set
97 */
98 HostConfiguration getHostConfiguration();
99
100 /***
101 * Set the path part of my request.
102 * @param path the path to request
103 */
104 void setPath(String path);
105
106 /***
107 * Get the path part of my request.
108 *
109 * Calling this method AFTER the request
110 * has been executed will return the ACTUAL path, following any 301 or 302
111 * redirects (except for redirects off the initial server, which are not
112 * supported, or when HttpClient is set to not follow redirects; in either
113 * case, HttpClient returns the 301 or 302 status code).
114 * @return the path to request
115 */
116 String getPath();
117
118 /***
119 * Gets the URI for this method. The URI will be absolute if the host
120 * configuration has been set or relative otherwise.
121 *
122 * @return URI
123 *
124 * @throws URIException if a URI cannot be constructed
125 */
126 URI getURI() throws URIException;
127
128 /***
129 * <p>Turns strict mode on or off. In strict mode (the default) we
130 * following the letter of RFC 2616, the Http 1.1 specification. If strict
131 * mode is turned off we attempt to violate the specification in the same
132 * way that most Http user agent's do (and many HTTP servers expect.</p>
133 *
134 * <p>NOTE: StrictMode is currently experimental and its functionaity may
135 * change in the future.</p>
136 *
137 * @param strictMode True to enable strict mode.
138 */
139 void setStrictMode(boolean strictMode);
140
141 /***
142 * Returns the value of strictMode.
143 *
144 * NOTE: StrictMode is currently experimental and its functionlaity may change in the future.
145 *
146 * @return true if strict mode is enabled.
147 */
148 boolean isStrictMode();
149
150 /***
151 * Set the specified request header, overwriting any
152 * previous value.
153 * Note that header-name matching is case insensitive.
154 * @param headerName the header's name
155 * @param headerValue the header's value
156 */
157 void setRequestHeader(String headerName, String headerValue);
158
159 /***
160 * Set the specified request header, overwriting any
161 * previous value.
162 * Note that header-name matching is case insensitive.
163 * @param header the header
164 */
165 void setRequestHeader(Header header);
166
167 /***
168 * Adds the specified request header, NOT overwriting any
169 * previous value.
170 * Note that header-name matching is case insensitive.
171 * @param headerName the header's name
172 * @param headerValue the header's value
173 */
174 void addRequestHeader(String headerName, String headerValue);
175
176 /***
177 * Adds the specified request header, NOT overwriting any
178 * previous value.
179 * Note that header-name matching is case insensitive.
180 * @param header the header
181 */
182 void addRequestHeader(Header header);
183
184 /***
185 * Get the request header associated with the given name.
186 * Note that header-name matching is case insensitive.
187 * @param headerName the header name
188 * @return the header
189 */
190 Header getRequestHeader(String headerName);
191
192 /***
193 * Remove all request headers associated with the given name.
194 * Note that header-name matching is case insensitive.
195 * @param headerName the header name
196 */
197 void removeRequestHeader(String headerName);
198
199 /***
200 * Whether or not I should automatically follow
201 * HTTP redirects (status code 302, etc.)
202 * @return <tt>true</tt> if I will automatically follow HTTP redirects
203 */
204 boolean getFollowRedirects();
205
206 /***
207 * Set whether or not I should automatically follow HTTP redirects (status
208 * code 302, etc.)
209 * @param followRedirects True if I should automatically follow redirects.
210 */
211 void setFollowRedirects(boolean followRedirects);
212
213 /***
214 * Set my query string.
215 * @param queryString the query string
216 */
217 void setQueryString(String queryString);
218
219 /***
220 * Set my query string.
221 * @param params an array of {@link NameValuePair}s
222 * to add as query string parameterss
223 */
224 void setQueryString(NameValuePair[] params);
225
226 /***
227 * Get my query string.
228 * @return my query string
229 */
230 String getQueryString();
231
232 /***
233 * Return an array of my request headers.
234 * @return an array of request headers.
235 */
236 Header[] getRequestHeaders();
237
238 // ---------------------------------------------------------------- Queries
239
240 /***
241 * Confirm that I am ready to execute.
242 * @return True if I am ready to execute.
243 */
244 boolean validate();
245
246 /***
247 * Return the status code associated with the latest response.
248 * @return the status code.
249 */
250 int getStatusCode();
251
252 /***
253 * Return the status text (or "reason phrase") associated with the latest
254 * response.
255 * @return The status text.
256 */
257 String getStatusText();
258
259 /***
260 * Return an array of my response headers.
261 * @return An array of all the response headers.
262 */
263 Header[] getResponseHeaders();
264
265 /***
266 * Return the specified response header. Note that header-name matching is
267 * case insensitive.
268 * @param headerName The name of the header to be returned.
269 * @return The specified response header.
270 */
271 Header getResponseHeader(String headerName);
272
273 /***
274 * Return an array of my response footers
275 * @return <tt>null</tt> if no footers are available
276 */
277 Header[] getResponseFooters();
278
279 /***
280 * Return the specified response footer. Note that footer-name matching is
281 * case insensitive.
282 * @param footerName The name of the footer.
283 * @return The response footer.
284 */
285 Header getResponseFooter(String footerName);
286
287 /***
288 * Return my response body, if any, as a byte array. Otherwise return
289 * <tt>null</tt>.
290 * @return The response body.
291 */
292 byte[] getResponseBody();
293
294 /***
295 * Return my response body, if any, as a {@link String}. Otherwise return
296 * <tt>null</tt>.
297 * @return response body.
298 */
299 String getResponseBodyAsString();
300
301 /***
302 * Return my response body, if any, as an {@link InputStream}. Otherwise
303 * return <tt>null</tt>.
304 * @return As above.
305 * @throws IOException If an IO problem occurs.
306 */
307 InputStream getResponseBodyAsStream() throws IOException;
308
309 /***
310 * Return <tt>true</tt> if I have been {@link #execute executed}
311 * but not recycled.
312 * @return true if this has been used.
313 */
314 boolean hasBeenUsed();
315
316 // --------------------------------------------------------- Action Methods
317
318 /***
319 * Execute this method.
320 *
321 * @param state state information to associate with this request
322 * @param connection the {@link HttpConnection} to write to/read from
323 *
324 * @throws IOException if an I/O error occurs
325 * @throws HttpException if an protocol exception occurs
326 *
327 * @return the integer status code if one was obtained, or <tt>-1</tt>
328 */
329 int execute(HttpState state, HttpConnection connection)
330 throws HttpException, IOException;
331
332 /***
333 * Recycle this method so that it can be used again.
334 * Note that all of my instance variables will be reset
335 * once this method has been called.
336 */
337 void recycle();
338
339 /***
340 * Releases the connection being used by this method. In particular the
341 * connection is used to read the response(if there is one) and will be held
342 * until the response has been read.
343 */
344 void releaseConnection();
345
346 /***
347 * Use this method internally to add footers.
348 * @param footer The footer to add.
349 * @since 2.0
350 */
351 void addResponseFooter(Header footer);
352
353 /***
354 * Return the Status-Line from the response.
355 * @return The status line
356 * @since 2.0
357 */
358 StatusLine getStatusLine();
359
360 /***
361 * Whether or not I should automatically process responses where
362 * authentication is required (status code 401, etc.)
363 *
364 * @return <tt>true</tt> if authentications will be processed automatically
365 * @since 2.0
366 */
367 boolean getDoAuthentication();
368
369 /***
370 * Set whether or not I should automatically process responses where
371 * authentication is required (status code 401, etc.)
372 *
373 * @param doAuthentication <tt>true</tt> to process authentications
374 * @since 2.0
375 */
376 void setDoAuthentication(boolean doAuthentication);
377
378 }
This page was automatically generated by Maven