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 12:34:50 +0100 (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 */ HttpMethodParams()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 */ HttpMethodParams(HttpParams defaults)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 */ getHttpElementCharset()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 */ setHttpElementCharset(String charset)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 */ getContentCharset()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 */ setUriCharset(String charset)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 */ getUriCharset()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 */ setContentCharset(String charset)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 */ getCredentialCharset()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 */ setCredentialCharset(String charset)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 */ getVersion()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 */ setVersion(HttpVersion version)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 */ getCookiePolicy()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 */ setCookiePolicy(String policy)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 */ getSoTimeout()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 */ setSoTimeout(int timeout)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 */ setVirtualHost(final String hostname)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 */ getVirtualHost()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 */ makeStrict()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 */ makeLenient()517 public void makeLenient() { 518 setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.FALSE); 519 setIntParameter(STATUS_LINE_GARBAGE_LIMIT, Integer.MAX_VALUE); 520 } 521 522 } 523