hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From oglu...@apache.org
Subject svn commit: r391135 - in /jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http: ./ impl/
Date Mon, 03 Apr 2006 20:15:43 GMT
Author: oglueck
Date: Mon Apr  3 13:15:40 2006
New Revision: 391135

URL: http://svn.apache.org/viewcvs?rev=391135&view=rev
Log:
added API Doc for interfaces

Modified:
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/ConnectionReuseStrategy.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/Header.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpClientConnection.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpConnection.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpMessage.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpProxyConnection.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpRequest.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpResponse.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpServerConnection.java
    jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/impl/DefaultHttpClientConnection.java

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/ConnectionReuseStrategy.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/ConnectionReuseStrategy.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/ConnectionReuseStrategy.java
(original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/ConnectionReuseStrategy.java
Mon Apr  3 13:15:40 2006
@@ -41,6 +41,16 @@
  */
 public interface ConnectionReuseStrategy {
 
+    /**
+     * Tells if the connection used to receive a response should be closed or
+     * kept open. Http processors should close the physical connection if this
+     * method returns false. They should do their best to keep it open if this
+     * method returns true.
+     * 
+     * @param response The response whose connection is concerned.
+     * @return true if the connection is to be kept open, false if it is to be
+     *         closed.
+     */
     boolean keepAlive(HttpResponse response);
             
 }

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/Header.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/Header.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/Header.java (original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/Header.java Mon Apr  3
13:15:40 2006
@@ -37,7 +37,8 @@
 
 /**
  * <p>An HTTP header.</p>
- *
+ * TODO implement equals and hashCode
+ * 
  * @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
  * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
  * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
@@ -120,6 +121,14 @@
         }
     }
 
+    /**
+     * Formats a Header into a header line. The <code>header</code> is
+     * directly appended to <code>buffer</code>; no newline characters are
+     * inserted (folding).
+     * 
+     * @param buffer the buffer to append to
+     * @param header the header to format
+     */
     public static void format(final CharArrayBuffer buffer, final Header header) {
         if (buffer == null) {
             throw new IllegalArgumentException("String buffer may not be null");
@@ -134,6 +143,9 @@
         }
     }
  
+    /**
+     * @see #format(CharArrayBuffer, Header)
+     */
     public static String format(final Header header) {
         CharArrayBuffer buffer = new CharArrayBuffer(32);
         format(buffer, header);

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpClientConnection.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpClientConnection.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpClientConnection.java
(original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpClientConnection.java
Mon Apr  3 13:15:40 2006
@@ -37,6 +37,7 @@
 /**
  * An HTTP connection for use on the client side.
  * It is used for sending requests and receiving responses.
+ * TODO add local port
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
@@ -46,31 +47,111 @@
  */
 public interface HttpClientConnection extends HttpConnection {
 
+    /**
+     * Returns the current target host as set by @link #setTargetHost(HttpHost).
+     * @return the target host of this connection
+     */
     HttpHost getTargetHost();
     
+    /**
+     * Provides the implementation with the host it is supposed to connect to.
+     * The host must be set prior to a call to
+     * 
+     * @link #open(HttpParams). The target host can only be set as long as the
+     *       connection is not open.
+     * @param targethost the host to connect to
+     */
     void setTargetHost(HttpHost targethost);
     
+    /**
+     * The local address the connection is or will be bound to as set by
+     * 
+     * @link #setLocalAddress(InetAddress) or <code>null</code> if
+     *       unspecified.
+     * @return
+     */
     InetAddress getLocalAddress();
     
+    /**
+     * Sets the local address the connection will be bound to upon opening. The
+     * local address can not only be set as long as the connection is not open.
+     * If no local address is specified it is up to the implementation to
+     * decide.
+     * 
+     * @param localAddress the local bind address or <code>null</code>.
+     */
     void setLocalAddress(InetAddress localAddress);
     
+    /**
+     * Opens the connection. Implementations may use additional settings from
+     * the HttpParams hierarchy.
+     * 
+     * @param params the parameters in effect for this connection.
+     * @throws IOException
+     */
     void open(HttpParams params) throws IOException;
     
+    /**
+     * Checks if response data is available from the connection. May wait for
+     * the specified time until some data becomes available. Note that some
+     * implementations may completely ignore the timeout parameter.
+     * 
+     * @param timeout the maximum time in milliseconds to wait for data
+     * @return true if data is available; false if there was no data available
+     *         even after waiting for <code>timeout</code> milliseconds.
+     * @throws IOException if an error happens on the connection
+     */
     boolean isResponseAvailable(int timeout) 
         throws IOException; 
     
+    /**
+     * Sends the request line and all headers over the connection.
+     * @param request the request whose headers to send.
+     * @throws HttpException 
+     * @throws IOException
+     */
     void sendRequestHeader(HttpRequest request) 
         throws HttpException, IOException;
 
+    /**
+     * Sends the request entity over the connection.
+     * @param request the request whose entity to send.
+     * @throws HttpException
+     * @throws IOException
+     */
     void sendRequestEntity(HttpEntityEnclosingRequest request) 
         throws HttpException, IOException;
 
+    /**
+     * Receives the request line and headers of the next response available from
+     * this connection. The caller should examine the HttpResponse object to
+     * find out if it should try to receive a response entity as well.
+     * 
+     * @param params the parameters in effect
+     * @return a new HttpResponse object with status line and headers
+     *         initialized.
+     * @throws HttpException
+     * @throws IOException
+     */
     HttpResponse receiveResponseHeader(HttpParams params) 
         throws HttpException, IOException;
 
+    /**
+     * Receives the next response entity available from this connection and
+     * attaches it to an existing HttpResponse object.
+     * 
+     * @param response the response to attach the entity to
+     * @throws HttpException
+     * @throws IOException
+     */
     void receiveResponseEntity(HttpResponse response) 
         throws HttpException, IOException;
     
+    /**
+     * Writes out all pending buffered data over the open connection.
+     * 
+     * @throws IOException
+     */
     void flush() throws IOException;
     
 }

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpConnection.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpConnection.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpConnection.java (original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpConnection.java Mon
Apr  3 13:15:40 2006
@@ -52,8 +52,22 @@
      */
     void close() throws IOException;
     
+    /**
+     * Checks if this connection is open.
+     * @return true if it is open, false if it is closed.
+     */
     boolean isOpen();
  
+    /**
+     * Network connections may get closed during some time of inactivity for several reasons.
+     * The next time a read is attempted on such a connection it will throw an IOException.
+     * This method tries to alleviate this inconvenience by trying to find out if a connection
is still
+     * usable. Implementations may do that by attempting a read with a very small timeout.
Thus this
+     * method may block for a small indefinite time before returning a result. 
+     * 
+     * @return true if attempts to use this connection are likely to succeed, false if they
are likely
+     * to fail and this connection should be closed and discarded.
+     */
     boolean isStale();
     
     /**

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpMessage.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpMessage.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpMessage.java (original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpMessage.java Mon Apr
 3 13:15:40 2006
@@ -45,30 +45,108 @@
  */
 public interface HttpMessage {
     
-    public HttpVersion getHttpVersion();
-
+    /**
+     * Returns the HTTP version this message is compatible with.
+     */
+    HttpVersion getHttpVersion();
+
+    /**
+     * Checks if a certain header is present in this message. Header values are
+     * ignored.
+     * 
+     * @param name the header name to check for.
+     * @return true if at least one header with this name is present.
+     */
     boolean containsHeader(String name);
     
+    /**
+     * Returns all the headers with a specified name of this message. Header values
+     * are ignored. Headers are orderd in the sequence they will be sent over a
+     * connection.
+     * 
+     * @param name the name of the headers to return.
+     * @return the headers whose name property equals <code>name</code>.
+     */
     Header[] getHeaders(String name);
 
+    /**
+     * Returns the first header with a specified name of this message. Header
+     * values are ignored. If there is more than one matching header in the
+     * message the first element of
+     * 
+     * @link #getHeaders(String) is returned.
+     * @param name the name of the header to return.
+     * @return the first header whose name property equals <code>name</code>.
+     */
     Header getFirstHeader(String name);
 
+    /**
+     * Returns the last header with a specified name of this message. Header values
+     * are ignored. If there is more than one matching header in the message the
+     * last element of
+     * 
+     * @link #getHeaders(String) is returned.
+     * @param name the name of the header to return.
+     * @return the last header whose name property equals <code>name</code>.
+     */
     Header getLastHeader(String name);
 
+    /**
+     * Returns all the headers of this message. Headers are orderd in the sequence
+     * they will be sent over a connection.
+     * 
+     * @return
+     */
     Header[] getAllHeaders();
 
+    /**
+     * Adds a header to this message. The header will be appended to the end of
+     * the list.
+     * 
+     * @param header the header to append.
+     */
     void addHeader(Header header);
 
+    /**
+     * Adds a header to this message. The new header will be appended to the end
+     * of the list. Existing headers with the same name will be removed.
+     * 
+     * @param header the header to add.
+     */
     void setHeader(Header header);
 
+    /**
+     * Removes a header from this message.
+     * 
+     * @param header the header to remove.
+     */
     void removeHeader(Header header);
     
+    /**
+     * Removes all headers with a certain name from this message.
+     * 
+     * @param name The name of the headers to remove.
+     */
     void removeHeaders(String name);
     
+    /**
+     * Returns an iterator of all the headers.
+     * 
+     * @return Iterator that returns Header objects in the sequence they are
+     *         sent over a connection.
+     */
     Iterator headerIterator();
-    
+
+    /**
+     * Returns the parameters effective for this message as set by
+     * @link #setParams(HttpParams).
+     */
     HttpParams getParams();
-    
+
+    /**
+     * Provides parameters to be used for the processing of this message.
+     * @param params the parameters
+     */
     void setParams(HttpParams params);
         
 }

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpProxyConnection.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpProxyConnection.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpProxyConnection.java
(original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpProxyConnection.java
Mon Apr  3 13:15:40 2006
@@ -34,22 +34,48 @@
 import org.apache.http.params.HttpParams;
 
 /**
- * An HTTP connection through a proxy.
- *
+ * An HTTP connection through a proxy. The semantics of
+ * @link org.apache.http.HttpClientConnection#setTargetHost(HttpHost) and
+ * @link org.apache.http.HttpClientConnection#getTargetHost() methods of a proxy
+ *       connections change their meaning to designate the proxy host.
+
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
- *
  * @version $Revision$
- * 
  * @since 4.0
  */
 public interface HttpProxyConnection extends HttpClientConnection {
 
+    /**
+     * After this connection is opened to the proxy, this method may be called
+     * to create a new connection over it. Subsequent data is sent over the
+     * resulting connection.
+     * 
+     * @param targetHost The final target host
+     * @param params The parameters effective for this connection
+     * @throws IOException
+     */
     void tunnelTo(HttpHost targetHost, HttpParams params) throws IOException;
     
+    /**
+     * Returns the target host as provided by
+     * 
+     * @link #tunnelTo(HttpHost, HttpParams).
+     */
     HttpHost getTunnelTarget();
-    
+
+    /**
+     * Checks if
+     * 
+     * @link #tunnelTo(HttpHost, HttpParams) has been called on this connection.
+     * @return true if tunnelTo has been called, false if not
+     */
     boolean isTunnelActive();
 
+    /**
+     * Checks if the tunnel uses a secure socket.
+     * 
+     * @return true if this is a secure tunnel.
+     */
     boolean isSecure();
     
 }

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpRequest.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpRequest.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpRequest.java (original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpRequest.java Mon Apr
 3 13:15:40 2006
@@ -40,6 +40,12 @@
  */
 public interface HttpRequest extends HttpMessage {
 
+    /**
+     * Returns the request line of this request.
+     * @return the request line.
+     */
     RequestLine getRequestLine();
+    
+    //TODO add a setter for request line?
     
 }

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpResponse.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpResponse.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpResponse.java (original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpResponse.java Mon
Apr  3 13:15:40 2006
@@ -40,14 +40,38 @@
  */
 public interface HttpResponse extends HttpMessage {
 
+    /**
+     * Returns the status line that belongs to this response as set by
+     * @link #setStatusLine(StatusLine).
+     */
     StatusLine getStatusLine();
 
+    /**
+     * Sets the status line that belongs to this response.
+     * @param statusline the status line of this response.
+     */
     void setStatusLine(StatusLine statusline);
     
+    /**
+     * Convenience method that creates and sets a new status line of this
+     * response that is initialized with the specified status code.
+     * 
+     * @param code the HTTP status code.
+     * @see HttpStatus
+     */
     void setStatusCode(int code);
     
+    /**
+     * Returns the response entity of this response as set by
+     * @link #setEntity(HttpEntity).
+     * @return the response entity or <code>null</code> if there is none.
+     */
     HttpEntity getEntity();
     
+    /**
+     * Associates a response entity with this response.
+     * @param entity the entity to associate with this response.
+     */
     void setEntity(HttpEntity entity);
     
 }

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpServerConnection.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpServerConnection.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpServerConnection.java
(original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/HttpServerConnection.java
Mon Apr  3 13:15:40 2006
@@ -46,21 +46,62 @@
  */
 public interface HttpServerConnection extends HttpConnection {
 
+    /**
+     * Binds this connection to an underlying socket.
+     * 
+     * @param socket The underlying socket.
+     * @param params the parameters in effect for this connection
+     * @throws IOException
+     */
     void bind(Socket socket, HttpParams params) 
         throws IOException;
     
+    /**
+     * Receives the request line and all headers available from this connection.
+     * The caller should examine the returned request and decide if to receive a
+     * request entity as well.
+     * 
+     * @param params the parameters in effect for this connection
+     * @return a new HttpRequest object whose request line and headers are
+     *         initialized.
+     * @throws HttpException
+     * @throws IOException
+     */
     HttpRequest receiveRequestHeader(HttpParams params) 
         throws HttpException, IOException;
 
+    /**
+     * Receives the next request entity available from this connection and attaches it to

+     * an existing request. 
+     * @param request the request to attach the entity to.
+     * @throws HttpException
+     * @throws IOException
+     */
     void receiveRequestEntity(HttpEntityEnclosingRequest request) 
         throws HttpException, IOException;
 
+    /**
+     * Sends the response line and headers of a response over this connection.
+     * @param response the response whose headers to send.
+     * @throws HttpException
+     * @throws IOException
+     */
     void sendResponseHeader(HttpResponse response) 
         throws HttpException, IOException;
     
+    /**
+     * Sends the response entity of a response over this connection.
+     * @param response the response whose entity to send.
+     * @throws HttpException
+     * @throws IOException
+     */
     void sendResponseEntity(HttpResponse response) 
         throws HttpException, IOException;
     
+    /**
+     * Sends all pending buffered data over this connection.
+     * @throws IOException
+     */
     void flush()
         throws IOException;
     

Modified: jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/impl/DefaultHttpClientConnection.java
URL: http://svn.apache.org/viewcvs/jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/impl/DefaultHttpClientConnection.java?rev=391135&r1=391134&r2=391135&view=diff
==============================================================================
--- jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/impl/DefaultHttpClientConnection.java
(original)
+++ jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http/impl/DefaultHttpClientConnection.java
Mon Apr  3 13:15:40 2006
@@ -144,16 +144,16 @@
     }
     
     public void setTargetHost(final HttpHost targethost) {
-    	if (targethost == null) {
-    		throw new IllegalArgumentException("Target host may not be null");
-    	}
-    	assertNotOpen();
-    	this.targethost = targethost;
+        if (targethost == null) {
+            throw new IllegalArgumentException("Target host may not be null");
+        }
+        assertNotOpen();
+        this.targethost = targethost;
     }
-    
+
     public void setLocalAddress(final InetAddress localAddress) {
-    	assertNotOpen();
-    	this.localAddress = localAddress;
+        assertNotOpen();
+        this.localAddress = localAddress;
     }
     
     public boolean isResponseAvailable(int timeout) throws IOException {



Mime
View raw message