commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient HttpMethod.java
Date Sat, 02 Aug 2003 22:27:49 GMT
olegk       2003/08/02 15:27:49

  Modified:    httpclient/src/java/org/apache/commons/httpclient Tag:
                        HTTPCLIENT_2_0_BRANCH HttpMethod.java
  Log:
  Javadoc clean-ups in HttpMethod
  
  Contributed by Oleg Kalnichevski
  
  Revision  Changes    Path
  No                   revision
  
  
  No                   revision
  
  
  1.23.2.1  +119 -88   jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java
  
  Index: HttpMethod.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v
  retrieving revision 1.23
  retrieving revision 1.23.2.1
  diff -u -r1.23 -r1.23.2.1
  --- HttpMethod.java	28 Jan 2003 04:40:20 -0000	1.23
  +++ HttpMethod.java	2 Aug 2003 22:27:49 -0000	1.23.2.1
  @@ -68,15 +68,17 @@
   
   /**
    * <p>
  - * A request to be applied to an {@link HttpConnection}, and a container for the
  - * associated response.
  + * 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$ $Date$
  + * 
    * @since 1.0
    */
   public interface HttpMethod {
  @@ -84,8 +86,9 @@
       // ------------------------------------------- Property Setters and Getters
   
       /**
  -     * Obtain the name of this method, suitable for use in the "request line",
  +     * Obtain 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();
  @@ -98,25 +101,25 @@
       HostConfiguration getHostConfiguration();
   
       /**
  -     * Set the path part of my request.
  -     * @param path the path to request
  +     * Sets the path of the HTTP method.
  +     * 
  +     * @param path the path of the HTTP method
        */
       void setPath(String path);
   
       /**
  -     * Get the path part of my request.  
  +     * Returns the path of the HTTP method.  
        *
  -     * Calling this method AFTER the request
  -     * has been executed will return the ACTUAL path, following any 301 or 302 
  -     * redirects (except for redirects off the initial server, which are not 
  -     * supported, or when HttpClient is set to not follow redirects; in either
  -     * case, HttpClient returns the 301 or 302 status code).
  +     * 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 to request
        */
       String getPath();
   
       /**
  -     * Gets the URI for this method.  The URI will be absolute if the host
  +     * Gets the URI for this method. The URI will be absolute if the host
        * configuration has been set or relative otherwise.
        * 
        * @return URI 
  @@ -126,111 +129,116 @@
       URI getURI() throws URIException;
   
       /**
  -     * <p>Turns strict mode on or off.  In strict mode (the default) we
  -     * following the letter of RFC 2616, the Http 1.1 specification. If strict
  -     * mode is turned off we attempt to violate the specification in the same
  -     * way that most Http user agent's do (and many HTTP servers expect.</p>
  +     * <p>Turns strict mode on or off. In the strict mode the HTTP method exactly

  +     * follows the HTTP specification. In the non-strict mode the HTTP method attempts

  +     * to violate the specification in the same way that most HTTP user agent's do 
  +     * (and, unfortunately, as many HTTP servers expect).</p>
        *
  -     * <p>NOTE:  StrictMode is currently experimental and its functionaity may
  -     * change in the future.</p>
  -     * 
  -     * @param strictMode True to enable strict mode.
  +     * @param strictMode <tt>true</tt> to enable the strict mode.
        */
       void setStrictMode(boolean strictMode);
   
       /**
  -     * Returns the value of strictMode.
  -     *
  -     * NOTE:  StrictMode is currently experimental and its functionlaity may change in
the future.
  +     * Returns the value of the strict mode flag.
        *
  -     * @return true if strict mode is enabled.
  +     * @return <tt>true</tt> if strict mode is enabled, <tt>false</tt>
otherwise
        */
       boolean isStrictMode();
        
       /**
  -     * Set the specified request header, overwriting any
  -     * previous value.
  +     * 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
        */
       void setRequestHeader(String headerName, String headerValue);
   
       /**
  -     * Set the specified request header, overwriting any
  -     * previous value.
  +     * Sets the specified request header, overwriting any previous value.
        * Note that header-name matching is case insensitive.
  +     * 
        * @param header the header
        */
       void setRequestHeader(Header header);
   
       /**
  -     * Adds the specified request header, NOT overwriting any
  -     * previous value.
  +     * Adds the specified request header, NOT overwriting any previous value.
        * Note that header-name matching is case insensitive.
  +     * 
        * @param headerName the header's name
        * @param headerValue the header's value
        */
       void addRequestHeader(String headerName, String headerValue);
   
       /**
  -     * Adds the specified request header, NOT overwriting any
  -     * previous value.
  +     * Adds the specified request header, NOT overwriting any previous value.
        * Note that header-name matching is case insensitive.
  +     * 
        * @param header the header
        */
       void addRequestHeader(Header header);
   
       /**
  -     * Get the request header associated with the given name.
  +     * Gets the request header associated with the given name.
        * Note that header-name matching is case insensitive.
  +     * 
        * @param headerName the header name
        * @return the header
        */
       Header getRequestHeader(String headerName);
   
       /**
  -     * Remove all request headers associated with the given name.
  +     * Removes all request headers associated with the given name.
        * Note that header-name matching is case insensitive.
  +     * 
        * @param headerName the header name
        */
       void removeRequestHeader(String headerName);
   
       /**
  -     * Whether or not I should automatically follow
  -     * HTTP redirects (status code 302, etc.)
  -     * @return <tt>true</tt> if I will automatically follow HTTP redirects
  +     * Returns <tt>true</tt>if the HTTP method should automatically follow
HTTP redirects 
  +     * (status code 302, etc.), <tt>false</ff> otherwise.
  +     * 
  +     * @return <tt>true</tt> if the method will automatically follow HTTP redirects,

  +     * <tt>false</ff> otherwise.
        */
       boolean getFollowRedirects();
   
       /**
  -     * Set whether or not I should automatically follow HTTP redirects (status
  -     * code 302, etc.)
  -     * @param followRedirects True if I should automatically follow redirects.
  +     * 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</ff> otherwise.
        */
       void setFollowRedirects(boolean followRedirects);
   
       /**
  -     * Set my query string.
  +     * Sets the query string of the HTTP method.
  +     * 
        * @param queryString the query string
        */
       void setQueryString(String queryString);
   
       /**
  -     * Set my query string.
  +     * Sets the query string of the method.
  +     * 
        * @param params an array of {@link NameValuePair}s
  -     *               to add as query string parameterss
  +     *               to add as query string parameters
        */
       void setQueryString(NameValuePair[] params);
   
       /**
  -     * Get my query string.
  -     * @return my query string
  +     * Returns the query string of the HTTP method.
  +     * 
  +     * @return the query string
        */
       String getQueryString();
   
       /**
  -     * Return an array of my request headers.
  +     * Returns an array of request headers that the HTTP method currently has.
  +     * 
        * @return an array of request headers.
        */
       Header[] getRequestHeaders();
  @@ -238,91 +246,102 @@
       // ---------------------------------------------------------------- Queries
   
       /**
  -     * Confirm that I am ready to execute.
  -     * @return True if I am ready to execute.
  +     * Returns <tt>true</tt> the method is ready to execute, <tt>false</ff>
otherwise.
  +     * 
  +     * @return <tt>true</tt> if the method is ready to execute, <tt>false</ff>
otherwise.
        */
       boolean validate();
   
       /**
  -     * Return the status code associated with the latest response.
  +     * Returns the status code associated with the latest response.
  +     * 
        * @return the status code.
        */
       int getStatusCode();
   
       /**
  -     * Return the status text (or "reason phrase") associated with the latest
  +     * Returns the status text (or "reason phrase") associated with the latest
        * response.
  +     * 
        * @return The status text.
        */
       String getStatusText();
   
       /**
  -     * Return an array of my response headers.
  +     * Returns an array of the response headers that the HTTP method currently has.
  +     * 
        * @return An array of all the response headers.
        */
       Header[] getResponseHeaders();
   
       /**
  -     * Return the specified response header. Note that header-name matching is
  +     * Returns the specified response header. Note that header-name matching is
        * case insensitive.
  +     * 
        * @param headerName The name of the header to be returned.
        * @return The specified response header.
        */
       Header getResponseHeader(String headerName);
   
       /**
  -     * Return an array of my response footers
  -     * @return <tt>null</tt> if no footers are available
  +     * Returns an array of the response footers that the HTTP method currently has
  +     * 
  +     * @return an array of the response footers
        */
       Header[] getResponseFooters();
   
       /**
        * Return the specified response footer. Note that footer-name matching is
        * case insensitive.
  +     * 
        * @param footerName The name of the footer.
        * @return The response footer.
        */
       Header getResponseFooter(String footerName);
   
       /**
  -     * Return my response body, if any, as a byte array. Otherwise return
  -     * <tt>null</tt>.
  +     * Returns the response body of the HTTP method, if any, as an array of bytes.
  +     * 
        * @return The response body.
        */
       byte[] getResponseBody();
   
       /**
  -     * Return my response body, if any, as a {@link String}. Otherwise return
  -     * <tt>null</tt>.
  -     * @return response body.
  +     * Returns the response body of the HTTP method, if any, as a {@link String}. 
  +     * 
  +     * @return THe response body.
        */
       String getResponseBodyAsString();
   
       /**
  -     * Return my response body, if any, as an {@link InputStream}. Otherwise
  -     * return <tt>null</tt>.
  -     * @return As above.
  -     * @throws IOException If an IO problem occurs.
  +     * Returns the response body of the HTTP method, if any, as an {@link InputStream}.

  +     * 
  +     * @return The response body
  +     * 
  +     * @throws IOException If an I/O (transport) problem occurs.
        */
       InputStream getResponseBodyAsStream() throws IOException;
   
       /**
  -     * Return <tt>true</tt> if I have been {@link #execute executed}
  -     * but not recycled.
  -     * @return true if this has been used.
  +     * Returns <tt>true</tt> if the HTTP method has been already {@link #execute
executed},
  +     * but not {@link #recycle recycled}.
  +     * 
  +     * @return <tt>true</tt> if the method has been executed, <tt>false</tt>
otherwise
        */
       boolean hasBeenUsed();
   
       // --------------------------------------------------------- Action Methods
   
       /**
  -     * Execute this method.
  +     * Execute the HTTP method.
        *
  -     * @param state state information to associate with this request
  -     * @param connection the {@link HttpConnection} to write to/read from
  +     * @param state the {@link HttpState state} information to associate with this method
  +     * @param connection the {@link HttpConnection connection} to be used
        *
  -     * @throws IOException if an I/O error occurs
  -     * @throws HttpException  if an protocol exception occurs
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions

  +     *                    cannot be recovered from.
        *
        * @return the integer status code if one was obtained, or <tt>-1</tt>
        */
  @@ -330,49 +349,61 @@
           throws HttpException, IOException;
   
       /**
  -     * Recycle this method so that it can be used again.
  -     * Note that all of my instance variables will be reset
  -     * once this method has been called.
  +     * Recycles the HTTP method so that it can be used again.
  +     * Note that all of the instance variables will be reset
  +     * once this method has been called. This method will also
  +     * release the connection being used by this HTTP method.
  +     * 
  +     * @see #releaseConnection()
        */
       void recycle();
   
       /**
  -     * Releases the connection being used by this method.  In particular the
  +     * Releases the connection being used by this HTTP method. In particular the
        * connection is used to read the response(if there is one) and will be held
  -     * until the response has been read.
  +     * until the response has been read. If the connection can be reused by other 
  +     * HTTP methods it is NOT closed at this point.
        */
       void releaseConnection();
   
       /**
        * Use this method internally to add footers.
  +     * 
        * @param footer The footer to add.
  +     * 
        * @since 2.0
        */
       void addResponseFooter(Header footer);
   
       /** 
  -     * Return the Status-Line from the response.
  +     * Returns the Status-Line from the response.
  +     * 
        * @return The status line
  +     * 
        * @since 2.0
        */
       StatusLine getStatusLine();
   
       /**
  -     * Whether or not I should automatically process responses where
  -     * authentication is required (status code 401, etc.)
  +     * Returns <tt>true</tt> if the HTTP method should automatically handle
HTTP 
  +     * authentication challenges (status code 401, etc.), <tt>false</tt> otherwise
        *
  -     * @return <tt>true</tt> if authentications will be processed automatically
  +     * @return <tt>true</tt> if authentication challenges will be processed

  +     * automatically, <tt>false</tt> otherwise.
  +     * 
        * @since 2.0
        */
       boolean getDoAuthentication();
   
       /**
  -     * Set whether or not I should automatically process responses where
  -     * authentication is required (status code 401, etc.)
  +     * Sets whether or not the HTTP method should automatically handle HTTP 
  +     * authentication challenges (status code 401, etc.)
        *
  -     * @param doAuthentication <tt>true</tt> to process authentications
  +     * @param doAuthentication <tt>true</tt> to process authentication challenges
  +     * authomatically, <tt>false</tt> otherwise.
  +     * 
        * @since 2.0
        */
       void setDoAuthentication(boolean doAuthentication);
  -      
  +
   }
  
  
  

Mime
View raw message