View Javadoc

    1   /*
    2    * $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 $
    3    * $Revision: 480424 $
    4    * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 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;
    32
    33  import java.io.IOException;
    34  import java.io.InputStream;
    35
    36  import org.apache.commons.httpclient.auth.AuthState;
    37  import org.apache.commons.httpclient.params.HttpMethodParams;
    38
    39  /**
    40   * <p>
    41   * HttpMethod interface represents a request to be sent via a
    42   * {@link HttpConnection HTTP connection} and a corresponding response.
    43   * </p>
    44   * @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
    45   * @author Rod Waldhoff
    46   * @author <a href="jsdever@apache.org">Jeff Dever</a>
    47   * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
    48   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
    49   *
    50   * @version $Revision: 480424 $ $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
    51   *
    52   * @since 1.0
    53   */
    54  public interface HttpMethod {
    55
    56      // ------------------------------------------- Property Setters and Getters
    57
    58      /**
    59       * Obtains the name of the HTTP method as used in the HTTP request line,
    60       * for example <tt>"GET"</tt> or <tt>"POST"</tt>.
    61       *
    62       * @return the name of this method
    63       */
    64      String getName();
    65
    66      /**
    67       * Gets the host configuration for this method.  The configuration specifies
    68       * the server, port, protocol, and proxy server via which this method will
    69       * send its HTTP request.
    70       *
    71       * @deprecated no longer applicable
    72       *
    73       * @return the HostConfiguration or <code>null</code> if none is set
    74       */
    75      HostConfiguration getHostConfiguration();
    76
    77      /**
    78       * Sets the path of the HTTP method.
    79       * It is responsibility of the caller to ensure that the path is
    80       * properly encoded (URL safe).
    81       *
    82       * @param path The path of the HTTP method. The path is expected
    83       *             to be URL encoded.
    84       */
    85      void setPath(String path);
    86
    87      /**
    88       * Returns the path of the HTTP method.
    89       *
    90       * Calling this method <em>after</em> the request has been executed will
    91       * return the <em>actual</em> path, following any redirects automatically
    92       * handled by this HTTP method.
    93       *
    94       * @return the path of the HTTP method, in URL encoded form
    95       */
    96      String getPath();
    97
    98      /**
    99       * Returns the URI for this method. The URI will be absolute if the host
    100      * configuration has been set and relative otherwise.
    101      *
    102      * @return the URI for this method
    103      *
    104      * @throws URIException if a URI cannot be constructed
    105      */
    106     URI getURI() throws URIException;
    107
    108     /**
    109      * Sets the URI for this method.
    110      *
    111      * @param uri URI to be set
    112      *
    113      * @throws URIException if a URI cannot be set
    114      *
    115      * @since 3.0
    116      */
    117     void setURI(URI uri) throws URIException;
    118
    119     /**
    120      * Defines how strictly the method follows the HTTP protocol specification.
    121      * (See RFC 2616 and other relevant RFCs.) In the strict mode the method precisely
    122      * implements the requirements of the specification, whereas in non-strict mode
    123      * it attempts to mimic the exact behaviour of commonly used HTTP agents,
    124      * which many HTTP servers expect.
    125      *
    126      * @param strictMode <tt>true</tt> for strict mode, <tt>false</tt> otherwise
    127      *
    128      * @deprecated Use {@link org.apache.commons.httpclient.params.HttpParams#setParameter(String, Object)}
    129      * to exercise a more granular control over HTTP protocol strictness.
    130      *
    131      * @see #isStrictMode()
    132      */
    133     void setStrictMode(boolean strictMode);
    134
    135     /**
    136      * Returns the value of the strict mode flag.
    137      *
    138      * @return <tt>true</tt> if strict mode is enabled, <tt>false</tt> otherwise
    139      *
    140      * @deprecated Use {@link org.apache.commons.httpclient.params.HttpParams#setParameter(String, Object)}
    141      * to exercise a more granular control over HTTP protocol strictness.
    142      *
    143      * @see #setStrictMode(boolean)
    144      */
    145     boolean isStrictMode();
    146
    147     /**
    148      * Sets the specified request header, overwriting any
    149      * previous value.
    150      * Note that header-name matching is case insensitive.
    151      * @param headerName the header's name
    152      * @param headerValue the header's value
    153      *
    154      * @see #setRequestHeader(Header)
    155      * @see #getRequestHeader(String)
    156      * @see #removeRequestHeader(String)
    157      */
    158     void setRequestHeader(String headerName, String headerValue);
    159
    160     /**
    161      * Sets the specified request header, overwriting any
    162      * previous value.
    163      * Note that header-name matching is case insensitive.
    164      * @param header the header to be set
    165      *
    166      * @see #setRequestHeader(String,String)
    167      * @see #getRequestHeader(String)
    168      * @see #removeRequestHeader(String)
    169      */
    170     void setRequestHeader(Header header);
    171
    172     /**
    173      * Adds the specified request header, <em>not</em> overwriting any previous value.
    174      * If the same header is added multiple times, perhaps with different values,
    175      * multiple instances of that header will be sent in the HTTP request.
    176      * Note that header-name matching is case insensitive.
    177      * @param headerName the header's name
    178      * @param headerValue the header's value
    179      *
    180      * @see #addRequestHeader(Header)
    181      * @see #getRequestHeader(String)
    182      * @see #removeRequestHeader(String)
    183      */
    184     void addRequestHeader(String headerName, String headerValue);
    185
    186     /**
    187      * Adds the specified request header, <em>not</em> overwriting any previous value.
    188      * If the same header is added multiple times, perhaps with different values,
    189      * multiple instances of that header will be sent in the HTTP request.
    190      * Note that header-name matching is case insensitive.
    191      * @param header the header
    192      *
    193      * @see #addRequestHeader(String,String)
    194      * @see #getRequestHeader(String)
    195      * @see #removeRequestHeader(String)
    196      */
    197     void addRequestHeader(Header header);
    198
    199     /**
    200      * Gets the request header with the given name.
    201      * If there are multiple headers with the same name,
    202      * there values will be combined with the ',' separator as specified by RFC2616.
    203      * Note that header-name matching is case insensitive.
    204      * @param headerName the header name
    205      * @return the header
    206      */
    207     Header getRequestHeader(String headerName);
    208
    209     /**
    210      * Removes all request headers with the given name.
    211      * Note that header-name matching is case insensitive.
    212      * @param headerName the header name
    213      */
    214     void removeRequestHeader(String headerName);
    215
    216     /**
    217      * Removes the given request header.
    218      *
    219      * @param header the header
    220      *
    221      * @since 3.0
    222      */
    223     void removeRequestHeader(Header header);
    224
    225     /**
    226      * Returns <tt>true</tt> if the HTTP method should automatically follow HTTP redirects
    227      * (status code 302, etc.), <tt>false</tt> otherwise.
    228      *
    229      * @return <tt>true</tt> if the method will automatically follow HTTP redirects,
    230      * <tt>false</tt> otherwise
    231      */
    232     boolean getFollowRedirects();
    233
    234     /**
    235      * Sets whether or not the HTTP method should automatically follow HTTP redirects
    236      * (status code 302, etc.)
    237      *
    238      * @param followRedirects <tt>true</tt> if the method will automatically follow redirects,
    239      * <tt>false</tt> otherwise.
    240      */
    241     void setFollowRedirects(boolean followRedirects);
    242
    243     /**
    244      * Sets the query string of the HTTP method.
    245      * It is responsibility of the caller to ensure that the path is
    246      * properly encoded (URL safe).  The string must not include an initial '?' character.
    247      *
    248      * @param queryString the query to be used in the request, with no leading '?' character
    249      *
    250      * @see #getQueryString()
    251      * @see #setQueryString(NameValuePair[])
    252      */
    253     void setQueryString(String queryString);
    254
    255     /**
    256      * Sets the query string of this HTTP method.  The pairs are encoded as UTF-8 characters.
    257      * To use a different charset the parameters can be encoded manually using EncodingUtil
    258      * and set as a single String.
    259      *
    260      * @param params An array of <code>NameValuePair</code>s to use as the query string.
    261      *               The name/value pairs will be automatically URL encoded and should not
    262      *               have been encoded previously.
    263      *
    264      * @see #getQueryString()
    265      * @see #setQueryString(String)
    266      * @see org.apache.commons.httpclient.util.EncodingUtil#formUrlEncode(NameValuePair[], String)
    267      */
    268     void setQueryString(NameValuePair[] params);
    269
    270     /**
    271      * Returns the query string of this HTTP method.
    272      *
    273      * @return the query string in URL encoded form, without a leading '?'.
    274      *
    275      * @see #setQueryString(NameValuePair[])
    276      * @see #setQueryString(String)
    277      */
    278     String getQueryString();
    279
    280     /**
    281      * Returns the current request headers for this HTTP method.  The returned headers
    282      * will be in the same order that they were added with <code>addRequestHeader</code>.
    283      * If there are multiple request headers with the same name (e.g. <code>Cookie</code>),
    284      * they will be returned as multiple entries in the array.
    285      *
    286      * @return an array containing all of the request headers
    287      *
    288      * @see #addRequestHeader(Header)
    289      * @see #addRequestHeader(String,String)
    290      */
    291     Header[] getRequestHeaders();
    292
    293     /**
    294      * Returns the request headers with the given name. Note that header-name matching is
    295      * case insensitive.
    296      * @param headerName the name of the headers to be returned.
    297      * @return an array of zero or more headers
    298      *
    299      * @since 3.0
    300      */
    301     Header[] getRequestHeaders(String headerName);
    302
    303     // ---------------------------------------------------------------- Queries
    304
    305     /**
    306      * Returns <tt>true</tt> the method is ready to execute, <tt>false</tt> otherwise.
    307      *
    308      * @return <tt>true</tt> if the method is ready to execute, <tt>false</tt> otherwise.
    309      */
    310     boolean validate();
    311
    312     /**
    313      * Returns the status code associated with the latest response.
    314      *
    315      * @return The status code from the most recent execution of this method.
    316      *         If the method has not yet been executed, the result is undefined.
    317      */
    318     int getStatusCode();
    319
    320     /**
    321      * Returns the status text (or "reason phrase") associated with the latest
    322      * response.
    323      *
    324      * @return The status text from the most recent execution of this method.
    325      *         If the method has not yet been executed, the result is undefined.
    326      */
    327     String getStatusText();
    328
    329     /**
    330      * Returns the response headers from the most recent execution of this request.
    331      *
    332      * @return A newly-created array containing all of the response headers,
    333      *         in the order in which they appeared in the response.
    334      */
    335     Header[] getResponseHeaders();
    336
    337     /**
    338      * Returns the specified response header. Note that header-name matching is
    339      * case insensitive.
    340      *
    341      * @param headerName The name of the header to be returned.
    342      *
    343      * @return The specified response header.  If the repsonse contained multiple
    344      *         instances of the header, its values will be combined using the ','
    345      *         separator as specified by RFC2616.
    346      */
    347     Header getResponseHeader(String headerName);
    348
    349     /**
    350      * Returns the response headers with the given name. Note that header-name matching is
    351      * case insensitive.
    352      * @param headerName the name of the headers to be returned.
    353      * @return an array of zero or more headers
    354      *
    355      * @since 3.0
    356      */
    357     Header[] getResponseHeaders(String headerName);
    358
    359     /**
    360      * Returns the response footers from the most recent execution of this request.
    361      *
    362      * @return an array containing the response footers in the order that they
    363      *         appeared in the response.  If the response had no footers,
    364      *         an empty array will be returned.
    365      */
    366     Header[] getResponseFooters();
    367
    368     /**
    369      * Return the specified response footer. Note that footer-name matching is
    370      * case insensitive.
    371      *
    372      * @param footerName The name of the footer.
    373      * @return The response footer.
    374      */
    375     Header getResponseFooter(String footerName);
    376
    377     /**
    378      * Returns the response body of the HTTP method, if any, as an array of bytes.
    379      * If the method has not yet been executed or the response has no body, <code>null</code>
    380      * is returned.  Note that this method does not propagate I/O exceptions.
    381      * If an error occurs while reading the body, <code>null</code> will be returned.
    382      *
    383      * @return The response body, or <code>null</code> if the
    384      *         body is not available.
    385      *
    386      * @throws IOException if an I/O (transport) problem occurs
    387      */
    388     byte[] getResponseBody() throws IOException;
    389
    390     /**
    391      * Returns the response body of the HTTP method, if any, as a {@link String}.
    392      * If response body is not available or cannot be read, <tt>null</tt> is returned.
    393      * The raw bytes in the body are converted to a <code>String</code> using the
    394      * character encoding specified in the response's <tt>Content-Type</tt> header, or
    395      * ISO-8859-1 if the response did not specify a character set.
    396      * <p>
    397      * Note that this method does not propagate I/O exceptions.
    398      * If an error occurs while reading the body, <code>null</code> will be returned.
    399      *
    400      * @return The response body converted to a <code>String</code>, or <code>null</code>
    401      *         if the body is not available.
    402      *
    403      * @throws IOException if an I/O (transport) problem occurs
    404      */
    405     String getResponseBodyAsString() throws IOException;
    406
    407     /**
    408      * Returns the response body of the HTTP method, if any, as an InputStream.
    409      * If the response had no body or the method has not yet been executed,
    410      * <code>null</code> is returned.  Additionally, <code>null</code> may be returned
    411      * if {@link #releaseConnection} has been called or
    412      * if this method was called previously and the resulting stream was closed.
    413      *
    414      * @return The response body, or <code>null</code> if it is not available
    415      *
    416      * @throws IOException if an I/O (transport) problem occurs
    417      */
    418     InputStream getResponseBodyAsStream() throws IOException;
    419
    420     /**
    421      * Returns <tt>true</tt> if the HTTP method has been already {@link #execute executed},
    422      * but not {@link #recycle recycled}.
    423      *
    424      * @return <tt>true</tt> if the method has been executed, <tt>false</tt> otherwise
    425      */
    426     boolean hasBeenUsed();
    427
    428     // --------------------------------------------------------- Action Methods
    429
    430     /**
    431      * Executes this method using the specified <code>HttpConnection</code> and
    432      * <code>HttpState</code>.
    433      *
    434      * @param state the {@link HttpState state} information to associate with this method
    435      * @param connection the {@link HttpConnection connection} used to execute
    436      *        this HTTP method
    437      *
    438      * @throws IOException If an I/O (transport) error occurs. Some transport exceptions
    439      *                     can be recovered from.
    440      * @throws HttpException  If a protocol exception occurs. Usually protocol exceptions
    441      *                    cannot be recovered from.
    442      *
    443      * @return the integer status code if one was obtained, or <tt>-1</tt>
    444      */
    445     int execute(HttpState state, HttpConnection connection)
    446         throws HttpException, IOException;
    447
    448     /**
    449      * Aborts the execution of the HTTP method.
    450      *
    451      * @see #execute(HttpState, HttpConnection)
    452      *
    453      * @since 3.0
    454      */
    455     void abort();
    456
    457     /**
    458      * Recycles the HTTP method so that it can be used again.
    459      * Note that all of the instance variables will be reset
    460      * once this method has been called. This method will also
    461      * release the connection being used by this HTTP method.
    462      *
    463      * @see #releaseConnection()
    464      *
    465      * @deprecated no longer supported and will be removed in the future
    466      *             version of HttpClient
    467      */
    468     void recycle();
    469
    470     /**
    471      * Releases the connection being used by this HTTP method. In particular the
    472      * connection is used to read the response (if there is one) and will be held
    473      * until the response has been read. If the connection can be reused by other
    474      * HTTP methods it is NOT closed at this point.
    475      * <p>
    476      * After this method is called, {@link #getResponseBodyAsStream} will return
    477      * <code>null</code>, and {@link #getResponseBody} and {@link #getResponseBodyAsString}
    478      * <em>may</em> return <code>null</code>.
    479      */
    480     void releaseConnection();
    481
    482     /**
    483      * Add a footer to this method's response.
    484      * <p>
    485      * <b>Note:</b> This method is for
    486      * internal use only and should not be called by external clients.
    487      *
    488      * @param footer the footer to add
    489      *
    490      * @since 2.0
    491      */
    492     void addResponseFooter(Header footer);
    493
    494     /**
    495      * Returns the Status-Line from the most recent response for this method,
    496      * or <code>null</code> if the method has not been executed.
    497      *
    498      * @return the status line, or <code>null</code> if the method has not been executed
    499      *
    500      * @since 2.0
    501      */
    502     StatusLine getStatusLine();
    503
    504     /**
    505      * Returns <tt>true</tt> if the HTTP method should automatically handle HTTP
    506      * authentication challenges (status code 401, etc.), <tt>false</tt> otherwise
    507      *
    508      * @return <tt>true</tt> if authentication challenges will be processed
    509      * automatically, <tt>false</tt> otherwise.
    510      *
    511      * @since 2.0
    512      *
    513      * @see #setDoAuthentication(boolean)
    514      */
    515     boolean getDoAuthentication();
    516
    517     /**
    518      * Sets whether or not the HTTP method should automatically handle HTTP
    519      * authentication challenges (status code 401, etc.)
    520      *
    521      * @param doAuthentication <tt>true</tt> to process authentication challenges
    522      * automatically, <tt>false</tt> otherwise.
    523      *
    524      * @since 2.0
    525      *
    526      * @see #getDoAuthentication()
    527      */
    528     void setDoAuthentication(boolean doAuthentication);
    529
    530
    531     /**
    532      * Returns {@link HttpMethodParams HTTP protocol parameters} associated with this method.
    533      *
    534      * @since 3.0
    535      *
    536      * @see HttpMethodParams
    537      */
    538     public HttpMethodParams getParams();
    539
    540     /**
    541      * Assigns {@link HttpMethodParams HTTP protocol parameters} for this method.
    542      *
    543      * @since 3.0
    544      *
    545      * @see HttpMethodParams
    546      */
    547     public void setParams(final HttpMethodParams params);
    548
    549     /**
    550      * Returns the target host {@link AuthState authentication state}
    551      *
    552      * @return host authentication state
    553      *
    554      * @since 3.0
    555      */
    556     public AuthState getHostAuthState();
    557
    558     /**
    559      * Returns the proxy {@link AuthState authentication state}
    560      *
    561      * @return host authentication state
    562      *
    563      * @since 3.0
    564      */
    565     public AuthState getProxyAuthState();
    566
    567     /**
    568      * Returns <tt>true</tt> if the HTTP has been transmitted to the target
    569      * server in its entirety, <tt>false</tt> otherwise. This flag can be useful
    570      * for recovery logic. If the request has not been transmitted in its entirety,
    571      * it is safe to retry the failed method.
    572      *
    573      * @return <tt>true</tt> if the request has been sent, <tt>false</tt> otherwise
    574      */
    575     boolean isRequestSent();
    576
    577 }