001 /**
002 * Copyright (C) 2009-2013 Barchart, Inc. <http://www.barchart.com/>
003 *
004 * All rights reserved. Licensed under the OSI BSD License.
005 *
006 * http://www.opensource.org/licenses/bsd-license.php
007 */
008 package com.barchart.udt.net;
009
010 import java.io.IOException;
011 import java.net.InetAddress;
012 import java.net.Socket;
013 import java.net.SocketAddress;
014 import java.net.SocketException;
015 import java.net.SocketTimeoutException;
016 import java.nio.channels.ServerSocketChannel;
017
018 /**
019 * compatibility verification interface
020 */
021 public interface IceServerSocket {
022
023 /**
024 *
025 * Binds the <code>ServerSocket</code> to a specific address (IP address and
026 * port number).
027 * <p>
028 * If the address is <code>null</code>, then the system will pick up an
029 * ephemeral port and a valid local address to bind the socket.
030 * <p>
031 *
032 * @param endpoint
033 * The IP address & port number to bind to.
034 * @throws IOException
035 * if the bind operation fails, or if the socket is already
036 * bound.
037 * @throws SecurityException
038 * if a <code>SecurityManager</code> is present and its
039 * <code>checkListen</code> method doesn't allow the operation.
040 * @throws IllegalArgumentException
041 * if endpoint is a SocketAddress subclass not supported by this
042 * socket
043 * @since 1.4
044 */
045 void bind(SocketAddress endpoint) throws IOException;
046
047 /**
048 *
049 * Binds the <code>ServerSocket</code> to a specific address (IP address and
050 * port number).
051 * <p>
052 * If the address is <code>null</code>, then the system will pick up an
053 * ephemeral port and a valid local address to bind the socket.
054 * <P>
055 * The <code>backlog</code> argument must be a positive value greater than
056 * 0. If the value passed if equal or less than 0, then the default value
057 * will be assumed.
058 *
059 * @param endpoint
060 * The IP address & port number to bind to.
061 * @param backlog
062 * The listen backlog length.
063 * @throws IOException
064 * if the bind operation fails, or if the socket is already
065 * bound.
066 * @throws SecurityException
067 * if a <code>SecurityManager</code> is present and its
068 * <code>checkListen</code> method doesn't allow the operation.
069 * @throws IllegalArgumentException
070 * if endpoint is a SocketAddress subclass not supported by this
071 * socket
072 * @since 1.4
073 */
074 void bind(SocketAddress endpoint, int backlog) throws IOException;
075
076 /**
077 * Returns the local address of this server socket.
078 *
079 * @return the address to which this socket is bound, or <code>null</code>
080 * if the socket is unbound.
081 */
082 InetAddress getInetAddress();
083
084 /**
085 * Returns the port on which this socket is listening.
086 *
087 * @return the port number to which this socket is listening or -1 if the
088 * socket is not bound yet.
089 */
090 int getLocalPort();
091
092 /**
093 * Returns the address of the endpoint this socket is bound to, or
094 * <code>null</code> if it is not bound yet.
095 *
096 * @return a <code>SocketAddress</code> representing the local endpoint of
097 * this socket, or <code>null</code> if it is not bound yet.
098 * @see #getInetAddress()
099 * @see #getLocalPort()
100 * @see #bind(SocketAddress)
101 * @since 1.4
102 */
103
104 SocketAddress getLocalSocketAddress();
105
106 /**
107 * Listens for a connection to be made to this socket and accepts it. The
108 * method blocks until a connection is made.
109 *
110 * <p>
111 * A new Socket <code>s</code> is created and, if there is a security
112 * manager, the security manager's <code>checkAccept</code> method is called
113 * with <code>s.getInetAddress().getHostAddress()</code> and
114 * <code>s.getPort()</code> as its arguments to ensure the operation is
115 * allowed. This could result in a SecurityException.
116 *
117 * @exception IOException
118 * if an I/O error occurs when waiting for a connection.
119 * @exception SecurityException
120 * if a security manager exists and its
121 * <code>checkAccept</code> method doesn't allow the
122 * operation.
123 * @exception SocketTimeoutException
124 * if a timeout was previously set with setSoTimeout and the
125 * timeout has been reached.
126 * @exception java.nio.channels.IllegalBlockingModeException
127 * if this socket has an associated channel, the channel is
128 * in non-blocking mode, and there is no connection ready to
129 * be accepted
130 *
131 * @return the new Socket
132 * @see SecurityManager#checkAccept revised 1.4 spec JSR-51
133 */
134 Socket accept() throws IOException;
135
136 /**
137 * Closes this socket.
138 *
139 * Any thread currently blocked in {@link #accept()} will throw a
140 * {@link SocketException}.
141 *
142 * <p>
143 * If this socket has an associated channel then the channel is closed as
144 * well.
145 *
146 * @exception IOException
147 * if an I/O error occurs when closing the socket. revised
148 * 1.4 spec JSR-51
149 */
150 void close() throws IOException;
151
152 /**
153 * Returns the unique {@link java.nio.channels.ServerSocketChannel} object
154 * associated with this socket, if any.
155 *
156 * <p>
157 * A server socket will have a channel if, and only if, the channel itself
158 * was created via the {@link java.nio.channels.ServerSocketChannel#open
159 * ServerSocketChannel.open} method.
160 *
161 * @return the server-socket channel associated with this socket, or
162 * <tt>null</tt> if this socket was not created for a channel
163 *
164 * @since 1.4 spec JSR-51
165 */
166 ServerSocketChannel getChannel();
167
168 /**
169 * Returns the binding state of the ServerSocket.
170 *
171 * @return true if the ServerSocket succesfuly bound to an address
172 * @since 1.4
173 */
174 boolean isBound();
175
176 /**
177 * Returns the closed state of the ServerSocket.
178 *
179 * @return true if the socket has been closed
180 * @since 1.4
181 */
182 boolean isClosed();
183
184 /**
185 * Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds.
186 * With this option set to a non-zero timeout, a call to accept() for this
187 * ServerSocket will block for only this amount of time. If the timeout
188 * expires, a <B>java.net.SocketTimeoutException</B> is raised, though the
189 * ServerSocket is still valid. The option <B>must</B> be enabled prior to
190 * entering the blocking operation to have effect. The timeout must be > 0.
191 * A timeout of zero is interpreted as an infinite timeout.
192 *
193 * @param timeout
194 * the specified timeout, in milliseconds
195 * @exception SocketException
196 * if there is an error in the underlying protocol, such as a
197 * TCP error.
198 * @since JDK1.1
199 * @see #getSoTimeout()
200 */
201 void setSoTimeout(int timeout) throws SocketException;
202
203 /**
204 * Retrieve setting for SO_TIMEOUT. 0 returns implies that the option is
205 * disabled (i.e., timeout of infinity).
206 *
207 * @return the SO_TIMEOUT value
208 * @exception IOException
209 * if an I/O error occurs
210 * @since JDK1.1
211 * @see #setSoTimeout(int)
212 */
213 int getSoTimeout() throws IOException;
214
215 /**
216 * Enable/disable the SO_REUSEADDR socket option.
217 * <p>
218 * When a TCP connection is closed the connection may remain in a timeout
219 * state for a period of time after the connection is closed (typically
220 * known as the <tt>TIME_WAIT</tt> state or <tt>2MSL</tt> wait state). For
221 * applications using a well known socket address or port it may not be
222 * possible to bind a socket to the required <tt>SocketAddress</tt> if there
223 * is a connection in the timeout state involving the socket address or
224 * port.
225 * <p>
226 * Enabling <tt>SO_REUSEADDR</tt> prior to binding the socket using
227 * {@link #bind(SocketAddress)} allows the socket to be bound even though a
228 * previous connection is in a timeout state.
229 * <p>
230 * When a <tt>ServerSocket</tt> is created the initial setting of
231 * <tt>SO_REUSEADDR</tt> is not defined. Applications can use
232 * {@link #getReuseAddress()} to determine the initial setting of
233 * <tt>SO_REUSEADDR</tt>.
234 * <p>
235 * The behaviour when <tt>SO_REUSEADDR</tt> is enabled or disabled after a
236 * socket is bound (See {@link #isBound()}) is not defined.
237 *
238 * @param on
239 * whether to enable or disable the socket option
240 * @exception SocketException
241 * if an error occurs enabling or disabling the
242 * <tt>SO_RESUEADDR</tt> socket option, or the socket is
243 * closed.
244 * @since 1.4
245 * @see #getReuseAddress()
246 * @see #bind(SocketAddress)
247 * @see #isBound()
248 * @see #isClosed()
249 */
250 void setReuseAddress(boolean on) throws SocketException;
251
252 /**
253 * Tests if SO_REUSEADDR is enabled.
254 *
255 * @return a <code>boolean</code> indicating whether or not SO_REUSEADDR is
256 * enabled.
257 * @exception SocketException
258 * if there is an error in the underlying protocol, such as a
259 * TCP error.
260 * @since 1.4
261 * @see #setReuseAddress(boolean)
262 */
263 boolean getReuseAddress() throws SocketException;
264
265 /**
266 * Returns the implementation address and implementation port of this socket
267 * as a <code>String</code>.
268 *
269 * @return a string representation of this socket.
270 */
271 @Override
272 String toString();
273
274 /**
275 * Sets a default proposed value for the SO_RCVBUF option for sockets
276 * accepted from this <tt>ServerSocket</tt>. The value actually set in the
277 * accepted socket must be determined by calling
278 * {@link Socket#getReceiveBufferSize()} after the socket is returned by
279 * {@link #accept()}.
280 * <p>
281 * The value of SO_RCVBUF is used both to set the size of the internal
282 * socket receive buffer, and to set the size of the TCP receive window that
283 * is advertized to the remote peer.
284 * <p>
285 * It is possible to change the value subsequently, by calling
286 * {@link Socket#setReceiveBufferSize(int)}. However, if the application
287 * wishes to allow a receive window larger than 64K bytes, as defined by
288 * RFC1323 then the proposed value must be set in the ServerSocket
289 * <B>before</B> it is bound to a local address. This implies, that the
290 * ServerSocket must be created with the no-argument constructor, then
291 * setReceiveBufferSize() must be called and lastly the ServerSocket is
292 * bound to an address by calling bind().
293 * <p>
294 * Failure to do this will not cause an error, and the buffer size may be
295 * set to the requested value but the TCP receive window in sockets accepted
296 * from this ServerSocket will be no larger than 64K bytes.
297 *
298 * @exception SocketException
299 * if there is an error in the underlying protocol, such as a
300 * TCP error.
301 *
302 * @param size
303 * the size to which to set the receive buffer size. This value
304 * must be greater than 0.
305 *
306 * @exception IllegalArgumentException
307 * if the value is 0 or is negative.
308 *
309 * @since 1.4
310 * @see #getReceiveBufferSize
311 */
312 void setReceiveBufferSize(int size) throws SocketException;
313
314 /**
315 * Gets the value of the SO_RCVBUF option for this <tt>ServerSocket</tt>,
316 * that is the proposed buffer size that will be used for Sockets accepted
317 * from this <tt>ServerSocket</tt>.
318 *
319 * <p>
320 * Note, the value actually set in the accepted socket is determined by
321 * calling {@link Socket#getReceiveBufferSize()}.
322 *
323 * @return the value of the SO_RCVBUF option for this <tt>Socket</tt>.
324 * @exception SocketException
325 * if there is an error in the underlying protocol, such as a
326 * TCP error.
327 * @see #setReceiveBufferSize(int)
328 * @since 1.4
329 */
330 int getReceiveBufferSize() throws SocketException;
331
332 /**
333 * Sets performance preferences for this ServerSocket.
334 *
335 * <p>
336 * Sockets use the TCP/IP protocol by default. Some implementations may
337 * offer alternative protocols which have different performance
338 * characteristics than TCP/IP. This method allows the application to
339 * express its own preferences as to how these tradeoffs should be made when
340 * the implementation chooses from the available protocols.
341 *
342 * <p>
343 * Performance preferences are described by three integers whose values
344 * indicate the relative importance of short connection time, low latency,
345 * and high bandwidth. The absolute values of the integers are irrelevant;
346 * in order to choose a protocol the values are simply compared, with larger
347 * values indicating stronger preferences. If the application prefers short
348 * connection time over both low latency and high bandwidth, for example,
349 * then it could invoke this method with the values <tt>(1, 0, 0)</tt>. If
350 * the application prefers high bandwidth above low latency, and low latency
351 * above short connection time, then it could invoke this method with the
352 * values <tt>(0, 1, 2)</tt>.
353 *
354 * <p>
355 * Invoking this method after this socket has been bound will have no
356 * effect. This implies that in order to use this capability requires the
357 * socket to be created with the no-argument constructor.
358 *
359 * @param connectionTime
360 * An <tt>int</tt> expressing the relative importance of a short
361 * connection time
362 *
363 * @param latency
364 * An <tt>int</tt> expressing the relative importance of low
365 * latency
366 *
367 * @param bandwidth
368 * An <tt>int</tt> expressing the relative importance of high
369 * bandwidth
370 *
371 * @since 1.5
372 */
373 void setPerformancePreferences(int connectionTime, int latency,
374 int bandwidth);
375
376 }