/* * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v 1.43 2004/10/07 16:14:15 olegk Exp $ * $Revision: 480424 $ * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 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;import java.io.IOException;import java.io.InputStream;import org.apache.commons.httpclient.auth.AuthState;import org.apache.commons.httpclient.params.HttpMethodParams;/** * <p> * HttpMethod interface represents a request to be sent via a  * {@link HttpConnection HTTP connection} and a corresponding response. * </p> * @author <a href="mailto:remm@apache.org">Remy Maucherat</a> * @author Rod Waldhoff * @author <a href="jsdever@apache.org">Jeff Dever</a> * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a> * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a> * * @version $Revision: 480424 $ $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $ *  * @since 1.0 */public interface HttpMethod {    // ------------------------------------------- Property Setters and Getters    /**     * Obtains the name of the HTTP method as used in the HTTP request line,     * for example <tt>"GET"</tt> or <tt>"POST"</tt>.     *      * @return the name of this method     */    String getName();    /**     * Gets the host configuration for this method.  The configuration specifies     * the server, port, protocol, and proxy server via which this method will     * send its HTTP request.     *      * @deprecated no longer applicable      *      * @return the HostConfiguration or <code>null</code> if none is set     */    HostConfiguration getHostConfiguration();    /**     * Sets the path of the HTTP method.     * It is responsibility of the caller to ensure that the path is     * properly encoded (URL safe).     *      * @param path The path of the HTTP method. The path is expected     *             to be URL encoded.     */    void setPath(String path);    /**     * Returns the path of the HTTP method.       *     * Calling this method <em>after</em> the request has been executed will      * return the <em>actual</em> path, following any redirects automatically     * handled by this HTTP method.     *      * @return the path of the HTTP method, in URL encoded form     */    String getPath();    /**     * Returns the URI for this method. The URI will be absolute if the host     * configuration has been set and relative otherwise.     *      * @return the URI for this method     *      * @throws URIException if a URI cannot be constructed     */    URI getURI() throws URIException;    /**     * Sets the URI for this method.      *      * @param uri URI to be set      *      * @throws URIException if a URI cannot be set     *      * @since 3.0     */    void setURI(URI uri) throws URIException;    /**     * Defines how strictly the method follows the HTTP protocol specification.       * (See RFC 2616 and other relevant RFCs.) In the strict mode the method precisely     * implements the requirements of the specification, whereas in non-strict mode      * it attempts to mimic the exact behaviour of commonly used HTTP agents,      * which many HTTP servers expect.     *      * @param strictMode <tt>true</tt> for strict mode, <tt>false</tt> otherwise     *      * @deprecated Use {@link org.apache.commons.httpclient.params.HttpParams#setParameter(String, Object)}      * to exercise a more granular control over HTTP protocol strictness.     *      * @see #isStrictMode()     */    void setStrictMode(boolean strictMode);    /**     * Returns the value of the strict mode flag.     *     * @return <tt>true</tt> if strict mode is enabled, <tt>false</tt> otherwise     *      * @deprecated Use {@link org.apache.commons.httpclient.params.HttpParams#setParameter(String, Object)}      * to exercise a more granular control over HTTP protocol strictness.     *      * @see #setStrictMode(boolean)     */    boolean isStrictMode();         /**     * Sets the specified request header, overwriting any     * previous value.     * Note that header-name matching is case insensitive.     * @param headerName the header's name     * @param headerValue the header's value     *     * @see #setRequestHeader(Header)     * @see #getRequestHeader(String)     * @see #removeRequestHeader(String)     */    void setRequestHeader(String headerName, String headerValue);    /**     * Sets the specified request header, overwriting any     * previous value.     * Note that header-name matching is case insensitive.     * @param header the header to be set     *     * @see #setRequestHeader(String,String)     * @see #getRequestHeader(String)     * @see #removeRequestHeader(String)     */    void setRequestHeader(Header header);    /**     * Adds the specified request header, <em>not</em> overwriting any previous value.     * If the same header is added multiple times, perhaps with different values,     * multiple instances of that header will be sent in the HTTP request.     * Note that header-name matching is case insensitive.     * @param headerName the header's name     * @param headerValue the header's value     *      * @see #addRequestHeader(Header)     * @see #getRequestHeader(String)     * @see #removeRequestHeader(String)     */    void addRequestHeader(String headerName, String headerValue);    /**     * Adds the specified request header, <em>not</em> overwriting any previous value.     * If the same header is added multiple times, perhaps with different values,     * multiple instances of that header will be sent in the HTTP request.     * Note that header-name matching is case insensitive.     * @param header the header     *      * @see #addRequestHeader(String,String)     * @see #getRequestHeader(String)     * @see #removeRequestHeader(String)     */    void addRequestHeader(Header header);    /**     * Gets the request header with the given name.     * If there are multiple headers with the same name,     * there values will be combined with the ',' separator as specified by RFC2616.     * Note that header-name matching is case insensitive.     * @param headerName the header name     * @return the header     */    Header getRequestHeader(String headerName);    /**     * Removes all request headers with the given name.     * Note that header-name matching is case insensitive.     * @param headerName the header name     */    void removeRequestHeader(String headerName);    /**     * Removes the given request header.     *      * @param header the header     *      * @since 3.0     */    void removeRequestHeader(Header header);    /**     * Returns <tt>true</tt> if the HTTP method should automatically follow HTTP redirects      * (status code 302, etc.), <tt>false</tt> otherwise.     *      * @return <tt>true</tt> if the method will automatically follow HTTP redirects,      * <tt>false</tt> otherwise     */    boolean getFollowRedirects();    /**     * Sets whether or not the HTTP method should automatically follow HTTP redirects      * (status code 302, etc.)     *      * @param followRedirects <tt>true</tt> if the method will automatically follow redirects,     * <tt>false</tt> otherwise.     */    void setFollowRedirects(boolean followRedirects);    /**     * Sets the query string of the HTTP method.     * It is responsibility of the caller to ensure that the path is     * properly encoded (URL safe).  The string must not include an initial '?' character.     *      * @param queryString the query to be used in the request, with no leading '?' character     *      * @see #getQueryString()     * @see #setQueryString(NameValuePair[])     */    void setQueryString(String queryString);    /**     * Sets the query string of this HTTP method.  The pairs are encoded as UTF-8 characters.       * To use a different charset the parameters can be encoded manually using EncodingUtil      * and set as a single String.     *     * @param params An array of <code>NameValuePair</code>s to use as the query string.     *               The name/value pairs will be automatically URL encoded and should not     *               have been encoded previously.     *      * @see #getQueryString()     * @see #setQueryString(String)     * @see org.apache.commons.httpclient.util.EncodingUtil#formUrlEncode(NameValuePair[], String)     */    void setQueryString(NameValuePair[] params);    /**     * Returns the query string of this HTTP method.     *      * @return the query string in URL encoded form, without a leading '?'.     *      * @see #setQueryString(NameValuePair[])      * @see #setQueryString(String)     */    String getQueryString();    /**     * Returns the current request headers for this HTTP method.  The returned headers     * will be in the same order that they were added with <code>addRequestHeader</code>.     * If there are multiple request headers with the same name (e.g. <code>Cookie</code>),     * they will be returned as multiple entries in the array.     *      * @return an array containing all of the request headers     *      * @see #addRequestHeader(Header)     * @see #addRequestHeader(String,String)