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 usingSimpleHttpConnectionManager.
+ * 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
*/