Index: HttpClient.java =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpClient.java,v retrieving revision 1.76 diff -u -r1.76 HttpClient.java --- HttpClient.java 12 May 2003 02:42:42 -0000 1.76 +++ HttpClient.java 15 Sep 2003 11:57:24 -0000 @@ -75,9 +75,9 @@ /** *

- * An HTTP "user-agent", containing an {@link HttpState} and - * one or more {@link HttpConnection}s, to which - * {@link HttpMethod}s can be applied. + * An HTTP "user-agent", containing an {@link HttpState HTTP state} and + * one or more {@link HttpConnection HTTP connections}, to which + * {@link HttpMethod HTTP methods} can be applied. *

* @author Remy Maucherat * @author Rodney Waldhoff @@ -88,6 +88,7 @@ * @author Mike Bowler * @author Sam Maloney * @author Laura Werner + * @author Oleg Kalnichevski * * @version $Revision: 1.76 $ $Date: 2003/05/12 02:42:42 $ */ @@ -120,7 +121,8 @@ // ----------------------------------------------------------- Constructors /** - * Creates an HttpClient using SimpleHttpConnectionManager. + * Creates an instance of HttpClient using a + * {@link SimpleHttpConnectionManager simple HTTP connection manager}. * * @see SimpleHttpConnectionManager */ @@ -129,8 +131,9 @@ } /** - * Creates an HttpClient with a user specified connection manager. - * @param httpConnectionManager The connection manager to use. + * Creates an instance of HttpClient with a user specified connection manager. + * @param httpConnectionManager The {@link HttpConnectionManager connection manager} + * to use. * * @since 2.0 */ @@ -149,33 +152,48 @@ // ----------------------------------------------------- Instance Variables - /** The current connection manager */ + /** + * The {@link HttpConnectionManager connection manager} being used to manage + * connections for this HttpClient + */ private HttpConnectionManager httpConnectionManager; /** - * My {@link HttpState state}. + * The {@link HttpState HTTP state} associated with this HttpClient. */ private HttpState state; - /** the timout when waiting for a connection from the connectionManager */ + /** + * The timout in milliseconds when waiting for a connection from the + * {@link HttpConnectionManager connection manager} + */ private long httpConnectionTimeout = 0; - /** The timeout in milliseconds*/ + /** + * The socket timeout in milliseconds. + */ private int timeoutInMilliseconds = 0; - /** The connection timeout. */ + /** + * The connection timeout in milliseconds. + */ private int connectionTimeout = 0; - /** The host configuration to use */ + /** + * The {@link HostConfiguration host configuration} associated with + * the HttpClient + */ private HostConfiguration hostConfiguration; - /** True if strict mode is enabled. */ + /** + * True if strict mode is enabled. + */ private boolean strictMode = false; // ------------------------------------------------------------- Properties /** - * Get my {@link HttpState state}. + * Returns {@link HttpState HTTP state} associated with the HttpClient. * * @see #setState(HttpState) * @return the shared client state @@ -185,52 +203,58 @@ } /** - * Set my {@link HttpState state}. + * Assigns {@link HttpState HTTP state} for the HttpClient. * * @see #getState() - * @param state the new state for the client + * @param state the new {@link HttpState HTTP state} for the client */ public synchronized void setState(HttpState state) { this.state = state; } /** - * - * @param strictMode true if strict mode should be used - * + * 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 true for strict mode, false otherwise + * * @see #isStrictMode() - * */ public synchronized void setStrictMode(boolean strictMode) { this.strictMode = strictMode; } /** + * Returns the value of the strict mode flag. * - * @return true if strict mode being used - * + * @return true if strict mode is enabled, false otherwise + * * @see #setStrictMode(boolean) - * */ public synchronized boolean isStrictMode() { return strictMode; } /** - * Sets the SO_TIMEOUT which is the timeout for waiting for data. - * - * A timeout value of zero is interpreted as an infinite timeout. + * Sets the 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. * * @param newTimeoutInMilliseconds Timeout in milliseconds - * */ public synchronized void setTimeout(int newTimeoutInMilliseconds) { this.timeoutInMilliseconds = newTimeoutInMilliseconds; } /** - * Sets the timeout used when retrieving an HttpConnection from the - * HttpConnectionManager. + * Sets the timeout in milliseconds used when retrieving an + * {@link HttpConnection HTTP connection} from the + * {@link HttpConnectionManager HTTP connection manager}. * * @param timeout the timeout in milliseconds * @@ -241,10 +265,12 @@ } /** - * Sets the timeout until a connection is etablished. A value of 0 means - * the timeout is not used. The default value is 0. - * @see HttpConnection#setConnectionTimeout(int) + * Sets the timeout until a connection is etablished. A timeout value of + * zero means the timeout is not used. The default value is zero. + * * @param newTimeoutInMilliseconds Timeout in milliseconds. + * + * @see HttpConnection#setConnectionTimeout(int) */ public synchronized void setConnectionTimeout(int newTimeoutInMilliseconds) { this.connectionTimeout = newTimeoutInMilliseconds; @@ -253,15 +279,15 @@ // --------------------------------------------------------- Public Methods /** - * @deprecated use hostConfiguration - * - * Sets the host, port and protocol(http) to be used when executing a + * Sets the host, port and default protocol (http) to be used when executing a * method. * * @param host the host to connect to * @param port the port to connect to * * @see #getHostConfiguration() + * + * @deprecated use {@link HostConfiguration} */ public void startSession(String host, int port) { LOG.trace("enter HttpClient.startSession(String, int)"); @@ -269,8 +295,6 @@ } /** - * @deprecated use hostConfiguration - * * Sets the host, port and protocol to be used when executing a method. * * @param host the host to connect to @@ -278,6 +302,8 @@ * @param https when true, create an HTTPS session * * @see #getHostConfiguration() + * + * @deprecated use {@link HostConfiguration} */ public void startSession(String host, int port, boolean https) { LOG.trace("enter HttpClient.startSession(String, int, boolean)"); @@ -291,9 +317,7 @@ } /** - * @deprecated use hostConfiguration and httpState - * - * Sets the host, port, protocol(http) and credentials to be used when + * Sets the host, port, default protocol (http) and credentials to be used when * executing a method. * * @param host the host to connect to @@ -303,6 +327,8 @@ * @see #getHostConfiguration() * @see #getState() * @see #startSession(String, int, Credentials, boolean) + * + * @deprecated use {@link HostConfiguration} and {@link HttpState} */ public void startSession(String host, int port, Credentials creds) { LOG.trace("enter HttpClient.startSession(String, int, Credentials)"); @@ -310,8 +336,6 @@ } /** - * @deprecated use hostConfiguration and httpState - * * Sets the host, port, protocol and credentials to be used when executing a * method. * @@ -322,6 +346,8 @@ * * @see #getHostConfiguration() * @see #getState() + * + * @deprecated use {@link HostConfiguration} and {@link HttpState} */ public void startSession(String host, int port, Credentials creds, boolean https) { LOG.trace("enter HttpClient.startSession(String, int, Credentials, boolean)"); @@ -342,8 +368,6 @@ } /** - * @deprecated use hostConfiguration and httpState - * * Sets the host, port, protocol and credentials to be used when executing a * method using the server specified by the scheme, userinfo, host and port * of the given uri. @@ -358,7 +382,8 @@ * @throws URIException If the URI is bad. * * @see #getHostConfiguration() - * @see #getState() + * + * @deprecated use {@link HostConfiguration} */ public void startSession(URI uri) throws URIException, IllegalStateException { @@ -393,8 +418,6 @@ } /** - * @deprecated use hostConfiguration - * * Sets the host, port and protocol to be used when executing a method. *

* Note that everything but the protocol, host and port of the @@ -406,6 +429,8 @@ * @exception IllegalArgumentException if the protocol is not http or https * * @see #getHostConfiguration() + * + * @deprecated use {@link HostConfiguration} */ public void startSession(URL url) throws IllegalArgumentException { LOG.trace("enter HttpClient.startSession(String, int, Credentials, boolean)"); @@ -417,8 +442,6 @@ } /** - * @deprecated use hostConfiguration and httpState - * * Sets the host, port, protocol and credentials to be used when executing a * method. *

@@ -433,6 +456,8 @@ * * @see #getHostConfiguration() * @see #getState() + * + * @deprecated use {@link HostConfiguration} and {@link HttpState} */ public void startSession(URL url, Credentials creds) throws IllegalArgumentException { @@ -443,8 +468,6 @@ } /** - * @deprecated use hostConfiguration - * * Sets the host, port, protocol(http) and proxy to be used when executing a * method. * @@ -454,6 +477,8 @@ * @param proxyport the proxy port to connect via * * @see #getHostConfiguration() + * + * @deprecated use {@link HostConfiguration} */ public void startSession(String host, int port, String proxyhost, int proxyport) { LOG.trace("enter HttpClient.startSession(String, int, String, int)"); @@ -461,8 +486,6 @@ } /** - * @deprecated use hostConfiguration - * * Sets the host, port, protocol and proxy to be used when executing a * method. * @@ -473,6 +496,8 @@ * @param secure whether or not to connect using HTTPS * * @see #getHostConfiguration() + * + * @deprecated use {@link HostConfiguration} */ public void startSession(String host, int port, String proxyhost, int proxyport, boolean secure) { @@ -484,13 +509,15 @@ } /** - * Executes the given method. + * Executes the given {@link HttpMethod HTTP method}. * - * @param method the {@link HttpMethod} to execute. + * @param method the {@link HttpMethod HTTP method} to execute. * @return the method's response code * - * @throws IOException if an I/O error occurs - * @throws HttpException if a 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. */ public int executeMethod(HttpMethod method) throws IOException, HttpException { @@ -508,14 +535,17 @@ } /** - * Executes the given method. + * Executes the given {@link HttpMethod HTTP method} using custom + * {@link HostConfiguration host configuration}. * - * @param hostConfiguration The configuration to use. - * @param method the {@link HttpMethod} to execute. + * @param hostConfiguration The {@link HostConfiguration host configuration} to use. + * @param method the {@link HttpMethod HTTP method} to execute. * @return the method's response code * - * @throws IOException if an I/O error occurs - * @throws HttpException if a 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. * @since 2.0 */ public int executeMethod(HostConfiguration hostConfiguration, HttpMethod method) @@ -529,17 +559,21 @@ /** - * Executes the given method. - * - * @param hostConfiguration The configuration to use. - * @param method the {@link HttpMethod} to execute. - * @param state the {@link HttpState} to use when executing the method. + * Executes the given {@link HttpMethod HTTP method} using the given custom + * {@link HostConfiguration host configuration} with the given custom + * {@link HttpState HTTP state}. + * + * @param hostConfiguration The {@link HostConfiguration host configuration} to use. + * @param method the {@link HttpMethod HTTP method} to execute. + * @param state the {@link HttpState HTTP state} to use when executing the method. * If null, the state returned by {@link #getState} will be used instead. * * @return the method's response code * - * @throws IOException if an I/O error occurs - * @throws HttpException if a 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. * @since 2.0 */ public int executeMethod(HostConfiguration hostConfiguration, @@ -639,7 +673,7 @@ } /** - * @deprecated this method has no effect. HttpMethod.releaseConnection() + * @deprecated this method has no effect. {@link HttpMethod#releaseConnection()} * should be used to release resources after a HttpMethod has been executed. * * @see HttpMethod#releaseConnection() @@ -648,7 +682,7 @@ } /** - * Return the host that the client is accessing. + * Returns the host that the client is accessing. * * @return The host that the client is accessing, or null if * the session has not been started via startSession. @@ -658,7 +692,7 @@ } /** - * Return the port that the client is accessing. + * Returns the port that the client is accessing. * * @return The port that the client is accessing, or -1 if the session * has not been started via startSession(). @@ -668,8 +702,10 @@ } /** - * Returns the hostConfiguration. - * @return HostConfiguration + * Returns the {@link HostConfiguration host configuration} associated with the + * HttpClient. + * + * @return {@link HostConfiguration host configuration} * * @since 2.0 */ @@ -678,8 +714,10 @@ } /** - * Sets the hostConfiguration. - * @param hostConfiguration The hostConfiguration to set + * Assigns the {@link HostConfiguration host configuration} to use with the + * HttpClient. + * + * @param hostConfiguration The {@link HostConfiguration host configuration} to set * * @since 2.0 */ @@ -688,8 +726,10 @@ } /** - * Returns the httpConnectionManager. - * @return HttpConnectionManager + * Returns the {@link HttpConnectionManager HTTP connection manager} associated + * with the HttpClient. + * + * @return {@link HttpConnectionManager HTTP connection manager} * * @since 2.0 */ @@ -698,8 +738,11 @@ } /** - * Sets the httpConnectionManager. - * @param httpConnectionManager The httpConnectionManager to set + * Assigns the {@link HttpConnectionManager HTTP connection manager} to use with + * the HttpClient. + * + * @param httpConnectionManager The {@link HttpConnectionManager HTTP connection manager} + * to set * * @since 2.0 */