View Javadoc

1   /*
2    * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/params/HttpConnectionParams.java,v 1.5 2004/05/13 04:01:22 mbecke Exp $
3    * $Revision: 1.5 $
4    * $Date: 2004/05/13 04:01:22 $
5    *
6    * ====================================================================
7    *
8    *  Copyright 1999-2004 The Apache Software Foundation
9    *
10   *  Licensed under the Apache License, Version 2.0 (the "License");
11   *  you may not use this file except in compliance with the License.
12   *  You may obtain a copy of the License at
13   *
14   *      http://www.apache.org/licenses/LICENSE-2.0
15   *
16   *  Unless required by applicable law or agreed to in writing, software
17   *  distributed under the License is distributed on an "AS IS" BASIS,
18   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19   *  See the License for the specific language governing permissions and
20   *  limitations under the License.
21   * ====================================================================
22   *
23   * This software consists of voluntary contributions made by many
24   * individuals on behalf of the Apache Software Foundation.  For more
25   * information on the Apache Software Foundation, please see
26   * <http://www.apache.org/>.
27   *
28   */
29  
30  package org.apache.commons.httpclient.params;
31  
32  /***
33   * This class represents a collection of HTTP protocol parameters applicable to 
34   * {@link org.apache.commons.httpclient.HttpConnection HTTP connections}. 
35   * Protocol parameters may be linked together to form a hierarchy. If a particular 
36   * parameter value has not been explicitly defined in the collection itself, its 
37   * value will be drawn from the parent collection of parameters.
38   * 
39   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
40   * 
41   * @version $Revision: 1.5 $
42   * 
43   * @since 3.0
44   */
45  public class HttpConnectionParams extends DefaultHttpParams {
46  
47      /***
48       * Defines the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
49       * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
50       * timeout. This value is used when no socket timeout is set in the 
51       * {@link HttpMethodParams HTTP method parameters}. 
52       * <p>
53       * This parameter expects a value of type {@link Integer}.
54       * </p>
55       * @see java.net.SocketOptions#SO_TIMEOUT
56       */
57      public static final String SO_TIMEOUT = "http.socket.timeout"; 
58  
59      /***
60       * Determines whether Nagle's algorithm is to be used. The Nagle's algorithm 
61       * tries to conserve bandwidth by minimizing the number of segments that are 
62       * sent. When applications wish to decrease network latency and increase 
63       * performance, they can disable Nagle's algorithm (that is enable TCP_NODELAY). 
64       * Data will be sent earlier, at the cost of an increase in bandwidth consumption. 
65       * <p>
66       * This parameter expects a value of type {@link Boolean}.
67       * </p>
68       * @see java.net.SocketOptions#TCP_NODELAY
69       */
70      public static final String TCP_NODELAY = "http.tcp.nodelay"; 
71  
72      /***
73       * Determines a hint the size of the underlying buffers used by the platform 
74       * for outgoing network I/O. This value is a suggestion to the kernel from 
75       * the application about the size of buffers to use for the data to be sent 
76       * over the socket.
77       * <p>
78       * This parameter expects a value of type {@link Integer}.
79       * </p>
80       * @see java.net.SocketOptions#SO_SNDBUF
81       */
82      public static final String SO_SNDBUF = "http.socket.sendbuffer"; 
83  
84      /***
85       * Determines a hint the size of the underlying buffers used by the platform 
86       * for incoming network I/O. This value is a suggestion to the kernel from 
87       * the application about the size of buffers to use for the data to be received 
88       * over the socket.  
89       * <p>
90       * This parameter expects a value of type {@link Integer}.
91       * </p>
92       * @see java.net.SocketOptions#SO_RCVBUF
93       */
94      public static final String SO_RCVBUF = "http.socket.receivebuffer"; 
95  
96      /***
97       * Determines the timeout until a connection is etablished. A value of zero 
98       * means the timeout is not used. The default value is zero.
99       * <p>
100      * This parameter expects a value of type {@link Integer}.
101      * </p>
102      */
103     public static final String CONNECTION_TIMEOUT = "http.connection.timeout"; 
104 
105     /***
106      * Determines whether stale connection check is to be used. Disabling 
107      * stale connection check may result in slight performance improvement 
108      * at the risk of getting an I/O error when executing a request over a
109      * connection that has been closed at the server side. 
110      * <p>
111      * This parameter expects a value of type {@link Boolean}.
112      * </p>
113      */
114     public static final String STALE_CONNECTION_CHECK = "http.connection.stalecheck"; 
115 
116     /***
117      * Creates a new collection of parameters with the collection returned
118      * by {@link #getDefaultParams()} as a parent. The collection will defer
119      * to its parent for a default value if a particular parameter is not 
120      * explicitly set in the collection itself.
121      * 
122      * @see #getDefaultParams()
123      */
124     public HttpConnectionParams() {
125         super();
126     }
127 
128     /***
129      * Returns the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
130      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
131      * timeout. This value is used when no socket timeout is set in the 
132      * {@link HttpMethodParams HTTP method parameters}. 
133      *
134      * @return timeout in milliseconds
135      */
136     public int getSoTimeout() {
137         return getIntParameter(SO_TIMEOUT, 0);
138     }
139 
140     /***
141      * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
142      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
143      * timeout. This value is used when no socket timeout is set in the 
144      * {@link HttpMethodParams HTTP method parameters}. 
145      *
146      * @param timeout Timeout in milliseconds
147      */
148     public void setSoTimeout(int timeout) {
149         setIntParameter(SO_TIMEOUT, timeout);
150     }
151 
152     /***
153      * Determines whether Nagle's algorithm is to be used. The Nagle's algorithm 
154      * tries to conserve bandwidth by minimizing the number of segments that are 
155      * sent. When applications wish to decrease network latency and increase 
156      * performance, they can disable Nagle's algorithm (that is enable TCP_NODELAY). 
157      * Data will be sent earlier, at the cost of an increase in bandwidth consumption. 
158      *
159      * @param value <tt>true</tt> if the Nagle's algorithm is to NOT be used
160      *   (that is enable TCP_NODELAY), <tt>false</tt> otherwise.
161      */
162     public void setTcpNoDelay(boolean value) {
163         setBooleanParameter(TCP_NODELAY, value);
164     }
165 
166     /***
167      * Tests if Nagle's algorithm is to be used.  
168      *
169      * @return <tt>true</tt> if the Nagle's algorithm is to NOT be used
170      *   (that is enable TCP_NODELAY), <tt>false</tt> otherwise.
171      */
172     public boolean getTcpNoDelay() {
173         return getBooleanParameter(TCP_NODELAY, true);
174     }
175 
176     /***
177      * Returns a hint the size of the underlying buffers used by the platform for 
178      * outgoing network I/O. This value is a suggestion to the kernel from the 
179      * application about the size of buffers to use for the data to be sent over 
180      * the socket.
181      *
182      * @return the hint size of the send buffer
183      */
184     public int getSendBufferSize() {
185         return getIntParameter(SO_SNDBUF, -1);
186     }
187 
188     /***
189      * Sets a hint the size of the underlying buffers used by the platform for 
190      * outgoing network I/O. This value is a suggestion to the kernel from the 
191      * application about the size of buffers to use for the data to be sent over 
192      * the socket.
193      *
194      * @param size the hint size of the send buffer
195      */
196     public void setSendBufferSize(int size) {
197         setIntParameter(SO_SNDBUF, size);
198     }
199 
200     /***
201      * Returns a hint the size of the underlying buffers used by the platform 
202      * for incoming network I/O. This value is a suggestion to the kernel from 
203      * the application about the size of buffers to use for the data to be received 
204      * over the socket.  
205      *
206      * @return the hint size of the send buffer
207      */
208     public int getReceiveBufferSize() {
209         return getIntParameter(SO_RCVBUF, -1);
210     }
211 
212     /***
213      * Sets a hint the size of the underlying buffers used by the platform 
214      * for incoming network I/O. This value is a suggestion to the kernel from 
215      * the application about the size of buffers to use for the data to be received 
216      * over the socket.  
217      *
218      * @param size the hint size of the send buffer
219      */
220     public void setReceiveBufferSize(int size) {
221         setIntParameter(SO_RCVBUF, size);
222     }
223 
224     /***
225      * Returns the timeout until a connection is etablished. A value of zero 
226      * means the timeout is not used. The default value is zero.
227      * 
228      * @return timeout in milliseconds.
229      */
230     public int getConnectionTimeout() {
231         return getIntParameter(CONNECTION_TIMEOUT, 0);
232     }
233 
234     /***
235      * Sets the timeout until a connection is etablished. A value of zero 
236      * means the timeout is not used. The default value is zero.
237      * 
238      * @param timeout Timeout in milliseconds.
239      */
240     public void setConnectionTimeout(int timeout) {
241         setIntParameter(CONNECTION_TIMEOUT, timeout);
242     }
243     
244     /***
245      * Tests whether stale connection check is to be used. Disabling 
246      * stale connection check may result in slight performance improvement 
247      * at the risk of getting an I/O error when executing a request over a
248      * connection that has been closed at the server side. 
249      * 
250      * @return <tt>true</tt> if stale connection check is to be used, 
251      *   <tt>false</tt> otherwise.
252      */
253     public boolean isStaleCheckingEnabled() {
254         return getBooleanParameter(STALE_CONNECTION_CHECK, true);
255     }
256 
257     /***
258      * Defines whether stale connection check is to be used. Disabling 
259      * stale connection check may result in slight performance improvement 
260      * at the risk of getting an I/O error when executing a request over a
261      * connection that has been closed at the server side. 
262      * 
263      * @param value <tt>true</tt> if stale connection check is to be used, 
264      *   <tt>false</tt> otherwise.
265      */
266     public void setStaleCheckingEnabled(boolean value) {
267         setBooleanParameter(STALE_CONNECTION_CHECK, value);
268     }
269 }