/*
 * $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 $
 * $Revision: 483949 $
 * $Date: 2006-12-08 12:34:50 +0100 (Fri, 08 Dec 2006) $
 *
 * ====================================================================
 *
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */

package org.apache.commons.httpclient.params;

import org.apache.commons.httpclient.HttpVersion;
import org.apache.commons.httpclient.cookie.CookiePolicy;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

This class represents a collection of HTTP protocol parameters applicable to HTTP methods. Protocol parameters may be linked together to form a hierarchy. If a particular parameter value has not been explicitly defined in the collection itself, its value will be drawn from the parent collection of parameters. 
Author:
Oleg Kalnichevski, Christian Kohlschuetter
Version:
$Revision: 483949 $
Since:
3.0/**
 * This class represents a collection of HTTP protocol parameters applicable to 
 * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}. Protocol 
 * parameters may be linked together to form a hierarchy. If a particular 
 * parameter value has not been explicitly defined in the collection itself, 
 * its value will be drawn from the parent collection of parameters.
 * 
 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
 * @author Christian Kohlschuetter
 * 
 * @version $Revision: 483949 $
 * 
 * @since 3.0
 */
public class HttpMethodParams extends DefaultHttpParams {

    
Log object for this class. /** Log object for this class. */
    private static final Log LOG = LogFactory.getLog(HttpMethodParams.class);

    
Defines the content of the User-Agent header used by HTTP methods. 
 This parameter expects a value of type String. 
/**
     * Defines the content of the <tt>User-Agent</tt> header used by  
     * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}.
     * <p>
     * This parameter expects a value of type {@link String}.
     * </p>
     */
    public static final String USER_AGENT = "http.useragent"; 

    
Defines the HTTP protocol version used by HTTP methods per default. 
 This parameter expects a value of type HttpVersion. 
/**
     * Defines the {@link HttpVersion HTTP protocol version} used by  
     * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} per
     * default.
     * <p>
     * This parameter expects a value of type {@link HttpVersion}.
     * </p>
     */
    public static final String PROTOCOL_VERSION = "http.protocol.version"; 

    
Defines whether HTTP methods should reject ambiguous HTTP status line. 
 This parameter expects a value of type Boolean. 
/**
     * Defines whether {@link org.apache.commons.httpclient.HttpMethod HTTP methods} should
     * reject ambiguous {@link org.apache.commons.httpclient.StatusLine HTTP status line}.
     * <p>
     * This parameter expects a value of type {@link Boolean}.
     * </p>
     */
    public static final String UNAMBIGUOUS_STATUS_LINE = "http.protocol.unambiguous-statusline"; 

    
Defines whether cookies should be put on a single response header. 
 This parameter expects a value of type Boolean. 
/**
     * Defines whether {@link org.apache.commons.httpclient.Cookie cookies} should be put on 
     * a single {@link org.apache.commons.httpclient.Header response header}.
     * <p>
     * This parameter expects a value of type {@link Boolean}.
     * </p>
     */
    public static final String SINGLE_COOKIE_HEADER = "http.protocol.single-cookie-header"; 

    
Defines whether responses with an invalid Transfer-Encoding header should be 
rejected.
 This parameter expects a value of type Boolean. 
/**
     * Defines whether responses with an invalid <tt>Transfer-Encoding</tt> header should be 
     * rejected.
     * <p>
     * This parameter expects a value of type {@link Boolean}.
     * </p>
     */
    public static final String STRICT_TRANSFER_ENCODING = "http.protocol.strict-transfer-encoding"; 

    
Defines whether the content body sent in response to HeadMethod should be rejected. 
 This parameter expects a value of type Boolean. 
/**
     * Defines whether the content body sent in response to 
     * {@link org.apache.commons.httpclient.methods.HeadMethod} should be rejected.
     * <p>
     * This parameter expects a value of type {@link Boolean}.
     * </p>
     */
    public static final String REJECT_HEAD_BODY = "http.protocol.reject-head-body"; 

    
Sets period of time in milliseconds to wait for a content body sent in response to HEAD method from a non-compliant server. If the parameter is not set or set to -1 non-compliant 
response body check is disabled.
 This parameter expects a value of type Integer. 
/**
     * Sets period of time in milliseconds to wait for a content body sent in response to 
     * {@link org.apache.commons.httpclient.methods.HeadMethod HEAD method} from a 
     * non-compliant server. If the parameter is not set or set to <tt>-1</tt> non-compliant 
     * response body check is disabled.
     * <p>
     * This parameter expects a value of type {@link Integer}.
     * </p>
     */
    public static final String HEAD_BODY_CHECK_TIMEOUT = "http.protocol.head-body-timeout"; 

    
 Activates 'Expect: 100-Continue' handshake for the 
entity enclosing methods. The purpose of the 'Expect: 100-Continue' handshake to allow a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body. 

The use of the 'Expect: 100-continue' handshake can result in 
noticable peformance improvement for entity enclosing requests
(such as POST and PUT) that require the target server's 
authentication.


'Expect: 100-continue' handshake should be used with 
caution, as it may cause problems with HTTP servers and 
proxies that do not support HTTP/1.1 protocol.
 This parameter expects a value of type Boolean. /**
     * <p>
     * Activates 'Expect: 100-Continue' handshake for the 
     * {@link org.apache.commons.httpclient.methods.ExpectContinueMethod 
     * entity enclosing methods}. The purpose of the 'Expect: 100-Continue'
     * handshake to allow a client that is sending a request message with 
     * a request body to determine if the origin server is willing to 
     * accept the request (based on the request headers) before the client
     * sends the request body.
     * </p>
     * 
     * <p>
     * The use of the 'Expect: 100-continue' handshake can result in 
     * noticable peformance improvement for entity enclosing requests
     * (such as POST and PUT) that require the target server's 
     * authentication.
     * </p>
     * 
     * <p>
     * 'Expect: 100-continue' handshake should be used with 
     * caution, as it may cause problems with HTTP servers and 
     * proxies that do not support HTTP/1.1 protocol.
     * </p>
     * 
     * This parameter expects a value of type {@link Boolean}.
     */
    public static final String USE_EXPECT_CONTINUE = "http.protocol.expect-continue"; 

    
Defines the charset to be used when encoding Credentials. If not defined then the HTTP_ELEMENT_CHARSET should be used. 
 This parameter expects a value of type String. 
/**
     * Defines the charset to be used when encoding 
     * {@link org.apache.commons.httpclient.Credentials}. If not defined then the 
     * {@link #HTTP_ELEMENT_CHARSET} should be used.
     * <p>
     * This parameter expects a value of type {@link String}.
     * </p>
     */
    public static final String CREDENTIAL_CHARSET = "http.protocol.credential-charset"; 
    
    
Defines the charset to be used for encoding HTTP protocol elements.
 This parameter expects a value of type String. 
/**
     * Defines the charset to be used for encoding HTTP protocol elements.
     * <p>
     * This parameter expects a value of type {@link String}.
     * </p>
     */
    public static final String HTTP_ELEMENT_CHARSET = "http.protocol.element-charset"; 
    
    
Defines the charset to be used for parsing URIs.
 This parameter expects a value of type String. 
/**
     * Defines the charset to be used for parsing URIs.
     * <p>
     * This parameter expects a value of type {@link String}.
     * </p>
     */
    public static final String HTTP_URI_CHARSET = "http.protocol.uri-charset"; 
    
    
Defines the charset to be used for encoding content body.
 This parameter expects a value of type String. 
/**
     * Defines the charset to be used for encoding content body.
     * <p>
     * This parameter expects a value of type {@link String}.
     * </p>
     */
    public static final String HTTP_CONTENT_CHARSET = "http.protocol.content-charset"; 
    
    
Defines cookie policy to be used for cookie management. 
 This parameter expects a value of type String. 
/**
     * Defines {@link CookiePolicy cookie policy} to be used for cookie management.
     * <p>
     * This parameter expects a value of type {@link String}.
     * </p>
     */
    public static final String COOKIE_POLICY = "http.protocol.cookie-policy";
    
    
Defines HttpClient's behavior when a response provides more bytes than
expected (specified with Content-Length, for example).

Such surplus data makes the HTTP connection unreliable for keep-alive
requests, as malicious response data (faked headers etc.) can lead to undesired
results on the next request using that connection.


If this parameter is set to true, any detection of extra
input data will generate a warning in the log.

 This parameter expects a value of type Boolean. 
/**
     * Defines HttpClient's behavior when a response provides more bytes than
     * expected (specified with Content-Length, for example).
     * <p>
     * Such surplus data makes the HTTP connection unreliable for keep-alive
     * requests, as malicious response data (faked headers etc.) can lead to undesired
     * results on the next request using that connection.
     * </p>
     * <p>
     * If this parameter is set to <code>true</code>, any detection of extra
     * input data will generate a warning in the log.
     * </p>
     * <p>
     * This parameter expects a value of type {@link Boolean}.
     * </p>
     */
    public static final String WARN_EXTRA_INPUT = "http.protocol.warn-extra-input";
    
    
Defines the maximum number of ignorable lines before we expect
a HTTP response's status code.

With HTTP/1.1 persistent connections, the problem arises that
broken scripts could return a wrong Content-Length
(there are more bytes sent than specified).

Unfortunately, in some cases, this is not possible after the bad response,
but only before the next one. 

So, HttpClient must be able to skip those surplus lines this way.


Set this to 0 to disallow any garbage/empty lines before the status line.
 To specify no limit, use Integer.MAX_VALUE (default in lenient mode). 
 This parameter expects a value of type Integer. /**
     * Defines the maximum number of ignorable lines before we expect
     * a HTTP response's status code.
     * <p>
     * With HTTP/1.1 persistent connections, the problem arises that
     * broken scripts could return a wrong Content-Length
     * (there are more bytes sent than specified).<br />
     * Unfortunately, in some cases, this is not possible after the bad response,
     * but only before the next one. <br />
     * So, HttpClient must be able to skip those surplus lines this way.
     * </p>
     * <p>
     * Set this to 0 to disallow any garbage/empty lines before the status line.<br />
     * To specify no limit, use {@link java.lang.Integer#MAX_VALUE} (default in lenient mode).
     * </p>
     *  
     * This parameter expects a value of type {@link Integer}.
     */
    public static final String STATUS_LINE_GARBAGE_LIMIT = "http.protocol.status-line-garbage-limit";

    
Sets the socket timeout (SO_TIMEOUT) in milliseconds to be used when executing the method. 
A timeout value of zero is interpreted as an infinite timeout.
 This parameter expects a value of type Integer. 
See Also:
SocketOptions.SO_TIMEOUT/**
     * Sets the socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds to be used when executing the method. 
     * A timeout value of zero is interpreted as an infinite timeout.
     * <p>
     * This parameter expects a value of type {@link Integer}.
     * </p>
     * @see java.net.SocketOptions#SO_TIMEOUT
     */
    public static final String SO_TIMEOUT = "http.socket.timeout"; 

    
The key used to look up the date patterns used for parsing. The String patterns are stored in a Collection and must be compatible with SimpleDateFormat. 
 This parameter expects a value of type Collection. 
/**
     * The key used to look up the date patterns used for parsing. The String patterns are stored
     * in a {@link java.util.Collection} and must be compatible with 
     * {@link java.text.SimpleDateFormat}.
     * <p>
     * This parameter expects a value of type {@link java.util.Collection}.
     * </p>
     */
    public static final String DATE_PATTERNS = "http.dateparser.patterns";

    
Sets the method retry handler parameter.
 This parameter expects a value of type HttpMethodRetryHandler. 
/**
     * Sets the method retry handler parameter.
     * <p>
     * This parameter expects a value of type {@link org.apache.commons.httpclient.HttpMethodRetryHandler}.
     * </p>
     */ 
    public static final String RETRY_HANDLER = "http.method.retry-handler";
    
    
Sets the maximum buffered response size (in bytes) that triggers no warning. Buffered
responses exceeding this size will trigger a warning in the log.
 This parameter expects a value if type Integer. 
/**
     * Sets the maximum buffered response size (in bytes) that triggers no warning. Buffered
     * responses exceeding this size will trigger a warning in the log.
     * <p>
     * This parameter expects a value if type {@link Integer}.
     * </p>
     */
    public static final String BUFFER_WARN_TRIGGER_LIMIT = "http.method.response.buffer.warnlimit";
    
    
Defines the virtual host name.
 This parameter expects a value of type String. 
/**
     * Defines the virtual host name.
     * <p>
     * This parameter expects a value of type {@link java.lang.String}. 
     * </p>
     */
    public static final String VIRTUAL_HOST = "http.virtual-host"; 

    
Sets the value to use as the multipart boundary.
 This parameter expects a value if type String. 
See Also:
MultipartRequestEntity/**
     * Sets the value to use as the multipart boundary.
     * <p>
     * This parameter expects a value if type {@link String}.
     * </p>
     * @see org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity
     */
    public static final String MULTIPART_BOUNDARY = "http.method.multipart.boundary";
    
    
Creates a new collection of parameters with the collection returned by DefaultHttpParams.getDefaultParams() as a parent. The collection will defer to its parent for a default value if a particular parameter is not explicitly set in the collection itself. 
See Also:
DefaultHttpParams.getDefaultParams()/**
     * Creates a new collection of parameters with the collection returned
     * by {@link #getDefaultParams()} as a parent. The collection will defer
     * to its parent for a default value if a particular parameter is not 
     * explicitly set in the collection itself.
     * 
     * @see #getDefaultParams()
     */
    public HttpMethodParams() {
        super(getDefaultParams());
    }

    
Creates a new collection of parameters with the given parent. 
The collection will defer to its parent for a default value 
if a particular parameter is not explicitly set in the collection
itself.
Params:
defaults – the parent collection to defer to, if a parameter
is not explictly set in the collection itself.
See Also:
DefaultHttpParams.getDefaultParams()/**
     * Creates a new collection of parameters with the given parent. 
     * The collection will defer to its parent for a default value 
     * if a particular parameter is not explicitly set in the collection
     * itself.
     * 
     * @param defaults the parent collection to defer to, if a parameter
     * is not explictly set in the collection itself.
     *
     * @see #getDefaultParams()
     */
    public HttpMethodParams(HttpParams defaults) {
        super(defaults);
    }

    
Returns the charset to be used for writing HTTP headers.
Returns:
The charset/**
     * Returns the charset to be used for writing HTTP headers.
     * @return The charset
     */
    public String getHttpElementCharset() {
        String charset = (String) getParameter(HTTP_ELEMENT_CHARSET);
        if (charset == null) {
            LOG.warn("HTTP element charset not configured, using US-ASCII");
            charset = "US-ASCII";
        }
        return charset;
    }
    
    
Sets the charset to be used for writing HTTP headers.
Params:
charset – The charset/**
     * Sets the charset to be used for writing HTTP headers.
     * @param charset The charset
     */
    public void setHttpElementCharset(String charset) {
        setParameter(HTTP_ELEMENT_CHARSET, charset);
    }

    
Returns the default charset to be used for writing content body, 
when no charset explicitly specified.
Returns:
The charset/**
     * Returns the default charset to be used for writing content body, 
     * when no charset explicitly specified.
     * @return The charset
     */
    public String getContentCharset() {
        String charset = (String) getParameter(HTTP_CONTENT_CHARSET);
        if (charset == null) {
            LOG.warn("Default content charset not configured, using ISO-8859-1");
            charset = "ISO-8859-1";
        }
        return charset;
    }
    
    
Sets the charset to be used for parsing URIs.
Params:
charset – The charset/**
     * Sets the charset to be used for parsing URIs.
     * @param charset The charset
     */
    public void setUriCharset(String charset) {
        setParameter(HTTP_URI_CHARSET, charset);
    }

    
Returns the charset to be used for parsing URIs.
Returns:
The charset/**
     * Returns the charset to be used for parsing URIs.
     * @return The charset
     */
    public String getUriCharset() {
        String charset = (String) getParameter(HTTP_URI_CHARSET);
        if (charset == null) {
            charset = "UTF-8";
        }
        return charset;
    }
    
    
Sets the default charset to be used for writing content body,
when no charset explicitly specified.
Params:
charset – The charset/**
     * Sets the default charset to be used for writing content body,
     * when no charset explicitly specified.
     * @param charset The charset
     */
    public void setContentCharset(String charset) {
        setParameter(HTTP_CONTENT_CHARSET, charset);
    }

    
Returns the charset to be used for Credentials. If not configured the HTTP element charset is used. 
Returns:
The charset/**
     * Returns the charset to be used for {@link org.apache.commons.httpclient.Credentials}. If
     * not configured the {@link #HTTP_ELEMENT_CHARSET HTTP element charset} is used.
     * @return The charset
     */
    public String getCredentialCharset() {
        String charset = (String) getParameter(CREDENTIAL_CHARSET);
        if (charset == null) {
            LOG.debug("Credential charset not configured, using HTTP element charset");
            charset = getHttpElementCharset();
        }
        return charset;
    }
    
    
Sets the charset to be used for writing HTTP headers.
Params:
charset – The charset/**
     * Sets the charset to be used for writing HTTP headers.
     * @param charset The charset
     */
    public void setCredentialCharset(String charset) {
        setParameter(CREDENTIAL_CHARSET, charset);
    }
    
    
Returns HTTP protocol version to be used by the HTTP methods that this collection of parameters applies to. 
Returns:
HTTP protocol version/**
     * Returns {@link HttpVersion HTTP protocol version} to be used by the 
     * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that 
     * this collection of parameters applies to. 
     *
     * @return {@link HttpVersion HTTP protocol version}
     */
    public HttpVersion getVersion() { 
        Object param = getParameter(PROTOCOL_VERSION);
        if (param == null) {
            return HttpVersion.HTTP_1_1;
        }
        return (HttpVersion)param;
    }
    
    
Assigns the HTTP protocol version to be used by the HTTP methods that this collection of parameters applies to. 
Params:
version – the HTTP protocol version/**
     * Assigns the {@link HttpVersion HTTP protocol version} to be used by the 
     * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that 
     * this collection of parameters applies to. 
     *
     * @param version the {@link HttpVersion HTTP protocol version}
     */
    public void setVersion(HttpVersion version) {
        setParameter(PROTOCOL_VERSION, version);
    }


    
Returns cookie policy to be used by the HTTP methods this collection of parameters applies to. 
Returns:
cookie policy/**
     * Returns {@link CookiePolicy cookie policy} to be used by the 
     * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
     * this collection of parameters applies to. 
     *
     * @return {@link CookiePolicy cookie policy}
     */
    public String getCookiePolicy() { 
        Object param = getParameter(COOKIE_POLICY);
        if (param == null) {
            return CookiePolicy.DEFAULT;
        }
        return (String)param;
    }
    
    
Assigns the cookie policy to be used by the HTTP methods this collection of parameters applies to. 
Params:
policy – the cookie policy/**
     * Assigns the {@link CookiePolicy cookie policy} to be used by the 
     * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
     * this collection of parameters applies to. 
     *
     * @param policy the {@link CookiePolicy cookie policy}
     */
    public void setCookiePolicy(String policy) {
        setParameter(COOKIE_POLICY, policy);
    }

    
Returns the default socket timeout (SO_TIMEOUT) in milliseconds which is the 
timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
timeout.  
Returns:
timeout in milliseconds/**
     * Returns the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
     * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
     * timeout.  
     *
     * @return timeout in milliseconds
     */
    public int getSoTimeout() {
        return getIntParameter(SO_TIMEOUT, 0);
    }

    
Sets the default socket timeout (SO_TIMEOUT) in milliseconds which is the 
timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
timeout.  
Params:
timeout – Timeout in milliseconds/**
     * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
     * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
     * timeout.  
     *
     * @param timeout Timeout in milliseconds
     */
    public void setSoTimeout(int timeout) {
        setIntParameter(SO_TIMEOUT, timeout);
    }

    
Sets the virtual host name.
Params:
hostname – The host name/**
     * Sets the virtual host name.
     * 
     * @param hostname The host name
     */
    public void setVirtualHost(final String hostname) {
        setParameter(VIRTUAL_HOST, hostname);
    }

    
Returns the virtual host name.
Returns:
The virtual host name/**
     * Returns the virtual host name.
     * 
     * @return The virtual host name
     */
    public String getVirtualHost() {
        return (String) getParameter(VIRTUAL_HOST);
    }
    
    private static final String[] PROTOCOL_STRICTNESS_PARAMETERS = {
        UNAMBIGUOUS_STATUS_LINE,
        SINGLE_COOKIE_HEADER,
        STRICT_TRANSFER_ENCODING,
        REJECT_HEAD_BODY,
        WARN_EXTRA_INPUT
    };
    
    
Makes the HTTP methods strictly follow the HTTP protocol specification (RFC 2616 and other relevant RFCs). It must be noted that popular HTTP agents have different degree of HTTP protocol compliance and some HTTP serves are programmed to expect the behaviour that does not strictly adhere to the HTTP specification. /**
     * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods} 
     * strictly follow the HTTP protocol specification (RFC 2616 and other relevant RFCs).
     * It must be noted that popular HTTP agents have different degree of HTTP protocol 
     * compliance and some HTTP serves are programmed to expect the behaviour that does not 
     * strictly adhere to the HTTP specification.  
     */
    public void makeStrict() {
        setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.TRUE);
        setIntParameter(STATUS_LINE_GARBAGE_LIMIT, 0);
    }

    
Makes the HTTP methods attempt to mimic the exact behaviour of commonly used HTTP agents, which many HTTP servers expect, even though such behaviour may violate the HTTP protocol specification (RFC 2616 and other relevant RFCs). /**
     * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
     * attempt to mimic the exact behaviour of commonly used HTTP agents, 
     * which many HTTP servers expect, even though such behaviour may violate   
     * the HTTP protocol specification (RFC 2616 and other relevant RFCs).
     */
    public void makeLenient() {
        setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.FALSE);
        setIntParameter(STATUS_LINE_GARBAGE_LIMIT, Integer.MAX_VALUE);
    }

}