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 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: 155418 $
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 * Sets SO_LINGER with the specified linger time in seconds. The maximum timeout
98 * value is platform specific. Value <tt>0</tt> implies that the option is disabled.
99 * Value <tt>-1</tt> implies that the JRE default is used. The setting only affects
100 * socket close.
101 * <p>
102 * This parameter expects a value of type {@link Integer}.
103 * </p>
104 * @see java.net.SocketOptions#SO_LINGER
105 */
106 public static final String SO_LINGER = "http.socket.linger";
107
108 /***
109 * Determines the timeout until a connection is etablished. A value of zero
110 * means the timeout is not used. The default value is zero.
111 * <p>
112 * This parameter expects a value of type {@link Integer}.
113 * </p>
114 */
115 public static final String CONNECTION_TIMEOUT = "http.connection.timeout";
116
117 /***
118 * Determines whether stale connection check is to be used. Disabling
119 * stale connection check may result in slight performance improvement
120 * at the risk of getting an I/O error when executing a request over a
121 * connection that has been closed at the server side.
122 * <p>
123 * This parameter expects a value of type {@link Boolean}.
124 * </p>
125 */
126 public static final String STALE_CONNECTION_CHECK = "http.connection.stalecheck";
127
128 /***
129 * Creates a new collection of parameters with the collection returned
130 * by {@link #getDefaultParams()} as a parent. The collection will defer
131 * to its parent for a default value if a particular parameter is not
132 * explicitly set in the collection itself.
133 *
134 * @see #getDefaultParams()
135 */
136 public HttpConnectionParams() {
137 super();
138 }
139
140 /***
141 * Returns 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 * @return timeout in milliseconds
147 */
148 public int getSoTimeout() {
149 return getIntParameter(SO_TIMEOUT, 0);
150 }
151
152 /***
153 * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
154 * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
155 * timeout. This value is used when no socket timeout is set in the
156 * {@link HttpMethodParams HTTP method parameters}.
157 *
158 * @param timeout Timeout in milliseconds
159 */
160 public void setSoTimeout(int timeout) {
161 setIntParameter(SO_TIMEOUT, timeout);
162 }
163
164 /***
165 * Determines whether Nagle's algorithm is to be used. The Nagle's algorithm
166 * tries to conserve bandwidth by minimizing the number of segments that are
167 * sent. When applications wish to decrease network latency and increase
168 * performance, they can disable Nagle's algorithm (that is enable TCP_NODELAY).
169 * Data will be sent earlier, at the cost of an increase in bandwidth consumption.
170 *
171 * @param value <tt>true</tt> if the Nagle's algorithm is to NOT be used
172 * (that is enable TCP_NODELAY), <tt>false</tt> otherwise.
173 */
174 public void setTcpNoDelay(boolean value) {
175 setBooleanParameter(TCP_NODELAY, value);
176 }
177
178 /***
179 * Tests if Nagle's algorithm is to be used.
180 *
181 * @return <tt>true</tt> if the Nagle's algorithm is to NOT be used
182 * (that is enable TCP_NODELAY), <tt>false</tt> otherwise.
183 */
184 public boolean getTcpNoDelay() {
185 return getBooleanParameter(TCP_NODELAY, true);
186 }
187
188 /***
189 * Returns 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 * @return the hint size of the send buffer
195 */
196 public int getSendBufferSize() {
197 return getIntParameter(SO_SNDBUF, -1);
198 }
199
200 /***
201 * Sets a hint the size of the underlying buffers used by the platform for
202 * outgoing network I/O. This value is a suggestion to the kernel from the
203 * application about the size of buffers to use for the data to be sent over
204 * the socket.
205 *
206 * @param size the hint size of the send buffer
207 */
208 public void setSendBufferSize(int size) {
209 setIntParameter(SO_SNDBUF, size);
210 }
211
212 /***
213 * Returns 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 * @return the hint size of the send buffer
219 */
220 public int getReceiveBufferSize() {
221 return getIntParameter(SO_RCVBUF, -1);
222 }
223
224 /***
225 * Sets a hint the size of the underlying buffers used by the platform
226 * for incoming network I/O. This value is a suggestion to the kernel from
227 * the application about the size of buffers to use for the data to be received
228 * over the socket.
229 *
230 * @param size the hint size of the send buffer
231 */
232 public void setReceiveBufferSize(int size) {
233 setIntParameter(SO_RCVBUF, size);
234 }
235
236 /***
237 * Returns linger-on-close timeout. Value <tt>0</tt> implies that the option is
238 * disabled. Value <tt>-1</tt> implies that the JRE default is used.
239 *
240 * @return the linger-on-close timeout
241 */
242 public int getLinger() {
243 return getIntParameter(SO_LINGER, -1);
244 }
245
246 /***
247 * Returns linger-on-close timeout. This option disables/enables immediate return
248 * from a close() of a TCP Socket. Enabling this option with a non-zero Integer
249 * timeout means that a close() will block pending the transmission and
250 * acknowledgement of all data written to the peer, at which point the socket is
251 * closed gracefully. Value <tt>0</tt> implies that the option is
252 * disabled. Value <tt>-1</tt> implies that the JRE default is used.
253 *
254 * @param value the linger-on-close timeout
255 */
256 public void setLinger(int value) {
257 setIntParameter(SO_LINGER, value);
258 }
259
260 /***
261 * Returns the timeout until a connection is etablished. A value of zero
262 * means the timeout is not used. The default value is zero.
263 *
264 * @return timeout in milliseconds.
265 */
266 public int getConnectionTimeout() {
267 return getIntParameter(CONNECTION_TIMEOUT, 0);
268 }
269
270 /***
271 * Sets the timeout until a connection is etablished. A value of zero
272 * means the timeout is not used. The default value is zero.
273 *
274 * @param timeout Timeout in milliseconds.
275 */
276 public void setConnectionTimeout(int timeout) {
277 setIntParameter(CONNECTION_TIMEOUT, timeout);
278 }
279
280 /***
281 * Tests whether stale connection check is to be used. Disabling
282 * stale connection check may result in slight performance improvement
283 * at the risk of getting an I/O error when executing a request over a
284 * connection that has been closed at the server side.
285 *
286 * @return <tt>true</tt> if stale connection check is to be used,
287 * <tt>false</tt> otherwise.
288 */
289 public boolean isStaleCheckingEnabled() {
290 return getBooleanParameter(STALE_CONNECTION_CHECK, true);
291 }
292
293 /***
294 * Defines whether stale connection check is to be used. Disabling
295 * stale connection check may result in slight performance improvement
296 * at the risk of getting an I/O error when executing a request over a
297 * connection that has been closed at the server side.
298 *
299 * @param value <tt>true</tt> if stale connection check is to be used,
300 * <tt>false</tt> otherwise.
301 */
302 public void setStaleCheckingEnabled(boolean value) {
303 setBooleanParameter(STALE_CONNECTION_CHECK, value);
304 }
305 }