View Javadoc

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: 155418 $
4    * $Date: 2005-02-26 08:01:52 -0500 (Sat, 26 Feb 2005) $
5    *
6    * ====================================================================
7    *
8    *  Copyright 1999-2004 The Apache Software Foundation
9    *
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
13   *
14   *      http://www.apache.org/licenses/LICENSE-2.0
15   *
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   * ====================================================================
22   *
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/>.
27   *
28   */
29  
30  package org.apache.commons.httpclient.params;
31  
32  import org.apache.commons.httpclient.HttpMethodRetryHandler;
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: 155418 $
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 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 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 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 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 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 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 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 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 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 HTTP_ELEMENT_CHARSET = "http.protocol.element-charset"; 
168     
169     /***
170      * Defines the charset to be used for encoding content body.
171      * <p>
172      * This parameter expects a value of type {@link String}.
173      * </p>
174      */
175     public static final String HTTP_CONTENT_CHARSET = "http.protocol.content-charset"; 
176     
177     /***
178      * Defines {@link CookiePolicy cookie policy} to be used for cookie management.
179      * <p>
180      * This parameter expects a value of type {@link String}.
181      * </p>
182      */
183     public static final String COOKIE_POLICY = "http.protocol.cookie-policy";
184     
185     /***
186      * Defines HttpClient's behavior when a response provides more bytes than
187      * expected (specified with Content-Length, for example).
188      * <p>
189      * Such surplus data makes the HTTP connection unreliable for keep-alive
190      * requests, as malicious response data (faked headers etc.) can lead to undesired
191      * results on the next request using that connection.
192      * </p>
193      * <p>
194      * If this parameter is set to <code>true</code>, any detection of extra
195      * input data will generate a warning in the log.
196      * </p>
197      * <p>
198      * This parameter expects a value of type {@link Boolean}.
199      * </p>
200      */
201     public static final String WARN_EXTRA_INPUT = "http.protocol.warn-extra-input";
202     
203     /***
204      * Defines the maximum number of ignorable lines before we expect
205      * a HTTP response's status code.
206      * <p>
207      * With HTTP/1.1 persistent connections, the problem arises that
208      * broken scripts could return a wrong Content-Length
209      * (there are more bytes sent than specified).<br />
210      * Unfortunately, in some cases, this is not possible after the bad response,
211      * but only before the next one. <br />
212      * So, HttpClient must be able to skip those surplus lines this way.
213      * </p>
214      * <p>
215      * Set this to 0 to disallow any garbage/empty lines before the status line.<br />
216      * To specify no limit, use {@link java.lang.Integer#MAX_VALUE} (default in lenient mode).
217      * </p>
218      *  
219      * This parameter expects a value of type {@link Integer}.
220      */
221     public static final String STATUS_LINE_GARBAGE_LIMIT = "http.protocol.status-line-garbage-limit";
222 
223     /***
224      * Sets the socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds to be used when executing the method. 
225      * A timeout value of zero is interpreted as an infinite timeout.
226      * <p>
227      * This parameter expects a value of type {@link Integer}.
228      * </p>
229      * @see java.net.SocketOptions#SO_TIMEOUT
230      */
231     public static final String SO_TIMEOUT = "http.socket.timeout"; 
232 
233     /***
234      * The key used to look up the date patterns used for parsing. The String patterns are stored
235      * in a {@link java.util.Collection} and must be compatible with 
236      * {@link java.text.SimpleDateFormat}.
237      * <p>
238      * This parameter expects a value of type {@link java.util.Collection}.
239      * </p>
240      */
241     public static final String DATE_PATTERNS = "http.dateparser.patterns";
242 
243     /***
244      * Sets the method retry handler parameter.
245      * <p>
246      * This parameter expects a value of type {@link HttpMethodRetryHandler}.
247      * </p>
248      */ 
249     public static final String RETRY_HANDLER = "http.method.retry-handler";
250     
251     /***
252      * Sets the maximum buffered response size (in bytes) that triggers no warning. Buffered
253      * responses exceeding this size will trigger a warning in the log.
254      * <p>
255      * This parameter expects a value if type {@link Integer}.
256      * </p>
257      */
258     public static final String BUFFER_WARN_TRIGGER_LIMIT = "http.method.response.buffer.warnlimit";
259     
260     /***
261      * Defines the virtual host name.
262      * <p>
263      * This parameter expects a value of type {@link java.lang.String}. 
264      * </p>
265      */
266     public static final String VIRTUAL_HOST = "http.virtual-host"; 
267 
268     /***
269      * Sets the value to use as the multipart boundary.
270      * <p>
271      * This parameter expects a value if type {@link String}.
272      * </p>
273      * @see org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity
274      */
275     public static final String MULTIPART_BOUNDARY = "http.method.multipart.boundary";
276     
277     /***
278      * Creates a new collection of parameters with the collection returned
279      * by {@link #getDefaultParams()} as a parent. The collection will defer
280      * to its parent for a default value if a particular parameter is not 
281      * explicitly set in the collection itself.
282      * 
283      * @see #getDefaultParams()
284      */
285     public HttpMethodParams() {
286         super(getDefaultParams());
287     }
288 
289     /***
290      * Creates a new collection of parameters with the given parent. 
291      * The collection will defer to its parent for a default value 
292      * if a particular parameter is not explicitly set in the collection
293      * itself.
294      * 
295      * @param defaults the parent collection to defer to, if a parameter
296      * is not explictly set in the collection itself.
297      *
298      * @see #getDefaultParams()
299      */
300     public HttpMethodParams(HttpParams defaults) {
301         super(defaults);
302     }
303 
304     /***
305      * Returns the charset to be used for writing HTTP headers.
306      * @return The charset
307      */
308     public String getHttpElementCharset() {
309         String charset = (String) getParameter(HTTP_ELEMENT_CHARSET);
310         if (charset == null) {
311             LOG.warn("HTTP element charset not configured, using US-ASCII");
312             charset = "US-ASCII";
313         }
314         return charset;
315     }
316     
317     /***
318      * Sets the charset to be used for writing HTTP headers.
319      * @param charset The charset
320      */
321     public void setHttpElementCharset(String charset) {
322         setParameter(HTTP_ELEMENT_CHARSET, charset);
323     }
324 
325     /***
326      * Returns the default charset to be used for writing content body, 
327      * when no charset explicitly specified.
328      * @return The charset
329      */
330     public String getContentCharset() {
331         String charset = (String) getParameter(HTTP_CONTENT_CHARSET);
332         if (charset == null) {
333             LOG.warn("Default content charset not configured, using ISO-8859-1");
334             charset = "ISO-8859-1";
335         }
336         return charset;
337     }
338     
339     /***
340      * Sets the default charset to be used for writing content body,
341      * when no charset explicitly specified.
342      * @param charset The charset
343      */
344     public void setContentCharset(String charset) {
345         setParameter(HTTP_CONTENT_CHARSET, charset);
346     }
347 
348     /***
349      * Returns the charset to be used for {@link org.apache.commons.httpclient.Credentials}. If
350      * not configured the {@link #HTTP_ELEMENT_CHARSET HTTP element charset} is used.
351      * @return The charset
352      */
353     public String getCredentialCharset() {
354         String charset = (String) getParameter(CREDENTIAL_CHARSET);
355         if (charset == null) {
356             LOG.debug("Credential charset not configured, using HTTP element charset");
357             charset = getHttpElementCharset();
358         }
359         return charset;
360     }
361     
362     /***
363      * Sets the charset to be used for writing HTTP headers.
364      * @param charset The charset
365      */
366     public void setCredentialCharset(String charset) {
367         setParameter(CREDENTIAL_CHARSET, charset);
368     }
369     
370     /***
371      * Returns {@link HttpVersion HTTP protocol version} to be used by the 
372      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that 
373      * this collection of parameters applies to. 
374      *
375      * @return {@link HttpVersion HTTP protocol version}
376      */
377     public HttpVersion getVersion() { 
378         Object param = getParameter(PROTOCOL_VERSION);
379         if (param == null) {
380             return HttpVersion.HTTP_1_1;
381         }
382         return (HttpVersion)param;
383     }
384     
385     /***
386      * Assigns the {@link HttpVersion HTTP protocol version} to be used by the 
387      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that 
388      * this collection of parameters applies to. 
389      *
390      * @param version the {@link HttpVersion HTTP protocol version}
391      */
392     public void setVersion(HttpVersion version) {
393         setParameter(PROTOCOL_VERSION, version);
394     }
395 
396 
397     /***
398      * Returns {@link CookiePolicy cookie policy} to be used by the 
399      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
400      * this collection of parameters applies to. 
401      *
402      * @return {@link CookiePolicy cookie policy}
403      */
404     public String getCookiePolicy() { 
405         Object param = getParameter(COOKIE_POLICY);
406         if (param == null) {
407             return CookiePolicy.DEFAULT;
408         }
409         return (String)param;
410     }
411     
412     /***
413      * Assigns the {@link CookiePolicy cookie policy} to be used by the 
414      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
415      * this collection of parameters applies to. 
416      *
417      * @param policy the {@link CookiePolicy cookie policy}
418      */
419     public void setCookiePolicy(String policy) {
420         setParameter(COOKIE_POLICY, policy);
421     }
422 
423     /***
424      * Returns the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
425      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
426      * timeout.  
427      *
428      * @return timeout in milliseconds
429      */
430     public int getSoTimeout() {
431         return getIntParameter(SO_TIMEOUT, 0);
432     }
433 
434     /***
435      * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
436      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
437      * timeout.  
438      *
439      * @param timeout Timeout in milliseconds
440      */
441     public void setSoTimeout(int timeout) {
442         setIntParameter(SO_TIMEOUT, timeout);
443     }
444 
445     /***
446      * Sets the virtual host name.
447      * 
448      * @param hostname The host name
449      */
450     public void setVirtualHost(final String hostname) {
451         setParameter(VIRTUAL_HOST, hostname);
452     }
453 
454     /***
455      * Returns the virtual host name.
456      * 
457      * @return The virtual host name
458      */
459     public String getVirtualHost() {
460         return (String) getParameter(VIRTUAL_HOST);
461     }
462     
463     private static final String[] PROTOCOL_STRICTNESS_PARAMETERS = {
464         UNAMBIGUOUS_STATUS_LINE,
465         SINGLE_COOKIE_HEADER,
466         STRICT_TRANSFER_ENCODING,
467         REJECT_HEAD_BODY,
468         WARN_EXTRA_INPUT
469     };
470     
471     /***
472      * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
473      * strictly follow the HTTP protocol specification (RFC 2616 and other relevant RFCs).
474      * It must be noted that popular HTTP agents have different degree of HTTP protocol 
475      * compliance and some HTTP serves are programmed to expect the behaviour that does not 
476      * strictly adhere to the HTTP specification.  
477      */
478     public void makeStrict() {
479         setParameters(PROTOCOL_STRICTNESS_PARAMETERS, new Boolean(true));
480         setIntParameter(STATUS_LINE_GARBAGE_LIMIT, 0);
481     }
482 
483     /***
484      * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
485      * attempt to mimic the exact behaviour of commonly used HTTP agents, 
486      * which many HTTP servers expect, even though such behaviour may violate   
487      * the HTTP protocol specification (RFC 2616 and other relevant RFCs).
488      */
489     public void makeLenient() {
490         setParameters(PROTOCOL_STRICTNESS_PARAMETERS, new Boolean(false));
491         setIntParameter(STATUS_LINE_GARBAGE_LIMIT, Integer.MAX_VALUE);
492     }
493 
494 }