View Javadoc

1   /*
2    * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/params/HttpMethodParams.java,v 1.13 2004/05/13 04:01:22 mbecke Exp $
3    * $Revision: 1.13 $
4    * $Date: 2004/05/13 04:01:22 $
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.HttpVersion;
33  import org.apache.commons.httpclient.cookie.CookiePolicy;
34  import org.apache.commons.logging.Log;
35  import org.apache.commons.logging.LogFactory;
36  
37  /***
38   * This class represents a collection of HTTP protocol parameters applicable to 
39   * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}. Protocol 
40   * parameters may be linked together to form a hierarchy. If a particular 
41   * parameter value has not been explicitly defined in the collection itself, 
42   * its value will be drawn from the parent collection of parameters.
43   * 
44   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
45   * @author Christian Kohlschuetter
46   * 
47   * @version $Revision: 1.13 $
48   * 
49   * @since 3.0
50   */
51  public class HttpMethodParams extends DefaultHttpParams {
52  
53      /*** Log object for this class. */
54      private static final Log LOG = LogFactory.getLog(HttpMethodParams.class);
55  
56      /***
57       * Defines the content of the <tt>User-Agent</tt> header used by  
58       * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}.
59       * <p>
60       * This parameter expects a value of type {@link String}.
61       * </p>
62       */
63      public static final String USER_AGENT = "http.useragent"; 
64  
65      /***
66       * Defines the {@link HttpVersion HTTP protocol version} used by  
67       * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} per
68       * default.
69       * <p>
70       * This parameter expects a value of type {@link HttpVersion}.
71       * </p>
72       */
73      public static final String PROTOCOL_VERSION = "http.protocol.version"; 
74  
75      /***
76       * Defines whether {@link org.apache.commons.httpclient.HttpMethod HTTP methods} should
77       * reject ambiguous {@link org.apache.commons.httpclient.StatusLine HTTP status line}.
78       * <p>
79       * This parameter expects a value of type {@link Boolean}.
80       * </p>
81       */
82      public static final String UNAMBIGUOUS_STATUS_LINE = "http.protocol.unambiguous-statusline"; 
83  
84      /***
85       * Defines whether {@link org.apache.commons.httpclient.Cookie cookies} should be put on 
86       * a single {@link org.apache.commons.httpclient.Header response header}.
87       * <p>
88       * This parameter expects a value of type {@link Boolean}.
89       * </p>
90       */
91      public static final String SINGLE_COOKIE_HEADER = "http.protocol.single-cookie-header"; 
92  
93      /***
94       * Defines whether responses with an invalid <tt>Transfer-Encoding</tt> header should be 
95       * rejected.
96       * <p>
97       * This parameter expects a value of type {@link Boolean}.
98       * </p>
99       */
100     public static final String STRICT_TRANSFER_ENCODING = "http.protocol.strict-transfer-encoding"; 
101 
102     /***
103      * Defines whether the content body sent in response to 
104      * {@link org.apache.commons.httpclient.methods.HeadMethod} should be rejected.
105      * <p>
106      * This parameter expects a value of type {@link Boolean}.
107      * </p>
108      */
109     public static final String REJECT_HEAD_BODY = "http.protocol.reject-head-body"; 
110 
111     /***
112      * Sets period of time in milliseconds to wait for a content body sent in response to 
113      * {@link org.apache.commons.httpclient.methods.HeadMethod HEAD method} from a 
114      * non-compliant server. If the parameter is not set or set to <tt>-1</tt> non-compliant 
115      * response body check is disabled.
116      * <p>
117      * This parameter expects a value of type {@link Integer}.
118      * </p>
119      */
120     public static final String HEAD_BODY_CHECK_TIMEOUT = "http.protocol.head-body-timeout"; 
121 
122     /***
123      * <p>
124      * Activates 'Expect: 100-Continue' handshake for the 
125      * {@link org.apache.commons.httpclient.methods.ExpectContinueMethod 
126      * entity enclosing methods}. The purpose of the 'Expect: 100-Continue'
127      * handshake to allow a client that is sending a request message with 
128      * a request body to determine if the origin server is willing to 
129      * accept the request (based on the request headers) before the client
130      * sends the request body.
131      * </p>
132      * 
133      * <p>
134      * The use of the 'Expect: 100-continue' handshake can result in 
135      * noticable peformance improvement for entity enclosing requests
136      * (such as POST and PUT) that require the target server's 
137      * authentication.
138      * </p>
139      * 
140      * <p>
141      * 'Expect: 100-continue' handshake should be used with 
142      * caution, as it may cause problems with HTTP servers and 
143      * proxies that do not support HTTP/1.1 protocol.
144      * </p>
145      * 
146      * This parameter expects a value of type {@link Boolean}.
147      */
148     public static final String USE_EXPECT_CONTINUE = "http.protocol.expect-continue"; 
149 
150     /***
151      * Defines the charset to be used when encoding 
152      * {@link org.apache.commons.httpclient.Credentials}. If not defined then the 
153      * {@link #HTTP_ELEMENT_CHARSET} should be used.
154      * <p>
155      * This parameter expects a value of type {@link String}.
156      * </p>
157      */
158     public static final String CREDENTIAL_CHARSET = "http.protocol.credential-charset"; 
159     
160     /***
161      * Defines the charset to be used for encoding HTTP protocol elements.
162      * <p>
163      * This parameter expects a value of type {@link String}.
164      * </p>
165      */
166     public static final String HTTP_ELEMENT_CHARSET = "http.protocol.element-charset"; 
167     
168     /***
169      * Defines the charset to be used for encoding content body.
170      * <p>
171      * This parameter expects a value of type {@link String}.
172      * </p>
173      */
174     public static final String HTTP_CONTENT_CHARSET = "http.protocol.content-charset"; 
175     
176     /***
177      * Defines {@link CookiePolicy cookie policy} to be used for cookie management.
178      * <p>
179      * This parameter expects a value of type {@link String}.
180      * </p>
181      */
182     public static final String COOKIE_POLICY = "http.protocol.cookie-policy";
183     
184     /***
185      * Defines HttpClient's behavior when a response provides more bytes than
186      * expected (specified with Content-Length, for example).
187      * <p>
188      * Such surplus data makes the HTTP connection unreliable for keep-alive
189      * requests, as malicious response data (faked headers etc.) can lead to undesired
190      * results on the next request using that connection.
191      * </p>
192      * <p>
193      * If this parameter is set to <code>true</code>, any detection of extra
194      * input data will generate a warning in the log.
195      * </p>
196      * <p>
197      * This parameter expects a value of type {@link Boolean}.
198      * </p>
199      */
200     public static final String WARN_EXTRA_INPUT = "http.protocol.warn-extra-input";
201     
202     /***
203      * Defines the maximum number of ignorable lines before we expect
204      * a HTTP response's status code.
205      * <p>
206      * With HTTP/1.1 persistent connections, the problem arises that
207      * broken scripts could return a wrong Content-Length
208      * (there are more bytes sent than specified).<br />
209      * Unfortunately, in some cases, this is not possible after the bad response,
210      * but only before the next one. <br />
211      * So, HttpClient must be able to skip those surplus lines this way.
212      * </p>
213      * <p>
214      * Set this to 0 to disallow any garbage/empty lines before the status line.<br />
215      * To specify no limit, use {@link java.lang.Integer#MAX_VALUE} (default in lenient mode).
216      * </p>
217      *  
218      * This parameter expects a value of type {@link Integer}.
219      */
220     public static final String STATUS_LINE_GARBAGE_LIMIT = "http.protocol.status-line-garbage-limit";
221 
222     /***
223      * Sets the socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds to be used when executing the method. 
224      * A timeout value of zero is interpreted as an infinite timeout.
225      * <p>
226      * This parameter expects a value of type {@link Integer}.
227      * </p>
228      * @see java.net.SocketOptions#SO_TIMEOUT
229      */
230     public static final String SO_TIMEOUT = "http.socket.timeout"; 
231 
232     /***
233      * Creates a new collection of parameters with the collection returned
234      * by {@link #getDefaultParams()} as a parent. The collection will defer
235      * to its parent for a default value if a particular parameter is not 
236      * explicitly set in the collection itself.
237      * 
238      * @see #getDefaultParams()
239      */
240     public HttpMethodParams() {
241         super(getDefaultParams());
242     }
243 
244     /***
245      * Creates a new collection of parameters with the given parent. 
246      * The collection will defer to its parent for a default value 
247      * if a particular parameter is not explicitly set in the collection
248      * itself.
249      * 
250      * @param defaults the parent collection to defer to, if a parameter
251      * is not explictly set in the collection itself.
252      *
253      * @see #getDefaultParams()
254      */
255     public HttpMethodParams(HttpParams defaults) {
256         super(defaults);
257     }
258 
259     /***
260      * Returns the charset to be used for writing HTTP headers.
261      * @return The charset
262      */
263     public String getHttpElementCharset() {
264         String charset = (String) getParameter(HTTP_ELEMENT_CHARSET);
265         if (charset == null) {
266             LOG.warn("HTTP element charset not configured, using US-ASCII");
267             charset = "US-ASCII";
268         }
269         return charset;
270     }
271     
272     /***
273      * Sets the charset to be used for writing HTTP headers.
274      * @param charset The charset
275      */
276     public void setHttpElementCharset(String charset) {
277         setParameter(HTTP_ELEMENT_CHARSET, charset);
278     }
279 
280     /***
281      * Returns the default charset to be used for writing content body, 
282      * when no charset explicitly specified.
283      * @return The charset
284      */
285     public String getContentCharset() {
286         String charset = (String) getParameter(HTTP_CONTENT_CHARSET);
287         if (charset == null) {
288             LOG.warn("Default content charset not configured, using ISO-8859-1");
289             charset = "ISO-8859-1";
290         }
291         return charset;
292     }
293     
294     /***
295      * Sets the default charset to be used for writing content body,
296      * when no charset explicitly specified.
297      * @param charset The charset
298      */
299     public void setContentCharset(String charset) {
300         setParameter(HTTP_CONTENT_CHARSET, charset);
301     }
302 
303     /***
304      * Returns the charset to be used for {@link org.apache.commons.httpclient.Credentials}. If
305      * not configured the {@link #HTTP_ELEMENT_CHARSET HTTP element charset} is used.
306      * @return The charset
307      */
308     public String getCredentialCharset() {
309         String charset = (String) getParameter(CREDENTIAL_CHARSET);
310         if (charset == null) {
311             LOG.debug("Credential charset not configured, using HTTP element charset");
312             charset = getHttpElementCharset();
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 setCredentialCharset(String charset) {
322         setParameter(CREDENTIAL_CHARSET, charset);
323     }
324     
325     /***
326      * Returns {@link HttpVersion HTTP protocol version} to be used by the 
327      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that 
328      * this collection of parameters applies to. 
329      *
330      * @return {@link HttpVersion HTTP protocol version}
331      */
332     public HttpVersion getVersion() { 
333         Object param = getParameter(PROTOCOL_VERSION);
334         if (param == null) {
335             return HttpVersion.HTTP_1_1;
336         }
337         return (HttpVersion)param;
338     }
339     
340     /***
341      * Assigns the {@link HttpVersion HTTP protocol version} to be used by the 
342      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that 
343      * this collection of parameters applies to. 
344      *
345      * @param version the {@link HttpVersion HTTP protocol version}
346      */
347     public void setVersion(HttpVersion version) {
348         setParameter(PROTOCOL_VERSION, version);
349     }
350 
351 
352     /***
353      * Returns {@link CookiePolicy cookie policy} to be used by the 
354      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
355      * this collection of parameters applies to. 
356      *
357      * @return {@link CookiePolicy cookie policy}
358      */
359     public String getCookiePolicy() { 
360         Object param = getParameter(COOKIE_POLICY);
361         if (param == null) {
362             return CookiePolicy.DEFAULT;
363         }
364         return (String)param;
365     }
366     
367     /***
368      * Assigns the {@link CookiePolicy cookie policy} to be used by the 
369      * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
370      * this collection of parameters applies to. 
371      *
372      * @param policy the {@link CookiePolicy cookie policy}
373      */
374     public void setCookiePolicy(String policy) {
375         setParameter(COOKIE_POLICY, policy);
376     }
377 
378     /***
379      * Returns the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
380      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
381      * timeout.  
382      *
383      * @return timeout in milliseconds
384      */
385     public int getSoTimeout() {
386         return getIntParameter(SO_TIMEOUT, 0);
387     }
388 
389     /***
390      * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
391      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
392      * timeout.  
393      *
394      * @param timeout Timeout in milliseconds
395      */
396     public void setSoTimeout(int timeout) {
397         setIntParameter(SO_TIMEOUT, timeout);
398     }
399 
400     private static final String[] PROTOCOL_STRICTNESS_PARAMETERS = {
401         UNAMBIGUOUS_STATUS_LINE,
402         SINGLE_COOKIE_HEADER,
403         STRICT_TRANSFER_ENCODING,
404         REJECT_HEAD_BODY,
405         WARN_EXTRA_INPUT
406     };
407     
408     /***
409      * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
410      * strictly follow the HTTP protocol specification (RFC 2616 and other relevant RFCs).
411      * It must be noted that popular HTTP agents have different degree of HTTP protocol 
412      * compliance and some HTTP serves are programmed to expect the behaviour that does not 
413      * strictly adhere to the HTTP specification.  
414      */
415     public void makeStrict() {
416         setParameters(PROTOCOL_STRICTNESS_PARAMETERS, new Boolean(true));
417         setIntParameter(STATUS_LINE_GARBAGE_LIMIT, 0);
418     }
419 
420     /***
421      * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
422      * attempt to mimic the exact behaviour of commonly used HTTP agents, 
423      * which many HTTP servers expect, even though such behaviour may violate   
424      * the HTTP protocol specification (RFC 2616 and other relevant RFCs).
425      */
426     public void makeLenient() {
427         setParameters(PROTOCOL_STRICTNESS_PARAMETERS, new Boolean(false));
428         setIntParameter(STATUS_LINE_GARBAGE_LIMIT, Integer.MAX_VALUE);
429     }
430 
431 }