1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31 package org.apache.commons.httpclient.params;
32
33 /***
34 * This class represents a collection of HTTP protocol parameters applicable to
35 * {@link org.apache.commons.httpclient.HttpConnection HTTP connections}.
36 * Protocol parameters may be linked together to form a hierarchy. If a particular
37 * parameter value has not been explicitly defined in the collection itself, its
38 * value will be drawn from the parent collection of parameters.
39 *
40 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
41 *
42 * @version $Revision$
43 *
44 * @since 3.0
45 */
46 public class HttpConnectionParams extends DefaultHttpParams {
47
48 /***
49 * Defines the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
50 * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
51 * timeout. This value is used when no socket timeout is set in the
52 * {@link HttpMethodParams HTTP method parameters}.
53 * <p>
54 * This parameter expects a value of type {@link Integer}.
55 * </p>
56 * @see java.net.SocketOptions#SO_TIMEOUT
57 */
58 public static final String SO_TIMEOUT = "http.socket.timeout";
59
60 /***
61 * Determines whether Nagle's algorithm is to be used. The Nagle's algorithm
62 * tries to conserve bandwidth by minimizing the number of segments that are
63 * sent. When applications wish to decrease network latency and increase
64 * performance, they can disable Nagle's algorithm (that is enable TCP_NODELAY).
65 * Data will be sent earlier, at the cost of an increase in bandwidth consumption.
66 * <p>
67 * This parameter expects a value of type {@link Boolean}.
68 * </p>
69 * @see java.net.SocketOptions#TCP_NODELAY
70 */
71 public static final String TCP_NODELAY = "http.tcp.nodelay";
72
73 /***
74 * Determines a hint the size of the underlying buffers used by the platform
75 * for outgoing network I/O. This value is a suggestion to the kernel from
76 * the application about the size of buffers to use for the data to be sent
77 * over the socket.
78 * <p>
79 * This parameter expects a value of type {@link Integer}.
80 * </p>
81 * @see java.net.SocketOptions#SO_SNDBUF
82 */
83 public static final String SO_SNDBUF = "http.socket.sendbuffer";
84
85 /***
86 * Determines a hint the size of the underlying buffers used by the platform
87 * for incoming network I/O. This value is a suggestion to the kernel from
88 * the application about the size of buffers to use for the data to be received
89 * over the socket.
90 * <p>
91 * This parameter expects a value of type {@link Integer}.
92 * </p>
93 * @see java.net.SocketOptions#SO_RCVBUF
94 */
95 public static final String SO_RCVBUF = "http.socket.receivebuffer";
96
97 /***
98 * Sets SO_LINGER with the specified linger time in seconds. The maximum timeout
99 * value is platform specific. Value <tt>0</tt> implies that the option is disabled.
100 * Value <tt>-1</tt> implies that the JRE default is used. The setting only affects
101 * socket close.
102 * <p>
103 * This parameter expects a value of type {@link Integer}.
104 * </p>
105 * @see java.net.SocketOptions#SO_LINGER
106 */
107 public static final String SO_LINGER = "http.socket.linger";
108
109 /***
110 * Determines the timeout until a connection is etablished. A value of zero
111 * means the timeout is not used. The default value is zero.
112 * <p>
113 * This parameter expects a value of type {@link Integer}.
114 * </p>
115 */
116 public static final String CONNECTION_TIMEOUT = "http.connection.timeout";
117
118 /***
119 * Determines whether stale connection check is to be used. Disabling
120 * stale connection check may result in slight performance improvement
121 * at the risk of getting an I/O error when executing a request over a
122 * connection that has been closed at the server side.
123 * <p>
124 * This parameter expects a value of type {@link Boolean}.
125 * </p>
126 */
127 public static final String STALE_CONNECTION_CHECK = "http.connection.stalecheck";
128
129 /***
130 * Creates a new collection of parameters with the collection returned
131 * by {@link #getDefaultParams()} as a parent. The collection will defer
132 * to its parent for a default value if a particular parameter is not
133 * explicitly set in the collection itself.
134 *
135 * @see #getDefaultParams()
136 */
137 public HttpConnectionParams() {
138 super();
139 }
140
141 /***
142 * Returns the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
143 * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
144 * timeout. This value is used when no socket timeout is set in the
145 * {@link HttpMethodParams HTTP method parameters}.
146 *
147 * @return timeout in milliseconds
148 */
149 public int getSoTimeout() {
150 return getIntParameter(SO_TIMEOUT, 0);
151 }
152
153 /***
154 * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
155 * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
156 * timeout. This value is used when no socket timeout is set in the
157 * {@link HttpMethodParams HTTP method parameters}.
158 *
159 * @param timeout Timeout in milliseconds
160 */
161 public void setSoTimeout(int timeout) {
162 setIntParameter(SO_TIMEOUT, timeout);
163 }
164
165 /***
166 * Determines whether Nagle's algorithm is to be used. The Nagle's algorithm
167 * tries to conserve bandwidth by minimizing the number of segments that are
168 * sent. When applications wish to decrease network latency and increase
169 * performance, they can disable Nagle's algorithm (that is enable TCP_NODELAY).
170 * Data will be sent earlier, at the cost of an increase in bandwidth consumption.
171 *
172 * @param value <tt>true</tt> if the Nagle's algorithm is to NOT be used
173 * (that is enable TCP_NODELAY), <tt>false</tt> otherwise.
174 */
175 public void setTcpNoDelay(boolean value) {
176 setBooleanParameter(TCP_NODELAY, value);
177 }
178
179 /***
180 * Tests if Nagle's algorithm is to be used.
181 *
182 * @return <tt>true</tt> if the Nagle's algorithm is to NOT be used
183 * (that is enable TCP_NODELAY), <tt>false</tt> otherwise.
184 */
185 public boolean getTcpNoDelay() {
186 return getBooleanParameter(TCP_NODELAY, true);
187 }
188
189 /***
190 * Returns a hint the size of the underlying buffers used by the platform for
191 * outgoing network I/O. This value is a suggestion to the kernel from the
192 * application about the size of buffers to use for the data to be sent over
193 * the socket.
194 *
195 * @return the hint size of the send buffer
196 */
197 public int getSendBufferSize() {
198 return getIntParameter(SO_SNDBUF, -1);
199 }
200
201 /***
202 * Sets a hint the size of the underlying buffers used by the platform for
203 * outgoing network I/O. This value is a suggestion to the kernel from the
204 * application about the size of buffers to use for the data to be sent over
205 * the socket.
206 *
207 * @param size the hint size of the send buffer
208 */
209 public void setSendBufferSize(int size) {
210 setIntParameter(SO_SNDBUF, size);
211 }
212
213 /***
214 * Returns a hint the size of the underlying buffers used by the platform
215 * for incoming network I/O. This value is a suggestion to the kernel from
216 * the application about the size of buffers to use for the data to be received
217 * over the socket.
218 *
219 * @return the hint size of the send buffer
220 */
221 public int getReceiveBufferSize() {
222 return getIntParameter(SO_RCVBUF, -1);
223 }
224
225 /***
226 * Sets a hint the size of the underlying buffers used by the platform
227 * for incoming network I/O. This value is a suggestion to the kernel from
228 * the application about the size of buffers to use for the data to be received
229 * over the socket.
230 *
231 * @param size the hint size of the send buffer
232 */
233 public void setReceiveBufferSize(int size) {
234 setIntParameter(SO_RCVBUF, size);
235 }
236
237 /***
238 * Returns linger-on-close timeout. Value <tt>0</tt> implies that the option is
239 * disabled. Value <tt>-1</tt> implies that the JRE default is used.
240 *
241 * @return the linger-on-close timeout
242 */
243 public int getLinger() {
244 return getIntParameter(SO_LINGER, -1);
245 }
246
247 /***
248 * Returns linger-on-close timeout. This option disables/enables immediate return
249 * from a close() of a TCP Socket. Enabling this option with a non-zero Integer
250 * timeout means that a close() will block pending the transmission and
251 * acknowledgement of all data written to the peer, at which point the socket is
252 * closed gracefully. Value <tt>0</tt> implies that the option is
253 * disabled. Value <tt>-1</tt> implies that the JRE default is used.
254 *
255 * @param value the linger-on-close timeout
256 */
257 public void setLinger(int value) {
258 setIntParameter(SO_LINGER, value);
259 }
260
261 /***
262 * Returns the timeout until a connection is etablished. A value of zero
263 * means the timeout is not used. The default value is zero.
264 *
265 * @return timeout in milliseconds.
266 */
267 public int getConnectionTimeout() {
268 return getIntParameter(CONNECTION_TIMEOUT, 0);
269 }
270
271 /***
272 * Sets the timeout until a connection is etablished. A value of zero
273 * means the timeout is not used. The default value is zero.
274 *
275 * @param timeout Timeout in milliseconds.
276 */
277 public void setConnectionTimeout(int timeout) {
278 setIntParameter(CONNECTION_TIMEOUT, timeout);
279 }
280
281 /***
282 * Tests whether stale connection check is to be used. Disabling
283 * stale connection check may result in slight performance improvement
284 * at the risk of getting an I/O error when executing a request over a
285 * connection that has been closed at the server side.
286 *
287 * @return <tt>true</tt> if stale connection check is to be used,
288 * <tt>false</tt> otherwise.
289 */
290 public boolean isStaleCheckingEnabled() {
291 return getBooleanParameter(STALE_CONNECTION_CHECK, true);
292 }
293
294 /***
295 * Defines whether stale connection check is to be used. Disabling
296 * stale connection check may result in slight performance improvement
297 * at the risk of getting an I/O error when executing a request over a
298 * connection that has been closed at the server side.
299 *
300 * @param value <tt>true</tt> if stale connection check is to be used,
301 * <tt>false</tt> otherwise.
302 */
303 public void setStaleCheckingEnabled(boolean value) {
304 setBooleanParameter(STALE_CONNECTION_CHECK, value);
305 }
306 }