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.io.InputStream;
012 import java.io.OutputStream;
013 import java.net.InetAddress;
014 import java.net.ServerSocket;
015 import java.net.SocketAddress;
016 import java.net.SocketException;
017 import java.net.SocketTimeoutException;
018 import java.nio.channels.SocketChannel;
019
020 /**
021 * compatibility verification interface
022 */
023 public interface IceSocket {
024
025 /**
026 * Connects this socket to the server.
027 *
028 * @param endpoint
029 * the <code>SocketAddress</code>
030 * @throws IOException
031 * if an error occurs during the connection
032 * @throws java.nio.channels.IllegalBlockingModeException
033 * if this socket has an associated channel, and the channel is
034 * in non-blocking mode
035 * @throws IllegalArgumentException
036 * if endpoint is null or is a SocketAddress subclass not
037 * supported by this socket
038 * @since 1.4 spec JSR-51
039 */
040 void connect(SocketAddress endpoint) throws IOException;
041
042 /**
043 * Connects this socket to the server with a specified timeout value. A
044 * timeout of zero is interpreted as an infinite timeout. The connection
045 * will then block until established or an error occurs.
046 *
047 * @param endpoint
048 * the <code>SocketAddress</code>
049 * @param timeout
050 * the timeout value to be used in milliseconds.
051 * @throws IOException
052 * if an error occurs during the connection
053 * @throws SocketTimeoutException
054 * if timeout expires before connecting
055 * @throws java.nio.channels.IllegalBlockingModeException
056 * if this socket has an associated channel, and the channel is
057 * in non-blocking mode
058 * @throws IllegalArgumentException
059 * if endpoint is null or is a SocketAddress subclass not
060 * supported by this socket
061 * @since 1.4 spec JSR-51
062 */
063 void connect(SocketAddress endpoint, int timeout) throws IOException;
064
065 /**
066 * Binds the socket to a local address.
067 * <P>
068 * If the address is <code>null</code>, then the system will pick up an
069 * ephemeral port and a valid local address to bind the socket.
070 *
071 * @param bindpoint
072 * the <code>SocketAddress</code> to bind to
073 * @throws IOException
074 * if the bind operation fails, or if the socket is already
075 * bound.
076 * @throws IllegalArgumentException
077 * if bindpoint is a SocketAddress subclass not supported by
078 * this socket
079 *
080 * @since 1.4
081 * @see #isBound
082 */
083 void bind(SocketAddress bindpoint) throws IOException;
084
085 /**
086 * Returns the address to which the socket is connected.
087 *
088 * @return the remote IP address to which this socket is connected, or
089 * <code>null</code> if the socket is not connected.
090 */
091 InetAddress getInetAddress();
092
093 /**
094 * Gets the local address to which the socket is bound.
095 *
096 * @return the local address to which the socket is bound or
097 * <code>InetAddress.anyLocalAddress()</code> if the socket is not
098 * bound yet.
099 * @since JDK1.1
100 */
101 InetAddress getLocalAddress();
102
103 /**
104 * Returns the remote port to which this socket is connected.
105 *
106 * @return the remote port number to which this socket is connected, or 0 if
107 * the socket is not connected yet.
108 */
109 int getPort();
110
111 /**
112 * Returns the local port to which this socket is bound.
113 *
114 * @return the local port number to which this socket is bound or -1 if the
115 * socket is not bound yet.
116 */
117 int getLocalPort();
118
119 /**
120 * Returns the address of the endpoint this socket is connected to, or
121 * <code>null</code> if it is unconnected.
122 *
123 * @return a <code>SocketAddress</code> reprensenting the remote endpoint of
124 * this socket, or <code>null</code> if it is not connected yet.
125 * @see #getInetAddress()
126 * @see #getPort()
127 * @see #connect(SocketAddress, int)
128 * @see #connect(SocketAddress)
129 * @since 1.4
130 */
131 SocketAddress getRemoteSocketAddress();
132
133 /**
134 * Returns the address of the endpoint this socket is bound to, or
135 * <code>null</code> if it is not bound yet.
136 *
137 * @return a <code>SocketAddress</code> representing the local endpoint of
138 * this socket, or <code>null</code> if it is not bound yet.
139 * @see #getLocalAddress()
140 * @see #getLocalPort()
141 * @see #bind(SocketAddress)
142 * @since 1.4
143 */
144
145 SocketAddress getLocalSocketAddress();
146
147 /**
148 * Returns the unique {@link java.nio.channels.SocketChannel SocketChannel}
149 * object associated with this socket, if any.
150 *
151 * <p>
152 * A socket will have a channel if, and only if, the channel itself was
153 * created via the {@link java.nio.channels.SocketChannel#open
154 * SocketChannel.open} or
155 * {@link java.nio.channels.ServerSocketChannel#accept
156 * ServerSocketChannel.accept} methods.
157 *
158 * @return the socket channel associated with this socket, or <tt>null</tt>
159 * if this socket was not created for a channel
160 *
161 * @since 1.4 spec JSR-51
162 */
163 SocketChannel getChannel();
164
165 /**
166 * Returns an input stream for this socket.
167 *
168 * <p>
169 * If this socket has an associated channel then the resulting input stream
170 * delegates all of its operations to the channel. If the channel is in
171 * non-blocking mode then the input stream's <tt>read</tt> operations will
172 * throw an {@link java.nio.channels.IllegalBlockingModeException}.
173 *
174 * <p>
175 * Under abnormal conditions the underlying connection may be broken by the
176 * remote host or the network software (for example a connection reset in
177 * the case of TCP connections). When a broken connection is detected by the
178 * network software the following applies to the returned input stream :-
179 *
180 * <ul>
181 *
182 * <li>
183 * <p>
184 * The network software may discard bytes that are buffered by the socket.
185 * Bytes that aren't discarded by the network software can be read using
186 * {@link java.io.InputStream#read read}.
187 *
188 * <li>
189 * <p>
190 * If there are no bytes buffered on the socket, or all buffered bytes have
191 * been consumed by {@link java.io.InputStream#read read}, then all
192 * subsequent calls to {@link java.io.InputStream#read read} will throw an
193 * {@link java.io.IOException IOException}.
194 *
195 * <li>
196 * <p>
197 * If there are no bytes buffered on the socket, and the socket has not been
198 * closed using {@link #close close}, then
199 * {@link java.io.InputStream#available available} will return
200 * <code>0</code>.
201 *
202 * </ul>
203 *
204 * <p>
205 * Closing the returned {@link java.io.InputStream InputStream} will close
206 * the associated socket.
207 *
208 * @return an input stream for reading bytes from this socket.
209 * @exception IOException
210 * if an I/O error occurs when creating the input stream, the
211 * socket is closed, the socket is not connected, or the
212 * socket input has been shutdown using
213 * {@link #shutdownInput()}
214 *
215 * revised 1.4 spec JSR-51
216 */
217 InputStream getInputStream() throws IOException;
218
219 /**
220 * Returns an output stream for this socket.
221 *
222 * <p>
223 * If this socket has an associated channel then the resulting output stream
224 * delegates all of its operations to the channel. If the channel is in
225 * non-blocking mode then the output stream's <tt>write</tt> operations will
226 * throw an {@link java.nio.channels.IllegalBlockingModeException}.
227 *
228 * <p>
229 * Closing the returned {@link java.io.OutputStream OutputStream} will close
230 * the associated socket.
231 *
232 * @return an output stream for writing bytes to this socket.
233 * @exception IOException
234 * if an I/O error occurs when creating the output stream or
235 * if the socket is not connected. revised 1.4 spec JSR-51
236 */
237 OutputStream getOutputStream() throws IOException;
238
239 /**
240 * Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm).
241 *
242 * @param on
243 * <code>true</code> to enable TCP_NODELAY, <code>false</code> to
244 * disable.
245 *
246 * @exception SocketException
247 * if there is an error in the underlying protocol, such as a
248 * TCP error.
249 *
250 * @since JDK1.1
251 *
252 * @see #getTcpNoDelay()
253 */
254 void setTcpNoDelay(boolean on) throws SocketException;
255
256 /**
257 * Tests if TCP_NODELAY is enabled.
258 *
259 * @return a <code>boolean</code> indicating whether or not TCP_NODELAY is
260 * enabled.
261 * @exception SocketException
262 * if there is an error in the underlying protocol, such as a
263 * TCP error.
264 * @since JDK1.1
265 * @see #setTcpNoDelay(boolean)
266 */
267 boolean getTcpNoDelay() throws SocketException;
268
269 /**
270 * Enable/disable SO_LINGER with the specified linger time in seconds. The
271 * maximum timeout value is platform specific.
272 *
273 * The setting only affects socket close.
274 *
275 * @param on
276 * whether or not to linger on.
277 * @param linger
278 * how long to linger for, if on is true.
279 * @exception SocketException
280 * if there is an error in the underlying protocol, such as a
281 * TCP error.
282 * @exception IllegalArgumentException
283 * if the linger value is negative.
284 * @since JDK1.1
285 * @see #getSoLinger()
286 */
287 void setSoLinger(boolean on, int linger) throws SocketException;
288
289 /**
290 * Returns setting for SO_LINGER. -1 returns implies that the option is
291 * disabled.
292 *
293 * The setting only affects socket close.
294 *
295 * @return the setting for SO_LINGER.
296 * @exception SocketException
297 * if there is an error in the underlying protocol, such as a
298 * TCP error.
299 * @since JDK1.1
300 * @see #setSoLinger(boolean, int)
301 */
302 int getSoLinger() throws SocketException;
303
304 /**
305 * Send one byte of urgent data on the socket. The byte to be sent is the
306 * lowest eight bits of the data parameter. The urgent byte is sent after
307 * any preceding writes to the socket OutputStream and before any future
308 * writes to the OutputStream.
309 *
310 * @param data
311 * The byte of data to send
312 * @exception IOException
313 * if there is an error sending the data.
314 * @since 1.4
315 */
316 void sendUrgentData(int data) throws IOException;
317
318 /**
319 * Enable/disable OOBINLINE (receipt of TCP urgent data)
320 *
321 * By default, this option is disabled and TCP urgent data received on a
322 * socket is silently discarded. If the user wishes to receive urgent data,
323 * then this option must be enabled. When enabled, urgent data is received
324 * inline with normal data.
325 * <p>
326 * Note, only limited support is provided for handling incoming urgent data.
327 * In particular, no notification of incoming urgent data is provided and
328 * there is no capability to distinguish between normal data and urgent data
329 * unless provided by a higher level protocol.
330 *
331 * @param on
332 * <code>true</code> to enable OOBINLINE, <code>false</code> to
333 * disable.
334 *
335 * @exception SocketException
336 * if there is an error in the underlying protocol, such as a
337 * TCP error.
338 *
339 * @since 1.4
340 *
341 * @see #getOOBInline()
342 */
343 void setOOBInline(boolean on) throws SocketException;
344
345 /**
346 * Tests if OOBINLINE is enabled.
347 *
348 * @return a <code>boolean</code> indicating whether or not OOBINLINE is
349 * enabled.
350 * @exception SocketException
351 * if there is an error in the underlying protocol, such as a
352 * TCP error.
353 * @since 1.4
354 * @see #setOOBInline(boolean)
355 */
356 boolean getOOBInline() throws SocketException;
357
358 /**
359 * Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds.
360 * With this option set to a non-zero timeout, a read() call on the
361 * InputStream associated with this Socket will block for only this amount
362 * of time. If the timeout expires, a <B>java.net.SocketTimeoutException</B>
363 * is raised, though the Socket is still valid. The option <B>must</B> be
364 * enabled prior to entering the blocking operation to have effect. The
365 * timeout must be > 0. A timeout of zero is interpreted as an infinite
366 * timeout.
367 *
368 * @param timeout
369 * the specified timeout, in milliseconds.
370 * @exception SocketException
371 * if there is an error in the underlying protocol, such as a
372 * TCP error.
373 * @since JDK 1.1
374 * @see #getSoTimeout()
375 */
376 void setSoTimeout(int timeout) throws SocketException;
377
378 /**
379 * Returns setting for SO_TIMEOUT. 0 returns implies that the option is
380 * disabled (i.e., timeout of infinity).
381 *
382 * @return the setting for SO_TIMEOUT
383 * @exception SocketException
384 * if there is an error in the underlying protocol, such as a
385 * TCP error.
386 * @since JDK1.1
387 * @see #setSoTimeout(int)
388 */
389 int getSoTimeout() throws SocketException;
390
391 /**
392 * Sets the SO_SNDBUF option to the specified value for this <tt>Socket</tt>
393 * . The SO_SNDBUF option is used by the platform's networking code as a
394 * hint for the size to set the underlying network I/O buffers.
395 *
396 * <p>
397 * Because SO_SNDBUF is a hint, applications that want to verify what size
398 * the buffers were set to should call {@link #getSendBufferSize()}.
399 *
400 * @exception SocketException
401 * if there is an error in the underlying protocol, such as a
402 * TCP error.
403 *
404 * @param size
405 * the size to which to set the send buffer size. This value must
406 * be greater than 0.
407 *
408 * @exception IllegalArgumentException
409 * if the value is 0 or is negative.
410 *
411 * @see #getSendBufferSize()
412 * @since 1.2
413 */
414 void setSendBufferSize(int size) throws SocketException;
415
416 /**
417 * Get value of the SO_SNDBUF option for this <tt>Socket</tt>, that is the
418 * buffer size used by the platform for output on this <tt>Socket</tt>.
419 *
420 * @return the value of the SO_SNDBUF option for this <tt>Socket</tt>.
421 *
422 * @exception SocketException
423 * if there is an error in the underlying protocol, such as a
424 * TCP error.
425 *
426 * @see #setSendBufferSize(int)
427 * @since 1.2
428 */
429 int getSendBufferSize() throws SocketException;
430
431 /**
432 * Sets the SO_RCVBUF option to the specified value for this <tt>Socket</tt>
433 * . The SO_RCVBUF option is used by the platform's networking code as a
434 * hint for the size to set the underlying network I/O buffers.
435 *
436 * <p>
437 * Increasing the receive buffer size can increase the performance of
438 * network I/O for high-volume connection, while decreasing it can help
439 * reduce the backlog of incoming data.
440 *
441 * <p>
442 * Because SO_RCVBUF is a hint, applications that want to verify what size
443 * the buffers were set to should call {@link #getReceiveBufferSize()}.
444 *
445 * <p>
446 * The value of SO_RCVBUF is also used to set the TCP receive window that is
447 * advertized to the remote peer. Generally, the window size can be modified
448 * at any time when a socket is connected. However, if a receive window
449 * larger than 64K is required then this must be requested <B>before</B> the
450 * socket is connected to the remote peer. There are two cases to be aware
451 * of:
452 * <p>
453 * <ol>
454 * <li>For sockets accepted from a ServerSocket, this must be done by
455 * calling {@link ServerSocket#setReceiveBufferSize(int)} before the
456 * ServerSocket is bound to a local address.
457 * <p></li>
458 * <li>For client sockets, setReceiveBufferSize() must be called before
459 * connecting the socket to its remote peer.
460 * <p></li>
461 * </ol>
462 *
463 * @param size
464 * the size to which to set the receive buffer size. This value
465 * must be greater than 0.
466 *
467 * @exception IllegalArgumentException
468 * if the value is 0 or is negative.
469 *
470 * @exception SocketException
471 * if there is an error in the underlying protocol, such as a
472 * TCP error.
473 *
474 * @see #getReceiveBufferSize()
475 * @see ServerSocket#setReceiveBufferSize(int)
476 * @since 1.2
477 */
478 void setReceiveBufferSize(int size) throws SocketException;
479
480 /**
481 * Gets the value of the SO_RCVBUF option for this <tt>Socket</tt>, that is
482 * the buffer size used by the platform for input on this <tt>Socket</tt>.
483 *
484 * @return the value of the SO_RCVBUF option for this <tt>Socket</tt>.
485 * @exception SocketException
486 * if there is an error in the underlying protocol, such as a
487 * TCP error.
488 * @see #setReceiveBufferSize(int)
489 * @since 1.2
490 */
491 int getReceiveBufferSize() throws SocketException;
492
493 /**
494 * Enable/disable SO_KEEPALIVE.
495 *
496 * @param on
497 * whether or not to have socket keep alive turned on.
498 * @exception SocketException
499 * if there is an error in the underlying protocol, such as a
500 * TCP error.
501 * @since 1.3
502 * @see #getKeepAlive()
503 */
504 void setKeepAlive(boolean on) throws SocketException;
505
506 /**
507 * Tests if SO_KEEPALIVE is enabled.
508 *
509 * @return a <code>boolean</code> indicating whether or not SO_KEEPALIVE is
510 * enabled.
511 * @exception SocketException
512 * if there is an error in the underlying protocol, such as a
513 * TCP error.
514 * @since 1.3
515 * @see #setKeepAlive(boolean)
516 */
517 boolean getKeepAlive() throws SocketException;
518
519 /**
520 * Sets traffic class or type-of-service octet in the IP header for packets
521 * sent from this Socket. As the underlying network implementation may
522 * ignore this value applications should consider it a hint.
523 *
524 * <P>
525 * The tc <B>must</B> be in the range <code> 0 <= tc <=
526 * 255</code> or an IllegalArgumentException will be thrown.
527 * <p>
528 * Notes:
529 * <p>
530 * For Internet Protocol v4 the value consists of an octet with precedence
531 * and TOS fields as detailed in RFC 1349. The TOS field is bitset created
532 * by bitwise-or'ing values such the following :-
533 * <p>
534 * <UL>
535 * <LI><CODE>IPTOS_LOWCOST (0x02)</CODE></LI>
536 * <LI><CODE>IPTOS_RELIABILITY (0x04)</CODE></LI>
537 * <LI><CODE>IPTOS_THROUGHPUT (0x08)</CODE></LI>
538 * <LI><CODE>IPTOS_LOWDELAY (0x10)</CODE></LI>
539 * </UL>
540 * The last low order bit is always ignored as this corresponds to the MBZ
541 * (must be zero) bit.
542 * <p>
543 * Setting bits in the precedence field may result in a SocketException
544 * indicating that the operation is not permitted.
545 * <p>
546 * As RFC 1122 section 4.2.4.2 indicates, a compliant TCP implementation
547 * should, but is not required to, let application change the TOS field
548 * during the lifetime of a connection. So whether the type-of-service field
549 * can be changed after the TCP connection has been established depends on
550 * the implementation in the underlying platform. Applications should not
551 * assume that they can change the TOS field after the connection.
552 * <p>
553 * For Internet Protocol v6 <code>tc</code> is the value that would be
554 * placed into the sin6_flowinfo field of the IP header.
555 *
556 * @param tc
557 * an <code>int</code> value for the bitset.
558 * @throws SocketException
559 * if there is an error setting the traffic class or
560 * type-of-service
561 * @since 1.4
562 * @see #getTrafficClass
563 */
564 void setTrafficClass(int tc) throws SocketException;
565
566 /**
567 * Gets traffic class or type-of-service in the IP header for packets sent
568 * from this Socket
569 * <p>
570 * As the underlying network implementation may ignore the traffic class or
571 * type-of-service set using {@link #setTrafficClass(int)} this method may
572 * return a different value than was previously set using the
573 * {@link #setTrafficClass(int)} method on this Socket.
574 *
575 * @return the traffic class or type-of-service already set
576 * @throws SocketException
577 * if there is an error obtaining the traffic class or
578 * type-of-service value.
579 * @since 1.4
580 * @see #setTrafficClass(int)
581 */
582 int getTrafficClass() throws SocketException;
583
584 /**
585 * Enable/disable the SO_REUSEADDR socket option.
586 * <p>
587 * When a TCP connection is closed the connection may remain in a timeout
588 * state for a period of time after the connection is closed (typically
589 * known as the <tt>TIME_WAIT</tt> state or <tt>2MSL</tt> wait state). For
590 * applications using a well known socket address or port it may not be
591 * possible to bind a socket to the required <tt>SocketAddress</tt> if there
592 * is a connection in the timeout state involving the socket address or
593 * port.
594 * <p>
595 * Enabling <tt>SO_REUSEADDR</tt> prior to binding the socket using
596 * {@link #bind(SocketAddress)} allows the socket to be bound even though a
597 * previous connection is in a timeout state.
598 * <p>
599 * When a <tt>Socket</tt> is created the initial setting of
600 * <tt>SO_REUSEADDR</tt> is disabled.
601 * <p>
602 * The behaviour when <tt>SO_REUSEADDR</tt> is enabled or disabled after a
603 * socket is bound (See {@link #isBound()}) is not defined.
604 *
605 * @param on
606 * whether to enable or disable the socket option
607 * @exception SocketException
608 * if an error occurs enabling or disabling the
609 * <tt>SO_RESUEADDR</tt> socket option, or the socket is
610 * closed.
611 * @since 1.4
612 * @see #getReuseAddress()
613 * @see #bind(SocketAddress)
614 * @see #isClosed()
615 * @see #isBound()
616 */
617 void setReuseAddress(boolean on) throws SocketException;
618
619 /**
620 * Tests if SO_REUSEADDR is enabled.
621 *
622 * @return a <code>boolean</code> indicating whether or not SO_REUSEADDR is
623 * enabled.
624 * @exception SocketException
625 * if there is an error in the underlying protocol, such as a
626 * TCP error.
627 * @since 1.4
628 * @see #setReuseAddress(boolean)
629 */
630 boolean getReuseAddress() throws SocketException;
631
632 /**
633 * Closes this socket.
634 * <p>
635 * Any thread currently blocked in an I/O operation upon this socket will
636 * throw a {@link SocketException}.
637 * <p>
638 * Once a socket has been closed, it is not available for further networking
639 * use (i.e. can't be reconnected or rebound). A new socket needs to be
640 * created.
641 *
642 * <p>
643 * Closing this socket will also close the socket's
644 * {@link java.io.InputStream InputStream} and {@link java.io.OutputStream
645 * OutputStream}.
646 *
647 * <p>
648 * If this socket has an associated channel then the channel is closed as
649 * well.
650 *
651 * @exception IOException
652 * if an I/O error occurs when closing this socket. revised
653 * 1.4 spec JSR-51
654 * @see #isClosed
655 */
656 void close() throws IOException;
657
658 /**
659 * Places the input stream for this socket at "end of stream". Any data sent
660 * to the input stream side of the socket is acknowledged and then silently
661 * discarded.
662 * <p>
663 * If you read from a socket input stream after invoking shutdownInput() on
664 * the socket, the stream will return EOF.
665 *
666 * @exception IOException
667 * if an I/O error occurs when shutting down this socket.
668 *
669 * @since 1.3
670 * @see java.net.Socket#shutdownOutput()
671 * @see java.net.Socket#close()
672 * @see java.net.Socket#setSoLinger(boolean, int)
673 * @see #isInputShutdown
674 */
675 void shutdownInput() throws IOException;
676
677 /**
678 * Disables the output stream for this socket. For a TCP socket, any
679 * previously written data will be sent followed by TCP's normal connection
680 * termination sequence.
681 *
682 * If you write to a socket output stream after invoking shutdownOutput() on
683 * the socket, the stream will throw an IOException.
684 *
685 * @exception IOException
686 * if an I/O error occurs when shutting down this socket.
687 *
688 * @since 1.3
689 * @see java.net.Socket#shutdownInput()
690 * @see java.net.Socket#close()
691 * @see java.net.Socket#setSoLinger(boolean, int)
692 * @see #isOutputShutdown
693 */
694 void shutdownOutput() throws IOException;
695
696 /**
697 * Converts this socket to a <code>String</code>.
698 *
699 * @return a string representation of this socket.
700 */
701 @Override
702 String toString();
703
704 /**
705 * Returns the connection state of the socket.
706 *
707 * @return true if the socket successfuly connected to a server
708 * @since 1.4
709 */
710 boolean isConnected();
711
712 /**
713 * Returns the binding state of the socket.
714 *
715 * @return true if the socket successfuly bound to an address
716 * @since 1.4
717 * @see #bind
718 */
719 boolean isBound();
720
721 /**
722 * Returns the closed state of the socket.
723 *
724 * @return true if the socket has been closed
725 * @since 1.4
726 * @see #close
727 */
728 boolean isClosed();
729
730 /**
731 * Returns whether the read-half of the socket connection is closed.
732 *
733 * @return true if the input of the socket has been shutdown
734 * @since 1.4
735 * @see #shutdownInput
736 */
737 boolean isInputShutdown();
738
739 /**
740 * Returns whether the write-half of the socket connection is closed.
741 *
742 * @return true if the output of the socket has been shutdown
743 * @since 1.4
744 * @see #shutdownOutput
745 */
746 boolean isOutputShutdown();
747
748 /**
749 * Sets performance preferences for this socket.
750 *
751 * <p>
752 * Sockets use the TCP/IP protocol by default. Some implementations may
753 * offer alternative protocols which have different performance
754 * characteristics than TCP/IP. This method allows the application to
755 * express its own preferences as to how these tradeoffs should be made when
756 * the implementation chooses from the available protocols.
757 *
758 * <p>
759 * Performance preferences are described by three integers whose values
760 * indicate the relative importance of short connection time, low latency,
761 * and high bandwidth. The absolute values of the integers are irrelevant;
762 * in order to choose a protocol the values are simply compared, with larger
763 * values indicating stronger preferences. Negative values represent a lower
764 * priority than positive values. If the application prefers short
765 * connection time over both low latency and high bandwidth, for example,
766 * then it could invoke this method with the values <tt>(1, 0, 0)</tt>. If
767 * the application prefers high bandwidth above low latency, and low latency
768 * above short connection time, then it could invoke this method with the
769 * values <tt>(0, 1, 2)</tt>.
770 *
771 * <p>
772 * Invoking this method after this socket has been connected will have no
773 * effect.
774 *
775 * @param connectionTime
776 * An <tt>int</tt> expressing the relative importance of a short
777 * connection time
778 *
779 * @param latency
780 * An <tt>int</tt> expressing the relative importance of low
781 * latency
782 *
783 * @param bandwidth
784 * An <tt>int</tt> expressing the relative importance of high
785 * bandwidth
786 *
787 * @since 1.5
788 */
789 void setPerformancePreferences(int connectionTime, int latency,
790 int bandwidth);
791
792 }