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   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 parsing URIs.
171      * <p>
172      * This parameter expects a value of type {@link String}.
173      * </p>
174      */
175     public static final String   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   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   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   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   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   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   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   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   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   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   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   getHttpElementCharset() {
317         String   charset = (String  ) 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   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   getContentCharset() {
339         String   charset = (String  ) 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   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   getUriCharset() {
360         String   charset = (String  ) 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   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   getCredentialCharset() {
382         String   charset = (String  ) 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   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   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   getCookiePolicy() { 
433         Object   param = getParameter(COOKIE_POLICY);
434         if (param == null) {
435             return CookiePolicy.DEFAULT;
436         }
437         return (String  )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   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   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   getVirtualHost() {
488         return (String  ) getParameter(VIRTUAL_HOST);
489     }
490     
491     private static final String  [] 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags