HttpMethodParams xref

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: 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      */
    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 }