KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > httpclient > params > HttpMethodParams


1 /*
2  * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/params/HttpMethodParams.java,v 1.17 2004/10/06 17:32:04 olegk Exp $
3  * $Revision: 483949 $
4  * $Date: 2006-12-08 11:34:50 +0000 (Fri, 08 Dec 2006) $
5  *
6  * ====================================================================
7  *
8  * Licensed to the Apache Software Foundation (ASF) under one or more
9  * contributor license agreements. See the NOTICE file distributed with
10  * this work for additional information regarding copyright ownership.
11  * The ASF licenses this file to You under the Apache License, Version 2.0
12  * (the "License"); you may not use this file except in compliance with
13  * the License. You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  * ====================================================================
23  *
24  * This software consists of voluntary contributions made by many
25  * individuals on behalf of the Apache Software Foundation. For more
26  * information on the Apache Software Foundation, please see
27  * <http://www.apache.org/>.
28  *
29  */

30
31 package org.apache.commons.httpclient.params;
32
33 import org.apache.commons.httpclient.HttpVersion;
34 import org.apache.commons.httpclient.cookie.CookiePolicy;
35 import org.apache.commons.logging.Log;
36 import org.apache.commons.logging.LogFactory;
37
38 /**
39  * This class represents a collection of HTTP protocol parameters applicable to
40  * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}. Protocol
41  * parameters may be linked together to form a hierarchy. If a particular
42  * parameter value has not been explicitly defined in the collection itself,
43  * its value will be drawn from the parent collection of parameters.
44  *
45  * @author <a HREF="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
46  * @author Christian Kohlschuetter
47  *
48  * @version $Revision: 483949 $
49  *
50  * @since 3.0
51  */

52 public class HttpMethodParams extends DefaultHttpParams {
53
54     /** Log object for this class. */
55     private static final Log LOG = LogFactory.getLog(HttpMethodParams.class);
56
57     /**
58      * Defines the content of the <tt>User-Agent</tt> header used by
59      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}.
60      * <p>
61      * This parameter expects a value of type {@link String}.
62      * </p>
63      */

64     public static final String JavaDoc USER_AGENT = "http.useragent";
65
66     /**
67      * Defines the {@link HttpVersion HTTP protocol version} used by
68      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} per
69      * default.
70      * <p>
71      * This parameter expects a value of type {@link HttpVersion}.
72      * </p>
73      */

74     public static final String JavaDoc PROTOCOL_VERSION = "http.protocol.version";
75
76     /**
77      * Defines whether {@link org.apache.commons.httpclient.HttpMethod HTTP methods} should
78      * reject ambiguous {@link org.apache.commons.httpclient.StatusLine HTTP status line}.
79      * <p>
80      * This parameter expects a value of type {@link Boolean}.
81      * </p>
82      */

83     public static final String JavaDoc UNAMBIGUOUS_STATUS_LINE = "http.protocol.unambiguous-statusline";
84
85     /**
86      * Defines whether {@link org.apache.commons.httpclient.Cookie cookies} should be put on
87      * a single {@link org.apache.commons.httpclient.Header response header}.
88      * <p>
89      * This parameter expects a value of type {@link Boolean}.
90      * </p>
91      */

92     public static final String JavaDoc SINGLE_COOKIE_HEADER = "http.protocol.single-cookie-header";
93
94     /**
95      * Defines whether responses with an invalid <tt>Transfer-Encoding</tt> header should be
96      * rejected.
97      * <p>
98      * This parameter expects a value of type {@link Boolean}.
99      * </p>
100      */

101     public static final String JavaDoc STRICT_TRANSFER_ENCODING = "http.protocol.strict-transfer-encoding";
102
103     /**
104      * Defines whether the content body sent in response to
105      * {@link org.apache.commons.httpclient.methods.HeadMethod} should be rejected.
106      * <p>
107      * This parameter expects a value of type {@link Boolean}.
108      * </p>
109      */

110     public static final String JavaDoc REJECT_HEAD_BODY = "http.protocol.reject-head-body";
111
112     /**
113      * Sets period of time in milliseconds to wait for a content body sent in response to
114      * {@link org.apache.commons.httpclient.methods.HeadMethod HEAD method} from a
115      * non-compliant server. If the parameter is not set or set to <tt>-1</tt> non-compliant
116      * response body check is disabled.
117      * <p>
118      * This parameter expects a value of type {@link Integer}.
119      * </p>
120      */

121     public static final String JavaDoc HEAD_BODY_CHECK_TIMEOUT = "http.protocol.head-body-timeout";
122
123     /**
124      * <p>
125      * Activates 'Expect: 100-Continue' handshake for the
126      * {@link org.apache.commons.httpclient.methods.ExpectContinueMethod
127      * entity enclosing methods}. The purpose of the 'Expect: 100-Continue'
128      * handshake to allow a client that is sending a request message with
129      * a request body to determine if the origin server is willing to
130      * accept the request (based on the request headers) before the client
131      * sends the request body.
132      * </p>
133      *
134      * <p>
135      * The use of the 'Expect: 100-continue' handshake can result in
136      * noticable peformance improvement for entity enclosing requests
137      * (such as POST and PUT) that require the target server's
138      * authentication.
139      * </p>
140      *
141      * <p>
142      * 'Expect: 100-continue' handshake should be used with
143      * caution, as it may cause problems with HTTP servers and
144      * proxies that do not support HTTP/1.1 protocol.
145      * </p>
146      *
147      * This parameter expects a value of type {@link Boolean}.
148      */

149     public static final String JavaDoc USE_EXPECT_CONTINUE = "http.protocol.expect-continue";
150
151     /**
152      * Defines the charset to be used when encoding
153      * {@link org.apache.commons.httpclient.Credentials}. If not defined then the
154      * {@link #HTTP_ELEMENT_CHARSET} should be used.
155      * <p>
156      * This parameter expects a value of type {@link String}.
157      * </p>
158      */

159     public static final String JavaDoc CREDENTIAL_CHARSET = "http.protocol.credential-charset";
160     
161     /**
162      * Defines the charset to be used for encoding HTTP protocol elements.
163      * <p>
164      * This parameter expects a value of type {@link String}.
165      * </p>
166      */

167     public static final String JavaDoc HTTP_ELEMENT_CHARSET = "http.protocol.element-charset";
168     
169     /**
170      * Defines the charset to be used for parsing URIs.
171      * <p>
172      * This parameter expects a value of type {@link String}.
173      * </p>
174      */

175     public static final String JavaDoc HTTP_URI_CHARSET = "http.protocol.uri-charset";
176     
177     /**
178      * Defines the charset to be used for encoding content body.
179      * <p>
180      * This parameter expects a value of type {@link String}.
181      * </p>
182      */

183     public static final String JavaDoc HTTP_CONTENT_CHARSET = "http.protocol.content-charset";
184     
185     /**
186      * Defines {@link CookiePolicy cookie policy} to be used for cookie management.
187      * <p>
188      * This parameter expects a value of type {@link String}.
189      * </p>
190      */

191     public static final String JavaDoc COOKIE_POLICY = "http.protocol.cookie-policy";
192     
193     /**
194      * Defines HttpClient's behavior when a response provides more bytes than
195      * expected (specified with Content-Length, for example).
196      * <p>
197      * Such surplus data makes the HTTP connection unreliable for keep-alive
198      * requests, as malicious response data (faked headers etc.) can lead to undesired
199      * results on the next request using that connection.
200      * </p>
201      * <p>
202      * If this parameter is set to <code>true</code>, any detection of extra
203      * input data will generate a warning in the log.
204      * </p>
205      * <p>
206      * This parameter expects a value of type {@link Boolean}.
207      * </p>
208      */

209     public static final String JavaDoc WARN_EXTRA_INPUT = "http.protocol.warn-extra-input";
210     
211     /**
212      * Defines the maximum number of ignorable lines before we expect
213      * a HTTP response's status code.
214      * <p>
215      * With HTTP/1.1 persistent connections, the problem arises that
216      * broken scripts could return a wrong Content-Length
217      * (there are more bytes sent than specified).<br />
218      * Unfortunately, in some cases, this is not possible after the bad response,
219      * but only before the next one. <br />
220      * So, HttpClient must be able to skip those surplus lines this way.
221      * </p>
222      * <p>
223      * Set this to 0 to disallow any garbage/empty lines before the status line.<br />
224      * To specify no limit, use {@link java.lang.Integer#MAX_VALUE} (default in lenient mode).
225      * </p>
226      *
227      * This parameter expects a value of type {@link Integer}.
228      */

229     public static final String JavaDoc STATUS_LINE_GARBAGE_LIMIT = "http.protocol.status-line-garbage-limit";
230
231     /**
232      * Sets the socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds to be used when executing the method.
233      * A timeout value of zero is interpreted as an infinite timeout.
234      * <p>
235      * This parameter expects a value of type {@link Integer}.
236      * </p>
237      * @see java.net.SocketOptions#SO_TIMEOUT
238      */

239     public static final String JavaDoc SO_TIMEOUT = "http.socket.timeout";
240
241     /**
242      * The key used to look up the date patterns used for parsing. The String patterns are stored
243      * in a {@link java.util.Collection} and must be compatible with
244      * {@link java.text.SimpleDateFormat}.
245      * <p>
246      * This parameter expects a value of type {@link java.util.Collection}.
247      * </p>
248      */

249     public static final String JavaDoc DATE_PATTERNS = "http.dateparser.patterns";
250
251     /**
252      * Sets the method retry handler parameter.
253      * <p>
254      * This parameter expects a value of type {@link org.apache.commons.httpclient.HttpMethodRetryHandler}.
255      * </p>
256      */

257     public static final String JavaDoc RETRY_HANDLER = "http.method.retry-handler";
258     
259     /**
260      * Sets the maximum buffered response size (in bytes) that triggers no warning. Buffered
261      * responses exceeding this size will trigger a warning in the log.
262      * <p>
263      * This parameter expects a value if type {@link Integer}.
264      * </p>
265      */

266     public static final String JavaDoc BUFFER_WARN_TRIGGER_LIMIT = "http.method.response.buffer.warnlimit";
267     
268     /**
269      * Defines the virtual host name.
270      * <p>
271      * This parameter expects a value of type {@link java.lang.String}.
272      * </p>
273      */

274     public static final String JavaDoc VIRTUAL_HOST = "http.virtual-host";
275
276     /**
277      * Sets the value to use as the multipart boundary.
278      * <p>
279      * This parameter expects a value if type {@link String}.
280      * </p>
281      * @see org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity
282      */

283     public static final String JavaDoc MULTIPART_BOUNDARY = "http.method.multipart.boundary";
284     
285     /**
286      * Creates a new collection of parameters with the collection returned
287      * by {@link #getDefaultParams()} as a parent. The collection will defer
288      * to its parent for a default value if a particular parameter is not
289      * explicitly set in the collection itself.
290      *
291      * @see #getDefaultParams()
292      */

293     public HttpMethodParams() {
294         super(getDefaultParams());
295     }
296
297     /**
298      * Creates a new collection of parameters with the given parent.
299      * The collection will defer to its parent for a default value
300      * if a particular parameter is not explicitly set in the collection
301      * itself.
302      *
303      * @param defaults the parent collection to defer to, if a parameter
304      * is not explictly set in the collection itself.
305      *
306      * @see #getDefaultParams()
307      */

308     public HttpMethodParams(HttpParams defaults) {
309         super(defaults);
310     }
311
312     /**
313      * Returns the charset to be used for writing HTTP headers.
314      * @return The charset
315      */

316     public String JavaDoc getHttpElementCharset() {
317         String JavaDoc charset = (String JavaDoc) getParameter(HTTP_ELEMENT_CHARSET);
318         if (charset == null) {
319             LOG.warn("HTTP element charset not configured, using US-ASCII");
320             charset = "US-ASCII";
321         }
322         return charset;
323     }
324     
325     /**
326      * Sets the charset to be used for writing HTTP headers.
327      * @param charset The charset
328      */

329     public void setHttpElementCharset(String JavaDoc charset) {
330         setParameter(HTTP_ELEMENT_CHARSET, charset);
331     }
332
333     /**
334      * Returns the default charset to be used for writing content body,
335      * when no charset explicitly specified.
336      * @return The charset
337      */

338     public String JavaDoc getContentCharset() {
339         String JavaDoc charset = (String JavaDoc) getParameter(HTTP_CONTENT_CHARSET);
340         if (charset == null) {
341             LOG.warn("Default content charset not configured, using ISO-8859-1");
342             charset = "ISO-8859-1";
343         }
344         return charset;
345     }
346     
347     /**
348      * Sets the charset to be used for parsing URIs.
349      * @param charset The charset
350      */

351     public void setUriCharset(String JavaDoc charset) {
352         setParameter(HTTP_URI_CHARSET, charset);
353     }
354
355     /**
356      * Returns the charset to be used for parsing URIs.
357      * @return The charset
358      */

359     public String JavaDoc getUriCharset() {
360         String JavaDoc charset = (String JavaDoc) getParameter(HTTP_URI_CHARSET);
361         if (charset == null) {
362             charset = "UTF-8";
363         }
364         return charset;
365     }
366     
367     /**
368      * Sets the default charset to be used for writing content body,
369      * when no charset explicitly specified.
370      * @param charset The charset
371      */

372     public void setContentCharset(String JavaDoc charset) {
373         setParameter(HTTP_CONTENT_CHARSET, charset);
374     }
375
376     /**
377      * Returns the charset to be used for {@link org.apache.commons.httpclient.Credentials}. If
378      * not configured the {@link #HTTP_ELEMENT_CHARSET HTTP element charset} is used.
379      * @return The charset
380      */

381     public String JavaDoc getCredentialCharset() {
382         String JavaDoc charset = (String JavaDoc) getParameter(CREDENTIAL_CHARSET);
383         if (charset == null) {
384             LOG.debug("Credential charset not configured, using HTTP element charset");
385             charset = getHttpElementCharset();
386         }
387         return charset;
388     }
389     
390     /**
391      * Sets the charset to be used for writing HTTP headers.
392      * @param charset The charset
393      */

394     public void setCredentialCharset(String JavaDoc charset) {
395         setParameter(CREDENTIAL_CHARSET, charset);
396     }
397     
398     /**
399      * Returns {@link HttpVersion HTTP protocol version} to be used by the
400      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that
401      * this collection of parameters applies to.
402      *
403      * @return {@link HttpVersion HTTP protocol version}
404      */

405     public HttpVersion getVersion() {
406         Object JavaDoc param = getParameter(PROTOCOL_VERSION);
407         if (param == null) {
408             return HttpVersion.HTTP_1_1;
409         }
410         return (HttpVersion)param;
411     }
412     
413     /**
414      * Assigns the {@link HttpVersion HTTP protocol version} to be used by the
415      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that
416      * this collection of parameters applies to.
417      *
418      * @param version the {@link HttpVersion HTTP protocol version}
419      */

420     public void setVersion(HttpVersion version) {
421         setParameter(PROTOCOL_VERSION, version);
422     }
423
424
425     /**
426      * Returns {@link CookiePolicy cookie policy} to be used by the
427      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
428      * this collection of parameters applies to.
429      *
430      * @return {@link CookiePolicy cookie policy}
431      */

432     public String JavaDoc getCookiePolicy() {
433         Object JavaDoc param = getParameter(COOKIE_POLICY);
434         if (param == null) {
435             return CookiePolicy.DEFAULT;
436         }
437         return (String JavaDoc)param;
438     }
439     
440     /**
441      * Assigns the {@link CookiePolicy cookie policy} to be used by the
442      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
443      * this collection of parameters applies to.
444      *
445      * @param policy the {@link CookiePolicy cookie policy}
446      */

447     public void setCookiePolicy(String JavaDoc policy) {
448         setParameter(COOKIE_POLICY, policy);
449     }
450
451     /**
452      * Returns the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
453      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
454      * timeout.
455      *
456      * @return timeout in milliseconds
457      */

458     public int getSoTimeout() {
459         return getIntParameter(SO_TIMEOUT, 0);
460     }
461
462     /**
463      * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
464      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
465      * timeout.
466      *
467      * @param timeout Timeout in milliseconds
468      */

469     public void setSoTimeout(int timeout) {
470         setIntParameter(SO_TIMEOUT, timeout);
471     }
472
473     /**
474      * Sets the virtual host name.
475      *
476      * @param hostname The host name
477      */

478     public void setVirtualHost(final String JavaDoc hostname) {
479         setParameter(VIRTUAL_HOST, hostname);
480     }
481
482     /**
483      * Returns the virtual host name.
484      *
485      * @return The virtual host name
486      */

487     public String JavaDoc getVirtualHost() {
488         return (String JavaDoc) getParameter(VIRTUAL_HOST);
489     }
490     
491     private static final String JavaDoc[] PROTOCOL_STRICTNESS_PARAMETERS = {
492         UNAMBIGUOUS_STATUS_LINE,
493         SINGLE_COOKIE_HEADER,
494         STRICT_TRANSFER_ENCODING,
495         REJECT_HEAD_BODY,
496         WARN_EXTRA_INPUT
497     };
498     
499     /**
500      * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
501      * strictly follow the HTTP protocol specification (RFC 2616 and other relevant RFCs).
502      * It must be noted that popular HTTP agents have different degree of HTTP protocol
503      * compliance and some HTTP serves are programmed to expect the behaviour that does not
504      * strictly adhere to the HTTP specification.
505      */

506     public void makeStrict() {
507         setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.TRUE);
508         setIntParameter(STATUS_LINE_GARBAGE_LIMIT, 0);
509     }
510
511     /**
512      * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
513      * attempt to mimic the exact behaviour of commonly used HTTP agents,
514      * which many HTTP servers expect, even though such behaviour may violate
515      * the HTTP protocol specification (RFC 2616 and other relevant RFCs).
516      */

517     public void makeLenient() {
518         setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.FALSE);
519         setIntParameter(STATUS_LINE_GARBAGE_LIMIT, Integer.MAX_VALUE);
520     }
521
522 }
523
Popular Tags