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.DatagramPacket;
012 import java.net.InetAddress;
013 import java.net.PortUnreachableException;
014 import java.net.SocketAddress;
015 import java.net.SocketException;
016 import java.net.SocketTimeoutException;
017 import java.nio.channels.DatagramChannel;
018
019 /**
020 * compatibility verification interface
021 */
022 public interface IceDatagramSocket {
023
024 /**
025 * Binds this DatagramSocket to a specific address & port.
026 * <p>
027 * If the address is <code>null</code>, then the system will pick up an
028 * ephemeral port and a valid local address to bind the socket.
029 * <p>
030 *
031 * @param addr
032 * The address & port to bind to.
033 * @throws SocketException
034 * if any error happens during the bind, or if the socket is
035 * already bound.
036 * @throws SecurityException
037 * if a security manager exists and its <code>checkListen</code>
038 * method doesn't allow the operation.
039 * @throws IllegalArgumentException
040 * if addr is a SocketAddress subclass not supported by this
041 * socket.
042 * @since 1.4
043 */
044 void bind(SocketAddress addr) throws SocketException;
045
046 /**
047 * Connects the socket to a remote address for this socket. When a socket is
048 * connected to a remote address, packets may only be sent to or received
049 * from that address. By default a datagram socket is not connected.
050 *
051 * <p>
052 * If the remote destination to which the socket is connected does not
053 * exist, or is otherwise unreachable, and if an ICMP destination
054 * unreachable packet has been received for that address, then a subsequent
055 * call to send or receive may throw a PortUnreachableException. Note, there
056 * is no guarantee that the exception will be thrown.
057 *
058 * <p>
059 * A caller's permission to send and receive datagrams to a given host and
060 * port are checked at connect time. When a socket is connected, receive and
061 * send <b>will not perform any security checks</b> on incoming and outgoing
062 * packets, other than matching the packet's and the socket's address and
063 * port. On a send operation, if the packet's address is set and the
064 * packet's address and the socket's address do not match, an
065 * IllegalArgumentException will be thrown. A socket connected to a
066 * multicast address may only be used to send packets.
067 *
068 * @param address
069 * the remote address for the socket
070 *
071 * @param port
072 * the remote port for the socket.
073 *
074 * @exception IllegalArgumentException
075 * if the address is null, or the port is out of range.
076 *
077 * @exception SecurityException
078 * if the caller is not allowed to send datagrams to and
079 * receive datagrams from the address and port.
080 *
081 * @see #disconnect
082 * @see #send
083 * @see #receive
084 */
085 void connect(InetAddress address, int port);
086
087 /**
088 * Connects this socket to a remote socket address (IP address + port
089 * number).
090 * <p>
091 *
092 * @param addr
093 * The remote address.
094 * @throws SocketException
095 * if the connect fails
096 * @throws IllegalArgumentException
097 * if addr is null or addr is a SocketAddress subclass not
098 * supported by this socket
099 * @since 1.4
100 * @see #connect
101 */
102 void connect(SocketAddress addr) throws SocketException;
103
104 /**
105 * Disconnects the socket. This does nothing if the socket is not connected.
106 *
107 * @see #connect
108 */
109 void disconnect();
110
111 /**
112 * Returns the binding state of the socket.
113 *
114 * @return true if the socket succesfuly bound to an address
115 * @since 1.4
116 */
117 boolean isBound();
118
119 /**
120 * Returns the connection state of the socket.
121 *
122 * @return true if the socket succesfuly connected to a server
123 * @since 1.4
124 */
125 boolean isConnected();
126
127 /**
128 * Returns the address to which this socket is connected. Returns null if
129 * the socket is not connected.
130 *
131 * @return the address to which this socket is connected.
132 */
133 InetAddress getInetAddress();
134
135 /**
136 * Returns the port for this socket. Returns -1 if the socket is not
137 * connected.
138 *
139 * @return the port to which this socket is connected.
140 */
141 int getPort();
142
143 /**
144 * Returns the address of the endpoint this socket is connected to, or
145 * <code>null</code> if it is unconnected.
146 *
147 * @return a <code>SocketAddress</code> representing the remote endpoint of
148 * this socket, or <code>null</code> if it is not connected yet.
149 * @see #getInetAddress()
150 * @see #getPort()
151 * @see #connect(SocketAddress)
152 * @since 1.4
153 */
154 SocketAddress getRemoteSocketAddress();
155
156 /**
157 * Returns the address of the endpoint this socket is bound to, or
158 * <code>null</code> if it is not bound yet.
159 *
160 * @return a <code>SocketAddress</code> representing the local endpoint of
161 * this socket, or <code>null</code> if it is not bound yet.
162 * @see #getLocalAddress()
163 * @see #getLocalPort()
164 * @see #bind(SocketAddress)
165 * @since 1.4
166 */
167
168 SocketAddress getLocalSocketAddress();
169
170 /**
171 * Sends a datagram packet from this socket. The <code>DatagramPacket</code>
172 * includes information indicating the data to be sent, its length, the IP
173 * address of the remote host, and the port number on the remote host.
174 *
175 * <p>
176 * If there is a security manager, and the socket is not currently connected
177 * to a remote address, this method first performs some security checks.
178 * First, if <code>p.getAddress().isMulticastAddress()</code> is true, this
179 * method calls the security manager's <code>checkMulticast</code> method
180 * with <code>p.getAddress()</code> as its argument. If the evaluation of
181 * that expression is false, this method instead calls the security
182 * manager's <code>checkConnect</code> method with arguments
183 * <code>p.getAddress().getHostAddress()</code> and <code>p.getPort()</code>
184 * . Each call to a security manager method could result in a
185 * SecurityException if the operation is not allowed.
186 *
187 * @param p
188 * the <code>DatagramPacket</code> to be sent.
189 *
190 * @exception IOException
191 * if an I/O error occurs.
192 * @exception SecurityException
193 * if a security manager exists and its
194 * <code>checkMulticast</code> or <code>checkConnect</code>
195 * method doesn't allow the send.
196 * @exception PortUnreachableException
197 * may be thrown if the socket is connected to a currently
198 * unreachable destination. Note, there is no guarantee that
199 * the exception will be thrown.
200 * @exception java.nio.channels.IllegalBlockingModeException
201 * if this socket has an associated channel, and the channel
202 * is in non-blocking mode.
203 *
204 * @see java.net.DatagramPacket
205 * @see SecurityManager#checkMulticast(InetAddress)
206 * @see SecurityManager#checkConnect revised 1.4 spec JSR-51
207 */
208 void send(DatagramPacket p) throws IOException;
209
210 /**
211 * Receives a datagram packet from this socket. When this method returns,
212 * the <code>DatagramPacket</code>'s buffer is filled with the data
213 * received. The datagram packet also contains the sender's IP address, and
214 * the port number on the sender's machine.
215 * <p>
216 * This method blocks until a datagram is received. The <code>length</code>
217 * field of the datagram packet object contains the length of the received
218 * message. If the message is longer than the packet's length, the message
219 * is truncated.
220 * <p>
221 * If there is a security manager, a packet cannot be received if the
222 * security manager's <code>checkAccept</code> method does not allow it.
223 *
224 * @param p
225 * the <code>DatagramPacket</code> into which to place the
226 * incoming data.
227 * @exception IOException
228 * if an I/O error occurs.
229 * @exception SocketTimeoutException
230 * if setSoTimeout was previously called and the timeout has
231 * expired.
232 * @exception PortUnreachableException
233 * may be thrown if the socket is connected to a currently
234 * unreachable destination. Note, there is no guarantee that
235 * the exception will be thrown.
236 * @exception java.nio.channels.IllegalBlockingModeException
237 * if this socket has an associated channel, and the channel
238 * is in non-blocking mode.
239 * @see java.net.DatagramPacket
240 * @see java.net.DatagramSocket revised 1.4 spec JSR-51
241 */
242 void receive(DatagramPacket p) throws IOException;
243
244 /**
245 * Gets the local address to which the socket is bound.
246 *
247 * <p>
248 * If there is a security manager, its <code>checkConnect</code> method is
249 * first called with the host address and <code>-1</code> as its arguments
250 * to see if the operation is allowed.
251 *
252 * @see SecurityManager#checkConnect
253 * @return the local address to which the socket is bound, or an
254 * <code>InetAddress</code> representing any local address if either
255 * the socket is not bound, or the security manager
256 * <code>checkConnect</code> method does not allow the operation
257 * @since 1.1
258 */
259 InetAddress getLocalAddress();
260
261 /**
262 * Returns the port number on the local host to which this socket is bound.
263 *
264 * @return the port number on the local host to which this socket is bound.
265 */
266 int getLocalPort();
267
268 /**
269 * Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds.
270 * With this option set to a non-zero timeout, a call to receive() for this
271 * DatagramSocket will block for only this amount of time. If the timeout
272 * expires, a <B>java.net.SocketTimeoutException</B> is raised, though the
273 * DatagramSocket is still valid. The option <B>must</B> be enabled prior to
274 * entering the blocking operation to have effect. The timeout must be > 0.
275 * A timeout of zero is interpreted as an infinite timeout.
276 *
277 * @param timeout
278 * the specified timeout in milliseconds.
279 * @throws SocketException
280 * if there is an error in the underlying protocol, such as an
281 * UDP error.
282 * @since JDK1.1
283 * @see #getSoTimeout()
284 */
285 void setSoTimeout(int timeout) throws SocketException;
286
287 /**
288 * Retrieve setting for SO_TIMEOUT. 0 returns implies that the option is
289 * disabled (i.e., timeout of infinity).
290 *
291 * @return the setting for SO_TIMEOUT
292 * @throws SocketException
293 * if there is an error in the underlying protocol, such as an
294 * UDP error.
295 * @since JDK1.1
296 * @see #setSoTimeout(int)
297 */
298 int getSoTimeout() throws SocketException;
299
300 /**
301 * Sets the SO_SNDBUF option to the specified value for this
302 * <tt>DatagramSocket</tt>. The SO_SNDBUF option is used by the network
303 * implementation as a hint to size the underlying network I/O buffers. The
304 * SO_SNDBUF setting may also be used by the network implementation to
305 * determine the maximum size of the packet that can be sent on this socket.
306 * <p>
307 * As SO_SNDBUF is a hint, applications that want to verify what size the
308 * buffer is should call {@link #getSendBufferSize()}.
309 * <p>
310 * Increasing the buffer size may allow multiple outgoing packets to be
311 * queued by the network implementation when the send rate is high.
312 * <p>
313 * Note: If {@link #send(DatagramPacket)} is used to send a
314 * <code>DatagramPacket</code> that is larger than the setting of SO_SNDBUF
315 * then it is implementation specific if the packet is sent or discarded.
316 *
317 * @param size
318 * the size to which to set the send buffer size. This value must
319 * be greater than 0.
320 *
321 * @exception SocketException
322 * if there is an error in the underlying protocol, such as
323 * an UDP error.
324 * @exception IllegalArgumentException
325 * if the value is 0 or is negative.
326 * @see #getSendBufferSize()
327 */
328 void setSendBufferSize(int size) throws SocketException;
329
330 /**
331 * Get value of the SO_SNDBUF option for this <tt>DatagramSocket</tt>, that
332 * is the buffer size used by the platform for output on this
333 * <tt>DatagramSocket</tt>.
334 *
335 * @return the value of the SO_SNDBUF option for this
336 * <tt>DatagramSocket</tt>
337 * @exception SocketException
338 * if there is an error in the underlying protocol, such as
339 * an UDP error.
340 * @see #setSendBufferSize
341 */
342 int getSendBufferSize() throws SocketException;
343
344 /**
345 * Sets the SO_RCVBUF option to the specified value for this
346 * <tt>DatagramSocket</tt>. The SO_RCVBUF option is used by the the network
347 * implementation as a hint to size the underlying network I/O buffers. The
348 * SO_RCVBUF setting may also be used by the network implementation to
349 * determine the maximum size of the packet that can be received on this
350 * socket.
351 * <p>
352 * Because SO_RCVBUF is a hint, applications that want to verify what size
353 * the buffers were set to should call {@link #getReceiveBufferSize()}.
354 * <p>
355 * Increasing SO_RCVBUF may allow the network implementation to buffer
356 * multiple packets when packets arrive faster than are being received using
357 * {@link #receive(DatagramPacket)}.
358 * <p>
359 * Note: It is implementation specific if a packet larger than SO_RCVBUF can
360 * be received.
361 *
362 * @param size
363 * the size to which to set the receive buffer size. This value
364 * must be greater than 0.
365 *
366 * @exception SocketException
367 * if there is an error in the underlying protocol, such as
368 * an UDP error.
369 * @exception IllegalArgumentException
370 * if the value is 0 or is negative.
371 * @see #getReceiveBufferSize()
372 */
373 void setReceiveBufferSize(int size) throws SocketException;
374
375 /**
376 * Get value of the SO_RCVBUF option for this <tt>DatagramSocket</tt>, that
377 * is the buffer size used by the platform for input on this
378 * <tt>DatagramSocket</tt>.
379 *
380 * @return the value of the SO_RCVBUF option for this
381 * <tt>DatagramSocket</tt>
382 * @exception SocketException
383 * if there is an error in the underlying protocol, such as
384 * an UDP error.
385 * @see #setReceiveBufferSize(int)
386 */
387 int getReceiveBufferSize() throws SocketException;
388
389 /**
390 * Enable/disable the SO_REUSEADDR socket option.
391 * <p>
392 * For UDP sockets it may be necessary to bind more than one socket to the
393 * same socket address. This is typically for the purpose of receiving
394 * multicast packets (See {@link java.net.MulticastSocket}). The
395 * <tt>SO_REUSEADDR</tt> socket option allows multiple sockets to be bound
396 * to the same socket address if the <tt>SO_REUSEADDR</tt> socket option is
397 * enabled prior to binding the socket using {@link #bind(SocketAddress)}.
398 * <p>
399 * Note: This functionality is not supported by all existing platforms, so
400 * it is implementation specific whether this option will be ignored or not.
401 * However, if it is not supported then {@link #getReuseAddress()} will
402 * always return <code>false</code>.
403 * <p>
404 * When a <tt>DatagramSocket</tt> is created the initial setting of
405 * <tt>SO_REUSEADDR</tt> is disabled.
406 * <p>
407 * The behaviour when <tt>SO_REUSEADDR</tt> is enabled or disabled after a
408 * socket is bound (See {@link #isBound()}) is not defined.
409 *
410 * @param on
411 * whether to enable or disable the
412 * @exception SocketException
413 * if an error occurs enabling or disabling the
414 * <tt>SO_RESUEADDR</tt> socket option, or the socket is
415 * closed.
416 * @since 1.4
417 * @see #getReuseAddress()
418 * @see #bind(SocketAddress)
419 * @see #isBound()
420 * @see #isClosed()
421 */
422 void setReuseAddress(boolean on) throws SocketException;
423
424 /**
425 * Tests if SO_REUSEADDR is enabled.
426 *
427 * @return a <code>boolean</code> indicating whether or not SO_REUSEADDR is
428 * enabled.
429 * @exception SocketException
430 * if there is an error in the underlying protocol, such as
431 * an UDP error.
432 * @since 1.4
433 * @see #setReuseAddress(boolean)
434 */
435 boolean getReuseAddress() throws SocketException;
436
437 /**
438 * Enable/disable SO_BROADCAST.
439 *
440 * @param on
441 * whether or not to have broadcast turned on.
442 * @exception SocketException
443 * if there is an error in the underlying protocol, such as
444 * an UDP error.
445 * @since 1.4
446 * @see #getBroadcast()
447 */
448 void setBroadcast(boolean on) throws SocketException;
449
450 /**
451 * Tests if SO_BROADCAST is enabled.
452 *
453 * @return a <code>boolean</code> indicating whether or not SO_BROADCAST is
454 * enabled.
455 * @exception SocketException
456 * if there is an error in the underlying protocol, such as
457 * an UDP error.
458 * @since 1.4
459 * @see #setBroadcast(boolean)
460 */
461 boolean getBroadcast() throws SocketException;
462
463 /**
464 * Sets traffic class or type-of-service octet in the IP datagram header for
465 * datagrams sent from this DatagramSocket. As the underlying network
466 * implementation may ignore this value applications should consider it a
467 * hint.
468 *
469 * <P>
470 * The tc <B>must</B> be in the range <code> 0 <= tc <=
471 * 255</code> or an IllegalArgumentException will be thrown.
472 * <p>
473 * Notes:
474 * <p>
475 * for Internet Protocol v4 the value consists of an octet with precedence
476 * and TOS fields as detailed in RFC 1349. The TOS field is bitset created
477 * by bitwise-or'ing values such the following :-
478 * <p>
479 * <UL>
480 * <LI><CODE>IPTOS_LOWCOST (0x02)</CODE></LI>
481 * <LI><CODE>IPTOS_RELIABILITY (0x04)</CODE></LI>
482 * <LI><CODE>IPTOS_THROUGHPUT (0x08)</CODE></LI>
483 * <LI><CODE>IPTOS_LOWDELAY (0x10)</CODE></LI>
484 * </UL>
485 * The last low order bit is always ignored as this corresponds to the MBZ
486 * (must be zero) bit.
487 * <p>
488 * Setting bits in the precedence field may result in a SocketException
489 * indicating that the operation is not permitted.
490 * <p>
491 * for Internet Protocol v6 <code>tc</code> is the value that would be
492 * placed into the sin6_flowinfo field of the IP header.
493 *
494 * @param tc
495 * an <code>int</code> value for the bitset.
496 * @throws SocketException
497 * if there is an error setting the traffic class or
498 * type-of-service
499 * @since 1.4
500 * @see #getTrafficClass
501 */
502 void setTrafficClass(int tc) throws SocketException;
503
504 /**
505 * Gets traffic class or type-of-service in the IP datagram header for
506 * packets sent from this DatagramSocket.
507 * <p>
508 * As the underlying network implementation may ignore the traffic class or
509 * type-of-service set using {@link #setTrafficClass(int)} this method may
510 * return a different value than was previously set using the
511 * {@link #setTrafficClass(int)} method on this DatagramSocket.
512 *
513 * @return the traffic class or type-of-service already set
514 * @throws SocketException
515 * if there is an error obtaining the traffic class or
516 * type-of-service value.
517 * @since 1.4
518 * @see #setTrafficClass(int)
519 */
520 int getTrafficClass() throws SocketException;
521
522 /**
523 * Closes this datagram socket.
524 * <p>
525 * Any thread currently blocked in {@link #receive} upon this socket will
526 * throw a {@link SocketException}.
527 *
528 * <p>
529 * If this socket has an associated channel then the channel is closed as
530 * well.
531 *
532 * revised 1.4 spec JSR-51
533 */
534 void close();
535
536 /**
537 * Returns whether the socket is closed or not.
538 *
539 * @return true if the socket has been closed
540 * @since 1.4
541 */
542 boolean isClosed();
543
544 /**
545 * Returns the unique {@link java.nio.channels.DatagramChannel} object
546 * associated with this datagram socket, if any.
547 *
548 * <p>
549 * A datagram socket will have a channel if, and only if, the channel itself
550 * was created via the {@link java.nio.channels.DatagramChannel#open
551 * DatagramChannel.open} method.
552 *
553 * @return the datagram channel associated with this datagram socket, or
554 * <tt>null</tt> if this socket was not created for a channel
555 *
556 * @since 1.4 spec JSR-51
557 */
558 DatagramChannel getChannel();
559
560 }