1 /*
2 * Copyright (c) 1995, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.net;
27
28 import java.io.InputStream;
29 import java.io.OutputStream;
30 import java.io.IOException;
31 import java.io.InterruptedIOException;
32 import java.nio.channels.SocketChannel;
33 import java.security.AccessController;
34 import java.security.PrivilegedExceptionAction;
35 import java.security.PrivilegedAction;
36
37 /**
38 * This class implements client sockets (also called just
39 * "sockets"). A socket is an endpoint for communication
40 * between two machines.
41 * <p>
42 * The actual work of the socket is performed by an instance of the
43 * <code>SocketImpl</code> class. An application, by changing
44 * the socket factory that creates the socket implementation,
45 * can configure itself to create sockets appropriate to the local
46 * firewall.
47 *
48 * @author unascribed
49 * @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory)
50 * @see java.net.SocketImpl
51 * @see java.nio.channels.SocketChannel
52 * @since JDK1.0
53 */
54 public
55 class Socket {
56 /**
57 * Various states of this socket.
58 */
59 private boolean created = false;
60 private boolean bound = false;
61 private boolean connected = false;
62 private boolean closed = false;
63 private Object closeLock = new Object();
64 private boolean shutIn = false;
65 private boolean shutOut = false;
66
67 /**
68 * The implementation of this Socket.
69 */
70 SocketImpl impl;
71
72 /**
73 * Are we using an older SocketImpl?
74 */
75 private boolean oldImpl = false;
76
77 /**
78 * Creates an unconnected socket, with the
79 * system-default type of SocketImpl.
80 *
81 * @since JDK1.1
82 * @revised 1.4
83 */
84 public Socket() {
85 setImpl();
86 }
87
88 /**
89 * Creates an unconnected socket, specifying the type of proxy, if any,
90 * that should be used regardless of any other settings.
91 * <P>
92 * If there is a security manager, its <code>checkConnect</code> method
93 * is called with the proxy host address and port number
94 * as its arguments. This could result in a SecurityException.
95 * <P>
96 * Examples:
97 * <UL> <LI><code>Socket s = new Socket(Proxy.NO_PROXY);</code> will create
98 * a plain socket ignoring any other proxy configuration.</LI>
99 * <LI><code>Socket s = new Socket(new Proxy(Proxy.Type.SOCKS, new InetSocketAddress("socks.mydom.com", 1080)));</code>
100 * will create a socket connecting through the specified SOCKS proxy
101 * server.</LI>
102 * </UL>
103 *
104 * @param proxy a {@link java.net.Proxy Proxy} object specifying what kind
105 * of proxying should be used.
106 * @throws IllegalArgumentException if the proxy is of an invalid type
107 * or <code>null</code>.
108 * @throws SecurityException if a security manager is present and
109 * permission to connect to the proxy is
110 * denied.
111 * @see java.net.ProxySelector
112 * @see java.net.Proxy
113 *
114 * @since 1.5
115 */
116 public Socket(Proxy proxy) {
117 // Create a copy of Proxy as a security measure
118 if (proxy == null) {
119 throw new IllegalArgumentException("Invalid Proxy");
120 }
121 Proxy p = proxy == Proxy.NO_PROXY ? Proxy.NO_PROXY : sun.net.ApplicationProxy.create(proxy);
122 if (p.type() == Proxy.Type.SOCKS) {
123 SecurityManager security = System.getSecurityManager();
124 InetSocketAddress epoint = (InetSocketAddress) p.address();
125 if (epoint.getAddress() != null) {
126 checkAddress (epoint.getAddress(), "Socket");
127 }
128 if (security != null) {
129 if (epoint.isUnresolved())
130 epoint = new InetSocketAddress(epoint.getHostName(), epoint.getPort());
131 if (epoint.isUnresolved())
132 security.checkConnect(epoint.getHostName(),
133 epoint.getPort());
134 else
135 security.checkConnect(epoint.getAddress().getHostAddress(),
136 epoint.getPort());
137 }
138 impl = new SocksSocketImpl(p);
139 impl.setSocket(this);
140 } else {
141 if (p == Proxy.NO_PROXY) {
142 if (factory == null) {
143 impl = new PlainSocketImpl();
144 impl.setSocket(this);
145 } else
146 setImpl();
147 } else
148 throw new IllegalArgumentException("Invalid Proxy");
149 }
150 }
151
152 /**
153 * Creates an unconnected Socket with a user-specified
154 * SocketImpl.
155 * <P>
156 * @param impl an instance of a <B>SocketImpl</B>
157 * the subclass wishes to use on the Socket.
158 *
159 * @exception SocketException if there is an error in the underlying protocol,
160 * such as a TCP error.
161 * @since JDK1.1
162 */
163 protected Socket(SocketImpl impl) throws SocketException {
164 this.impl = impl;
165 if (impl != null) {
166 checkOldImpl();
167 this.impl.setSocket(this);
168 }
169 }
170
171 /**
172 * Creates a stream socket and connects it to the specified port
173 * number on the named host.
174 * <p>
175 * If the specified host is <tt>null</tt> it is the equivalent of
176 * specifying the address as <tt>{@link java.net.InetAddress#getByName InetAddress.getByName}(null)</tt>.
177 * In other words, it is equivalent to specifying an address of the
178 * loopback interface. </p>
179 * <p>
180 * If the application has specified a server socket factory, that
181 * factory's <code>createSocketImpl</code> method is called to create
182 * the actual socket implementation. Otherwise a "plain" socket is created.
183 * <p>
184 * If there is a security manager, its
185 * <code>checkConnect</code> method is called
186 * with the host address and <code>port</code>
187 * as its arguments. This could result in a SecurityException.
188 *
189 * @param host the host name, or <code>null</code> for the loopback address.
190 * @param port the port number.
191 *
192 * @exception UnknownHostException if the IP address of
193 * the host could not be determined.
194 *
195 * @exception IOException if an I/O error occurs when creating the socket.
196 * @exception SecurityException if a security manager exists and its
197 * <code>checkConnect</code> method doesn't allow the operation.
198 * @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory)
199 * @see java.net.SocketImpl
200 * @see java.net.SocketImplFactory#createSocketImpl()
201 * @see SecurityManager#checkConnect
202 */
203 public Socket(String host, int port)
204 throws UnknownHostException, IOException
205 {
206 this(host != null ? new InetSocketAddress(host, port) :
207 new InetSocketAddress(InetAddress.getByName(null), port),
208 (SocketAddress) null, true);
209 }
210
211 /**
212 * Creates a stream socket and connects it to the specified port
213 * number at the specified IP address.
214 * <p>
215 * If the application has specified a socket factory, that factory's
216 * <code>createSocketImpl</code> method is called to create the
217 * actual socket implementation. Otherwise a "plain" socket is created.
218 * <p>
219 * If there is a security manager, its
220 * <code>checkConnect</code> method is called
221 * with the host address and <code>port</code>
222 * as its arguments. This could result in a SecurityException.
223 *
224 * @param address the IP address.
225 * @param port the port number.
226 * @exception IOException if an I/O error occurs when creating the socket.
227 * @exception SecurityException if a security manager exists and its
228 * <code>checkConnect</code> method doesn't allow the operation.
229 * @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory)
230 * @see java.net.SocketImpl
231 * @see java.net.SocketImplFactory#createSocketImpl()
232 * @see SecurityManager#checkConnect
233 */
234 public Socket(InetAddress address, int port) throws IOException {
235 this(address != null ? new InetSocketAddress(address, port) : null,
236 (SocketAddress) null, true);
237 }
238
239 /**
240 * Creates a socket and connects it to the specified remote host on
241 * the specified remote port. The Socket will also bind() to the local
242 * address and port supplied.
243 * <p>
244 * If the specified host is <tt>null</tt> it is the equivalent of
245 * specifying the address as <tt>{@link java.net.InetAddress#getByName InetAddress.getByName}(null)</tt>.
246 * In other words, it is equivalent to specifying an address of the
247 * loopback interface. </p>
248 * <p>
249 * If there is a security manager, its
250 * <code>checkConnect</code> method is called
251 * with the host address and <code>port</code>
252 * as its arguments. This could result in a SecurityException.
253 *
254 * @param host the name of the remote host, or <code>null</code> for the loopback address.
255 * @param port the remote port
256 * @param localAddr the local address the socket is bound to
257 * @param localPort the local port the socket is bound to
258 * @exception IOException if an I/O error occurs when creating the socket.
259 * @exception SecurityException if a security manager exists and its
260 * <code>checkConnect</code> method doesn't allow the operation.
261 * @see SecurityManager#checkConnect
262 * @since JDK1.1
263 */
264 public Socket(String host, int port, InetAddress localAddr,
265 int localPort) throws IOException {
266 this(host != null ? new InetSocketAddress(host, port) :
267 new InetSocketAddress(InetAddress.getByName(null), port),
268 new InetSocketAddress(localAddr, localPort), true);
269 }
270
271 /**
272 * Creates a socket and connects it to the specified remote address on
273 * the specified remote port. The Socket will also bind() to the local
274 * address and port supplied.
275 * <p>
276 * If there is a security manager, its
277 * <code>checkConnect</code> method is called
278 * with the host address and <code>port</code>
279 * as its arguments. This could result in a SecurityException.
280 *
281 * @param address the remote address
282 * @param port the remote port
283 * @param localAddr the local address the socket is bound to
284 * @param localPort the local port the socket is bound to
285 * @exception IOException if an I/O error occurs when creating the socket.
286 * @exception SecurityException if a security manager exists and its
287 * <code>checkConnect</code> method doesn't allow the operation.
288 * @see SecurityManager#checkConnect
289 * @since JDK1.1
290 */
291 public Socket(InetAddress address, int port, InetAddress localAddr,
292 int localPort) throws IOException {
293 this(address != null ? new InetSocketAddress(address, port) : null,
294 new InetSocketAddress(localAddr, localPort), true);
295 }
296
297 /**
298 * Creates a stream socket and connects it to the specified port
299 * number on the named host.
300 * <p>
301 * If the specified host is <tt>null</tt> it is the equivalent of
302 * specifying the address as <tt>{@link java.net.InetAddress#getByName InetAddress.getByName}(null)</tt>.
303 * In other words, it is equivalent to specifying an address of the
304 * loopback interface. </p>
305 * <p>
306 * If the stream argument is <code>true</code>, this creates a
307 * stream socket. If the stream argument is <code>false</code>, it
308 * creates a datagram socket.
309 * <p>
310 * If the application has specified a server socket factory, that
311 * factory's <code>createSocketImpl</code> method is called to create
312 * the actual socket implementation. Otherwise a "plain" socket is created.
313 * <p>
314 * If there is a security manager, its
315 * <code>checkConnect</code> method is called
316 * with the host address and <code>port</code>
317 * as its arguments. This could result in a SecurityException.
318 * <p>
319 * If a UDP socket is used, TCP/IP related socket options will not apply.
320 *
321 * @param host the host name, or <code>null</code> for the loopback address.
322 * @param port the port number.
323 * @param stream a <code>boolean</code> indicating whether this is
324 * a stream socket or a datagram socket.
325 * @exception IOException if an I/O error occurs when creating the socket.
326 * @exception SecurityException if a security manager exists and its
327 * <code>checkConnect</code> method doesn't allow the operation.
328 * @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory)
329 * @see java.net.SocketImpl
330 * @see java.net.SocketImplFactory#createSocketImpl()
331 * @see SecurityManager#checkConnect
332 * @deprecated Use DatagramSocket instead for UDP transport.
333 */
334 @Deprecated
335 public Socket(String host, int port, boolean stream) throws IOException {
336 this(host != null ? new InetSocketAddress(host, port) :
337 new InetSocketAddress(InetAddress.getByName(null), port),
338 (SocketAddress) null, stream);
339 }
340
341 /**
342 * Creates a socket and connects it to the specified port number at
343 * the specified IP address.
344 * <p>
345 * If the stream argument is <code>true</code>, this creates a
346 * stream socket. If the stream argument is <code>false</code>, it
347 * creates a datagram socket.
348 * <p>
349 * If the application has specified a server socket factory, that
350 * factory's <code>createSocketImpl</code> method is called to create
351 * the actual socket implementation. Otherwise a "plain" socket is created.
352 *
353 * <p>If there is a security manager, its
354 * <code>checkConnect</code> method is called
355 * with <code>host.getHostAddress()</code> and <code>port</code>
356 * as its arguments. This could result in a SecurityException.
357 * <p>
358 * If UDP socket is used, TCP/IP related socket options will not apply.
359 *
360 * @param host the IP address.
361 * @param port the port number.
362 * @param stream if <code>true</code>, create a stream socket;
363 * otherwise, create a datagram socket.
364 * @exception IOException if an I/O error occurs when creating the socket.
365 * @exception SecurityException if a security manager exists and its
366 * <code>checkConnect</code> method doesn't allow the operation.
367 * @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory)
368 * @see java.net.SocketImpl
369 * @see java.net.SocketImplFactory#createSocketImpl()
370 * @see SecurityManager#checkConnect
371 * @deprecated Use DatagramSocket instead for UDP transport.
372 */
373 @Deprecated
374 public Socket(InetAddress host, int port, boolean stream) throws IOException {
375 this(host != null ? new InetSocketAddress(host, port) : null,
376 new InetSocketAddress(0), stream);
377 }
378
379 private Socket(SocketAddress address, SocketAddress localAddr,
380 boolean stream) throws IOException {
381 setImpl();
382
383 // backward compatibility
384 if (address == null)
385 throw new NullPointerException();
386
387 try {
388 createImpl(stream);
389 if (localAddr != null)
390 bind(localAddr);
391 if (address != null)
392 connect(address);
393 } catch (IOException e) {
394 close();
395 throw e;
396 }
397 }
398
399 /**
400 * Creates the socket implementation.
401 *
402 * @param stream a <code>boolean</code> value : <code>true</code> for a TCP socket,
403 * <code>false</code> for UDP.
404 * @throws IOException if creation fails
405 * @since 1.4
406 */
407 void createImpl(boolean stream) throws SocketException {
408 if (impl == null)
409 setImpl();
410 try {
411 impl.create(stream);
412 created = true;
413 } catch (IOException e) {
414 throw new SocketException(e.getMessage());
415 }
416 }
417
418 private void checkOldImpl() {
419 if (impl == null)
420 return;
421 // SocketImpl.connect() is a protected method, therefore we need to use
422 // getDeclaredMethod, therefore we need permission to access the member
423
424 oldImpl = AccessController.doPrivileged
425 (new PrivilegedAction<Boolean>() {
426 public Boolean run() {
427 Class<?> clazz = impl.getClass();
428 while (true) {
429 try {
430 clazz.getDeclaredMethod("connect", SocketAddress.class, int.class);
431 return Boolean.FALSE;
432 } catch (NoSuchMethodException e) {
433 clazz = clazz.getSuperclass();
434 // java.net.SocketImpl class will always have this abstract method.
435 // If we have not found it by now in the hierarchy then it does not
436 // exist, we are an old style impl.
437 if (clazz.equals(java.net.SocketImpl.class)) {
438 return Boolean.TRUE;
439 }
440 }
441 }
442 }
443 });
444 }
445
446 /**
447 * Sets impl to the system-default type of SocketImpl.
448 * @since 1.4
449 */
450 void setImpl() {
451 if (factory != null) {
452 impl = factory.createSocketImpl();
453 checkOldImpl();
454 } else {
455 // No need to do a checkOldImpl() here, we know it's an up to date
456 // SocketImpl!
457 impl = new SocksSocketImpl();
458 }
459 if (impl != null)
460 impl.setSocket(this);
461 }
462
463
464 /**
465 * Get the <code>SocketImpl</code> attached to this socket, creating
466 * it if necessary.
467 *
468 * @return the <code>SocketImpl</code> attached to that ServerSocket.
469 * @throws SocketException if creation fails
470 * @since 1.4
471 */
472 SocketImpl getImpl() throws SocketException {
473 if (!created)
474 createImpl(true);
475 return impl;
476 }
477
478 /**
479 * Connects this socket to the server.
480 *
481 * @param endpoint the <code>SocketAddress</code>
482 * @throws IOException if an error occurs during the connection
483 * @throws java.nio.channels.IllegalBlockingModeException
484 * if this socket has an associated channel,
485 * and the channel is in non-blocking mode
486 * @throws IllegalArgumentException if endpoint is null or is a
487 * SocketAddress subclass not supported by this socket
488 * @since 1.4
489 * @spec JSR-51
490 */
491 public void connect(SocketAddress endpoint) throws IOException {
492 connect(endpoint, 0);
493 }
494
495 /**
496 * Connects this socket to the server with a specified timeout value.
497 * A timeout of zero is interpreted as an infinite timeout. The connection
498 * will then block until established or an error occurs.
499 *
500 * @param endpoint the <code>SocketAddress</code>
501 * @param timeout the timeout value to be used in milliseconds.
502 * @throws IOException if an error occurs during the connection
503 * @throws SocketTimeoutException if timeout expires before connecting
504 * @throws java.nio.channels.IllegalBlockingModeException
505 * if this socket has an associated channel,
506 * and the channel is in non-blocking mode
507 * @throws IllegalArgumentException if endpoint is null or is a
508 * SocketAddress subclass not supported by this socket
509 * @since 1.4
510 * @spec JSR-51
511 */
512 public void connect(SocketAddress endpoint, int timeout) throws IOException {
513 if (endpoint == null)
514 throw new IllegalArgumentException("connect: The address can't be null");
515
516 if (timeout < 0)
517 throw new IllegalArgumentException("connect: timeout can't be negative");
518
519 if (isClosed())
520 throw new SocketException("Socket is closed");
521
522 if (!oldImpl && isConnected())
523 throw new SocketException("already connected");
524
525 if (!(endpoint instanceof InetSocketAddress))
526 throw new IllegalArgumentException("Unsupported address type");
527
528 InetSocketAddress epoint = (InetSocketAddress) endpoint;
529 InetAddress addr = epoint.getAddress ();
530 int port = epoint.getPort();
531 checkAddress(addr, "connect");
532
533 SecurityManager security = System.getSecurityManager();
534 if (security != null) {
535 if (epoint.isUnresolved())
536 security.checkConnect(epoint.getHostName(), port);
537 else
538 security.checkConnect(addr.getHostAddress(), port);
539 }
540 if (!created)
541 createImpl(true);
542 if (!oldImpl)
543 impl.connect(epoint, timeout);
544 else if (timeout == 0) {
545 if (epoint.isUnresolved())
546 impl.connect(addr.getHostName(), port);
547 else
548 impl.connect(addr, port);
549 } else
550 throw new UnsupportedOperationException("SocketImpl.connect(addr, timeout)");
551 connected = true;
552 /*
553 * If the socket was not bound before the connect, it is now because
554 * the kernel will have picked an ephemeral port & a local address
555 */
556 bound = true;
557 }
558
559 /**
560 * Binds the socket to a local address.
561 * <P>
562 * If the address is <code>null</code>, then the system will pick up
563 * an ephemeral port and a valid local address to bind the socket.
564 *
565 * @param bindpoint the <code>SocketAddress</code> to bind to
566 * @throws IOException if the bind operation fails, or if the socket
567 * is already bound.
568 * @throws IllegalArgumentException if bindpoint is a
569 * SocketAddress subclass not supported by this socket
570 *
571 * @since 1.4
572 * @see #isBound
573 */
574 public void bind(SocketAddress bindpoint) throws IOException {
575 if (isClosed())
576 throw new SocketException("Socket is closed");
577 if (!oldImpl && isBound())
578 throw new SocketException("Already bound");
579
580 if (bindpoint != null && (!(bindpoint instanceof InetSocketAddress)))
581 throw new IllegalArgumentException("Unsupported address type");
582 InetSocketAddress epoint = (InetSocketAddress) bindpoint;
583 if (epoint != null && epoint.isUnresolved())
584 throw new SocketException("Unresolved address");
585 if (epoint == null) {
586 epoint = new InetSocketAddress(0);
587 }
588 InetAddress addr = epoint.getAddress();
589 int port = epoint.getPort();
590 checkAddress (addr, "bind");
591 SecurityManager security = System.getSecurityManager();
592 if (security != null) {
593 security.checkListen(port);
594 }
595 getImpl().bind (addr, port);
596 bound = true;
597 }
598
599 private void checkAddress (InetAddress addr, String op) {
600 if (addr == null) {
601 return;
602 }
603 if (!(addr instanceof Inet4Address || addr instanceof Inet6Address)) {
604 throw new IllegalArgumentException(op + ": invalid address type");
605 }
606 }
607
608 /**
609 * set the flags after an accept() call.
610 */
611 final void postAccept() {
612 connected = true;
613 created = true;
614 bound = true;
615 }
616
617 void setCreated() {
618 created = true;
619 }
620
621 void setBound() {
622 bound = true;
623 }
624
625 void setConnected() {
626 connected = true;
627 }
628
629 /**
630 * Returns the address to which the socket is connected.
631 *
632 * @return the remote IP address to which this socket is connected,
633 * or <code>null</code> if the socket is not connected.
634 */
635 public InetAddress getInetAddress() {
636 if (!isConnected())
637 return null;
638 try {
639 return getImpl().getInetAddress();
640 } catch (SocketException e) {
641 }
642 return null;
643 }
644
645 /**
646 * Gets the local address to which the socket is bound.
647 *
648 * @return the local address to which the socket is bound or
649 * <code>InetAddress.anyLocalAddress()</code>
650 * if the socket is not bound yet.
651 * @since JDK1.1
652 */
653 public InetAddress getLocalAddress() {
654 // This is for backward compatibility
655 if (!isBound())
656 return InetAddress.anyLocalAddress();
657 InetAddress in = null;
658 try {
659 in = (InetAddress) getImpl().getOption(SocketOptions.SO_BINDADDR);
660
661 if (!NetUtil.doRevealLocalAddress()) {
662 SecurityManager sm = System.getSecurityManager();
663 if (sm != null)
664 sm.checkConnect(in.getHostAddress(), -1);
665 }
666 if (in.isAnyLocalAddress()) {
667 in = InetAddress.anyLocalAddress();
668 }
669 } catch (SecurityException e) {
670 in = InetAddress.impl.loopbackAddress();
671 } catch (Exception e) {
672 in = InetAddress.anyLocalAddress(); // "0.0.0.0"
673 }
674 return in;
675 }
676
677 /**
678 * Returns the remote port number to which this socket is connected.
679 *
680 * @return the remote port number to which this socket is connected, or
681 * 0 if the socket is not connected yet.
682 */
683 public int getPort() {
684 if (!isConnected())
685 return 0;
686 try {
687 return getImpl().getPort();
688 } catch (SocketException e) {
689 // Shouldn't happen as we're connected
690 }
691 return -1;
692 }
693
694 /**
695 * Returns the local port number to which this socket is bound.
696 *
697 * @return the local port number to which this socket is bound or -1
698 * if the socket is not bound yet.
699 */
700 public int getLocalPort() {
701 if (!isBound())
702 return -1;
703 try {
704 return getImpl().getLocalPort();
705 } catch(SocketException e) {
706 // shouldn't happen as we're bound
707 }
708 return -1;
709 }
710
711 /**
712 * Returns the address of the endpoint this socket is connected to, or
713 * <code>null</code> if it is unconnected.
714 *
715 * @return a <code>SocketAddress</code> reprensenting the remote endpoint of this
716 * socket, or <code>null</code> if it is not connected yet.
717 * @see #getInetAddress()
718 * @see #getPort()
719 * @see #connect(SocketAddress, int)
720 * @see #connect(SocketAddress)
721 * @since 1.4
722 */
723 public SocketAddress getRemoteSocketAddress() {
724 if (!isConnected())
725 return null;
726 return new InetSocketAddress(getInetAddress(), getPort());
727 }
728
729 /**
730 * Returns the address of the endpoint this socket is bound to, or
731 * <code>null</code> if it is not bound yet.
732 *
733 * @return a <code>SocketAddress</code> representing the local endpoint of this
734 * socket, or <code>null</code> if it is not bound yet.
735 * @see #getLocalAddress()
736 * @see #getLocalPort()
737 * @see #bind(SocketAddress)
738 * @since 1.4
739 */
740
741 public SocketAddress getLocalSocketAddress() {
742 if (!isBound())
743 return null;
744 return new InetSocketAddress(getLocalAddress(), getLocalPort());
745 }
746
747 /**
748 * Returns the unique {@link java.nio.channels.SocketChannel SocketChannel}
749 * object associated with this socket, if any.
750 *
751 * <p> A socket will have a channel if, and only if, the channel itself was
752 * created via the {@link java.nio.channels.SocketChannel#open
753 * SocketChannel.open} or {@link
754 * java.nio.channels.ServerSocketChannel#accept ServerSocketChannel.accept}
755 * methods.
756 *
757 * @return the socket channel associated with this socket,
758 * or <tt>null</tt> if this socket was not created
759 * for a channel
760 *
761 * @since 1.4
762 * @spec JSR-51
763 */
764 public SocketChannel getChannel() {
765 return null;
766 }
767
768 /**
769 * Returns an input stream for this socket.
770 *
771 * <p> If this socket has an associated channel then the resulting input
772 * stream delegates all of its operations to the channel. If the channel
773 * is in non-blocking mode then the input stream's <tt>read</tt> operations
774 * will throw an {@link java.nio.channels.IllegalBlockingModeException}.
775 *
776 * <p>Under abnormal conditions the underlying connection may be
777 * broken by the remote host or the network software (for example
778 * a connection reset in the case of TCP connections). When a
779 * broken connection is detected by the network software the
780 * following applies to the returned input stream :-
781 *
782 * <ul>
783 *
784 * <li><p>The network software may discard bytes that are buffered
785 * by the socket. Bytes that aren't discarded by the network
786 * software can be read using {@link java.io.InputStream#read read}.
787 *
788 * <li><p>If there are no bytes buffered on the socket, or all
789 * buffered bytes have been consumed by
790 * {@link java.io.InputStream#read read}, then all subsequent
791 * calls to {@link java.io.InputStream#read read} will throw an
792 * {@link java.io.IOException IOException}.
793 *
794 * <li><p>If there are no bytes buffered on the socket, and the
795 * socket has not been closed using {@link #close close}, then
796 * {@link java.io.InputStream#available available} will
797 * return <code>0</code>.
798 *
799 * </ul>
800 *
801 * <p> Closing the returned {@link java.io.InputStream InputStream}
802 * will close the associated socket.
803 *
804 * @return an input stream for reading bytes from this socket.
805 * @exception IOException if an I/O error occurs when creating the
806 * input stream, the socket is closed, the socket is
807 * not connected, or the socket input has been shutdown
808 * using {@link #shutdownInput()}
809 *
810 * @revised 1.4
811 * @spec JSR-51
812 */
813 public InputStream getInputStream() throws IOException {
814 if (isClosed())
815 throw new SocketException("Socket is closed");
816 if (!isConnected())
817 throw new SocketException("Socket is not connected");
818 if (isInputShutdown())
819 throw new SocketException("Socket input is shutdown");
820 final Socket s = this;
821 InputStream is = null;
822 try {
823 is = AccessController.doPrivileged(
824 new PrivilegedExceptionAction<InputStream>() {
825 public InputStream run() throws IOException {
826 return impl.getInputStream();
827 }
828 });
829 } catch (java.security.PrivilegedActionException e) {
830 throw (IOException) e.getException();
831 }
832 return is;
833 }
834
835 /**
836 * Returns an output stream for this socket.
837 *
838 * <p> If this socket has an associated channel then the resulting output
839 * stream delegates all of its operations to the channel. If the channel
840 * is in non-blocking mode then the output stream's <tt>write</tt>
841 * operations will throw an {@link
842 * java.nio.channels.IllegalBlockingModeException}.
843 *
844 * <p> Closing the returned {@link java.io.OutputStream OutputStream}
845 * will close the associated socket.
846 *
847 * @return an output stream for writing bytes to this socket.
848 * @exception IOException if an I/O error occurs when creating the
849 * output stream or if the socket is not connected.
850 * @revised 1.4
851 * @spec JSR-51
852 */
853 public OutputStream getOutputStream() throws IOException {
854 if (isClosed())
855 throw new SocketException("Socket is closed");
856 if (!isConnected())
857 throw new SocketException("Socket is not connected");
858 if (isOutputShutdown())
859 throw new SocketException("Socket output is shutdown");
860 final Socket s = this;
861 OutputStream os = null;
862 try {
863 os = AccessController.doPrivileged(
864 new PrivilegedExceptionAction<OutputStream>() {
865 public OutputStream run() throws IOException {
866 return impl.getOutputStream();
867 }
868 });
869 } catch (java.security.PrivilegedActionException e) {
870 throw (IOException) e.getException();
871 }
872 return os;
873 }
874
875 /**
876 * Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm).
877 *
878 * @param on <code>true</code> to enable TCP_NODELAY,
879 * <code>false</code> to disable.
880 *
881 * @exception SocketException if there is an error
882 * in the underlying protocol, such as a TCP error.
883 *
884 * @since JDK1.1
885 *
886 * @see #getTcpNoDelay()
887 */
888 public void setTcpNoDelay(boolean on) throws SocketException {
889 if (isClosed())
890 throw new SocketException("Socket is closed");
891 getImpl().setOption(SocketOptions.TCP_NODELAY, Boolean.valueOf(on));
892 }
893
894 /**
895 * Tests if TCP_NODELAY is enabled.
896 *
897 * @return a <code>boolean</code> indicating whether or not TCP_NODELAY is enabled.
898 * @exception SocketException if there is an error
899 * in the underlying protocol, such as a TCP error.
900 * @since JDK1.1
901 * @see #setTcpNoDelay(boolean)
902 */
903 public boolean getTcpNoDelay() throws SocketException {
904 if (isClosed())
905 throw new SocketException("Socket is closed");
906 return ((Boolean) getImpl().getOption(SocketOptions.TCP_NODELAY)).booleanValue();
907 }
908
909 /**
910 * Enable/disable SO_LINGER with the specified linger time in seconds.
911 * The maximum timeout value is platform specific.
912 *
913 * The setting only affects socket close.
914 *
915 * @param on whether or not to linger on.
916 * @param linger how long to linger for, if on is true.
917 * @exception SocketException if there is an error
918 * in the underlying protocol, such as a TCP error.
919 * @exception IllegalArgumentException if the linger value is negative.
920 * @since JDK1.1
921 * @see #getSoLinger()
922 */
923 public void setSoLinger(boolean on, int linger) throws SocketException {
924 if (isClosed())
925 throw new SocketException("Socket is closed");
926 if (!on) {
927 getImpl().setOption(SocketOptions.SO_LINGER, new Boolean(on));
928 } else {
929 if (linger < 0) {
930 throw new IllegalArgumentException("invalid value for SO_LINGER");
931 }
932 if (linger > 65535)
933 linger = 65535;
934 getImpl().setOption(SocketOptions.SO_LINGER, new Integer(linger));
935 }
936 }
937
938 /**
939 * Returns setting for SO_LINGER. -1 returns implies that the
940 * option is disabled.
941 *
942 * The setting only affects socket close.
943 *
944 * @return the setting for SO_LINGER.
945 * @exception SocketException if there is an error
946 * in the underlying protocol, such as a TCP error.
947 * @since JDK1.1
948 * @see #setSoLinger(boolean, int)
949 */
950 public int getSoLinger() throws SocketException {
951 if (isClosed())
952 throw new SocketException("Socket is closed");
953 Object o = getImpl().getOption(SocketOptions.SO_LINGER);
954 if (o instanceof Integer) {
955 return ((Integer) o).intValue();
956 } else {
957 return -1;
958 }
959 }
960
961 /**
962 * Send one byte of urgent data on the socket. The byte to be sent is the lowest eight
963 * bits of the data parameter. The urgent byte is
964 * sent after any preceding writes to the socket OutputStream
965 * and before any future writes to the OutputStream.
966 * @param data The byte of data to send
967 * @exception IOException if there is an error
968 * sending the data.
969 * @since 1.4
970 */
971 public void sendUrgentData (int data) throws IOException {
972 if (!getImpl().supportsUrgentData ()) {
973 throw new SocketException ("Urgent data not supported");
974 }
975 getImpl().sendUrgentData (data);
976 }
977
978 /**
979 * Enable/disable OOBINLINE (receipt of TCP urgent data)
980 *
981 * By default, this option is disabled and TCP urgent data received on a
982 * socket is silently discarded. If the user wishes to receive urgent data, then
983 * this option must be enabled. When enabled, urgent data is received
984 * inline with normal data.
985 * <p>
986 * Note, only limited support is provided for handling incoming urgent
987 * data. In particular, no notification of incoming urgent data is provided
988 * and there is no capability to distinguish between normal data and urgent
989 * data unless provided by a higher level protocol.
990 *
991 * @param on <code>true</code> to enable OOBINLINE,
992 * <code>false</code> to disable.
993 *
994 * @exception SocketException if there is an error
995 * in the underlying protocol, such as a TCP error.
996 *
997 * @since 1.4
998 *
999 * @see #getOOBInline()
1000 */
1001 public void setOOBInline(boolean on) throws SocketException {
1002 if (isClosed())
1003 throw new SocketException("Socket is closed");
1004 getImpl().setOption(SocketOptions.SO_OOBINLINE, Boolean.valueOf(on));
1005 }
1006
1007 /**
1008 * Tests if OOBINLINE is enabled.
1009 *
1010 * @return a <code>boolean</code> indicating whether or not OOBINLINE is enabled.
1011 * @exception SocketException if there is an error
1012 * in the underlying protocol, such as a TCP error.
1013 * @since 1.4
1014 * @see #setOOBInline(boolean)
1015 */
1016 public boolean getOOBInline() throws SocketException {
1017 if (isClosed())
1018 throw new SocketException("Socket is closed");
1019 return ((Boolean) getImpl().getOption(SocketOptions.SO_OOBINLINE)).booleanValue();
1020 }
1021
1022 /**
1023 * Enable/disable SO_TIMEOUT with the specified timeout, in
1024 * milliseconds. With this option set to a non-zero timeout,
1025 * a read() call on the InputStream associated with this Socket
1026 * will block for only this amount of time. If the timeout expires,
1027 * a <B>java.net.SocketTimeoutException</B> is raised, though the
1028 * Socket is still valid. The option <B>must</B> be enabled
1029 * prior to entering the blocking operation to have effect. The
1030 * timeout must be > 0.
1031 * A timeout of zero is interpreted as an infinite timeout.
1032 * @param timeout the specified timeout, in milliseconds.
1033 * @exception SocketException if there is an error
1034 * in the underlying protocol, such as a TCP error.
1035 * @since JDK 1.1
1036 * @see #getSoTimeout()
1037 */
1038 public synchronized void setSoTimeout(int timeout) throws SocketException {
1039 if (isClosed())
1040 throw new SocketException("Socket is closed");
1041 if (timeout < 0)
1042 throw new IllegalArgumentException("timeout can't be negative");
1043
1044 getImpl().setOption(SocketOptions.SO_TIMEOUT, new Integer(timeout));
1045 }
1046
1047 /**
1048 * Returns setting for SO_TIMEOUT. 0 returns implies that the
1049 * option is disabled (i.e., timeout of infinity).
1050 * @return the setting for SO_TIMEOUT
1051 * @exception SocketException if there is an error
1052 * in the underlying protocol, such as a TCP error.
1053 * @since JDK1.1
1054 * @see #setSoTimeout(int)
1055 */
1056 public synchronized int getSoTimeout() throws SocketException {
1057 if (isClosed())
1058 throw new SocketException("Socket is closed");
1059 Object o = getImpl().getOption(SocketOptions.SO_TIMEOUT);
1060 /* extra type safety */
1061 if (o instanceof Integer) {
1062 return ((Integer) o).intValue();
1063 } else {
1064 return 0;
1065 }
1066 }
1067
1068 /**
1069 * Sets the SO_SNDBUF option to the specified value for this
1070 * <tt>Socket</tt>. The SO_SNDBUF option is used by the platform's
1071 * networking code as a hint for the size to set
1072 * the underlying network I/O buffers.
1073 *
1074 * <p>Because SO_SNDBUF is a hint, applications that want to
1075 * verify what size the buffers were set to should call
1076 * {@link #getSendBufferSize()}.
1077 *
1078 * @exception SocketException if there is an error
1079 * in the underlying protocol, such as a TCP error.
1080 *
1081 * @param size the size to which to set the send buffer
1082 * size. This value must be greater than 0.
1083 *
1084 * @exception IllegalArgumentException if the
1085 * value is 0 or is negative.
1086 *
1087 * @see #getSendBufferSize()
1088 * @since 1.2
1089 */
1090 public synchronized void setSendBufferSize(int size)
1091 throws SocketException{
1092 if (!(size > 0)) {
1093 throw new IllegalArgumentException("negative send size");
1094 }
1095 if (isClosed())
1096 throw new SocketException("Socket is closed");
1097 getImpl().setOption(SocketOptions.SO_SNDBUF, new Integer(size));
1098 }
1099
1100 /**
1101 * Get value of the SO_SNDBUF option for this <tt>Socket</tt>,
1102 * that is the buffer size used by the platform
1103 * for output on this <tt>Socket</tt>.
1104 * @return the value of the SO_SNDBUF option for this <tt>Socket</tt>.
1105 *
1106 * @exception SocketException if there is an error
1107 * in the underlying protocol, such as a TCP error.
1108 *
1109 * @see #setSendBufferSize(int)
1110 * @since 1.2
1111 */
1112 public synchronized int getSendBufferSize() throws SocketException {
1113 if (isClosed())
1114 throw new SocketException("Socket is closed");
1115 int result = 0;
1116 Object o = getImpl().getOption(SocketOptions.SO_SNDBUF);
1117 if (o instanceof Integer) {
1118 result = ((Integer)o).intValue();
1119 }
1120 return result;
1121 }
1122
1123 /**
1124 * Sets the SO_RCVBUF option to the specified value for this
1125 * <tt>Socket</tt>. The SO_RCVBUF option is used by the platform's
1126 * networking code as a hint for the size to set
1127 * the underlying network I/O buffers.
1128 *
1129 * <p>Increasing the receive buffer size can increase the performance of
1130 * network I/O for high-volume connection, while decreasing it can
1131 * help reduce the backlog of incoming data.
1132 *
1133 * <p>Because SO_RCVBUF is a hint, applications that want to
1134 * verify what size the buffers were set to should call
1135 * {@link #getReceiveBufferSize()}.
1136 *
1137 * <p>The value of SO_RCVBUF is also used to set the TCP receive window
1138 * that is advertized to the remote peer. Generally, the window size
1139 * can be modified at any time when a socket is connected. However, if
1140 * a receive window larger than 64K is required then this must be requested
1141 * <B>before</B> the socket is connected to the remote peer. There are two
1142 * cases to be aware of:<p>
1143 * <ol>
1144 * <li>For sockets accepted from a ServerSocket, this must be done by calling
1145 * {@link ServerSocket#setReceiveBufferSize(int)} before the ServerSocket
1146 * is bound to a local address.<p></li>
1147 * <li>For client sockets, setReceiveBufferSize() must be called before
1148 * connecting the socket to its remote peer.<p></li></ol>
1149 * @param size the size to which to set the receive buffer
1150 * size. This value must be greater than 0.
1151 *
1152 * @exception IllegalArgumentException if the value is 0 or is
1153 * negative.
1154 *
1155 * @exception SocketException if there is an error
1156 * in the underlying protocol, such as a TCP error.
1157 *
1158 * @see #getReceiveBufferSize()
1159 * @see ServerSocket#setReceiveBufferSize(int)
1160 * @since 1.2
1161 */
1162 public synchronized void setReceiveBufferSize(int size)
1163 throws SocketException{
1164 if (size <= 0) {
1165 throw new IllegalArgumentException("invalid receive size");
1166 }
1167 if (isClosed())
1168 throw new SocketException("Socket is closed");
1169 getImpl().setOption(SocketOptions.SO_RCVBUF, new Integer(size));
1170 }
1171
1172 /**
1173 * Gets the value of the SO_RCVBUF option for this <tt>Socket</tt>,
1174 * that is the buffer size used by the platform for
1175 * input on this <tt>Socket</tt>.
1176 *
1177 * @return the value of the SO_RCVBUF option for this <tt>Socket</tt>.
1178 * @exception SocketException if there is an error
1179 * in the underlying protocol, such as a TCP error.
1180 * @see #setReceiveBufferSize(int)
1181 * @since 1.2
1182 */
1183 public synchronized int getReceiveBufferSize()
1184 throws SocketException{
1185 if (isClosed())
1186 throw new SocketException("Socket is closed");
1187 int result = 0;
1188 Object o = getImpl().getOption(SocketOptions.SO_RCVBUF);
1189 if (o instanceof Integer) {
1190 result = ((Integer)o).intValue();
1191 }
1192 return result;
1193 }
1194
1195 /**
1196 * Enable/disable SO_KEEPALIVE.
1197 *
1198 * @param on whether or not to have socket keep alive turned on.
1199 * @exception SocketException if there is an error
1200 * in the underlying protocol, such as a TCP error.
1201 * @since 1.3
1202 * @see #getKeepAlive()
1203 */
1204 public void setKeepAlive(boolean on) throws SocketException {
1205 if (isClosed())
1206 throw new SocketException("Socket is closed");
1207 getImpl().setOption(SocketOptions.SO_KEEPALIVE, Boolean.valueOf(on));
1208 }
1209
1210 /**
1211 * Tests if SO_KEEPALIVE is enabled.
1212 *
1213 * @return a <code>boolean</code> indicating whether or not SO_KEEPALIVE is enabled.
1214 * @exception SocketException if there is an error
1215 * in the underlying protocol, such as a TCP error.
1216 * @since 1.3
1217 * @see #setKeepAlive(boolean)
1218 */
1219 public boolean getKeepAlive() throws SocketException {
1220 if (isClosed())
1221 throw new SocketException("Socket is closed");
1222 return ((Boolean) getImpl().getOption(SocketOptions.SO_KEEPALIVE)).booleanValue();
1223 }
1224
1225 /**
1226 * Sets traffic class or type-of-service octet in the IP
1227 * header for packets sent from this Socket.
1228 * As the underlying network implementation may ignore this
1229 * value applications should consider it a hint.
1230 *
1231 * <P> The tc <B>must</B> be in the range <code> 0 <= tc <=
1232 * 255</code> or an IllegalArgumentException will be thrown.
1233 * <p>Notes:
1234 * <p> For Internet Protocol v4 the value consists of an octet
1235 * with precedence and TOS fields as detailed in RFC 1349. The
1236 * TOS field is bitset created by bitwise-or'ing values such
1237 * the following :-
1238 * <p>
1239 * <UL>
1240 * <LI><CODE>IPTOS_LOWCOST (0x02)</CODE></LI>
1241 * <LI><CODE>IPTOS_RELIABILITY (0x04)</CODE></LI>
1242 * <LI><CODE>IPTOS_THROUGHPUT (0x08)</CODE></LI>
1243 * <LI><CODE>IPTOS_LOWDELAY (0x10)</CODE></LI>
1244 * </UL>
1245 * The last low order bit is always ignored as this
1246 * corresponds to the MBZ (must be zero) bit.
1247 * <p>
1248 * Setting bits in the precedence field may result in a
1249 * SocketException indicating that the operation is not
1250 * permitted.
1251 * <p>
1252 * As RFC 1122 section 4.2.4.2 indicates, a compliant TCP
1253 * implementation should, but is not required to, let application
1254 * change the TOS field during the lifetime of a connection.
1255 * So whether the type-of-service field can be changed after the
1256 * TCP connection has been established depends on the implementation
1257 * in the underlying platform. Applications should not assume that
1258 * they can change the TOS field after the connection.
1259 * <p>
1260 * For Internet Protocol v6 <code>tc</code> is the value that
1261 * would be placed into the sin6_flowinfo field of the IP header.
1262 *
1263 * @param tc an <code>int</code> value for the bitset.
1264 * @throws SocketException if there is an error setting the
1265 * traffic class or type-of-service
1266 * @since 1.4
1267 * @see #getTrafficClass
1268 */
1269 public void setTrafficClass(int tc) throws SocketException {
1270 if (tc < 0 || tc > 255)
1271 throw new IllegalArgumentException("tc is not in range 0 -- 255");
1272
1273 if (isClosed())
1274 throw new SocketException("Socket is closed");
1275 getImpl().setOption(SocketOptions.IP_TOS, new Integer(tc));
1276 }
1277
1278 /**
1279 * Gets traffic class or type-of-service in the IP header
1280 * for packets sent from this Socket
1281 * <p>
1282 * As the underlying network implementation may ignore the
1283 * traffic class or type-of-service set using {@link #setTrafficClass(int)}
1284 * this method may return a different value than was previously
1285 * set using the {@link #setTrafficClass(int)} method on this Socket.
1286 *
1287 * @return the traffic class or type-of-service already set
1288 * @throws SocketException if there is an error obtaining the
1289 * traffic class or type-of-service value.
1290 * @since 1.4
1291 * @see #setTrafficClass(int)
1292 */
1293 public int getTrafficClass() throws SocketException {
1294 return ((Integer) (getImpl().getOption(SocketOptions.IP_TOS))).intValue();
1295 }
1296
1297 /**
1298 * Enable/disable the SO_REUSEADDR socket option.
1299 * <p>
1300 * When a TCP connection is closed the connection may remain
1301 * in a timeout state for a period of time after the connection
1302 * is closed (typically known as the <tt>TIME_WAIT</tt> state
1303 * or <tt>2MSL</tt> wait state).
1304 * For applications using a well known socket address or port
1305 * it may not be possible to bind a socket to the required
1306 * <tt>SocketAddress</tt> if there is a connection in the
1307 * timeout state involving the socket address or port.
1308 * <p>
1309 * Enabling <tt>SO_REUSEADDR</tt> prior to binding the socket
1310 * using {@link #bind(SocketAddress)} allows the socket to be
1311 * bound even though a previous connection is in a timeout
1312 * state.
1313 * <p>
1314 * When a <tt>Socket</tt> is created the initial setting
1315 * of <tt>SO_REUSEADDR</tt> is disabled.
1316 * <p>
1317 * The behaviour when <tt>SO_REUSEADDR</tt> is enabled or
1318 * disabled after a socket is bound (See {@link #isBound()})
1319 * is not defined.
1320 *
1321 * @param on whether to enable or disable the socket option
1322 * @exception SocketException if an error occurs enabling or
1323 * disabling the <tt>SO_RESUEADDR</tt> socket option,
1324 * or the socket is closed.
1325 * @since 1.4
1326 * @see #getReuseAddress()
1327 * @see #bind(SocketAddress)
1328 * @see #isClosed()
1329 * @see #isBound()
1330 */
1331 public void setReuseAddress(boolean on) throws SocketException {
1332 if (isClosed())
1333 throw new SocketException("Socket is closed");
1334 getImpl().setOption(SocketOptions.SO_REUSEADDR, Boolean.valueOf(on));
1335 }
1336
1337 /**
1338 * Tests if SO_REUSEADDR is enabled.
1339 *
1340 * @return a <code>boolean</code> indicating whether or not SO_REUSEADDR is enabled.
1341 * @exception SocketException if there is an error
1342 * in the underlying protocol, such as a TCP error.
1343 * @since 1.4
1344 * @see #setReuseAddress(boolean)
1345 */
1346 public boolean getReuseAddress() throws SocketException {
1347 if (isClosed())
1348 throw new SocketException("Socket is closed");
1349 return ((Boolean) (getImpl().getOption(SocketOptions.SO_REUSEADDR))).booleanValue();
1350 }
1351
1352 /**
1353 * Closes this socket.
1354 * <p>
1355 * Any thread currently blocked in an I/O operation upon this socket
1356 * will throw a {@link SocketException}.
1357 * <p>
1358 * Once a socket has been closed, it is not available for further networking
1359 * use (i.e. can't be reconnected or rebound). A new socket needs to be
1360 * created.
1361 *
1362 * <p> Closing this socket will also close the socket's
1363 * {@link java.io.InputStream InputStream} and
1364 * {@link java.io.OutputStream OutputStream}.
1365 *
1366 * <p> If this socket has an associated channel then the channel is closed
1367 * as well.
1368 *
1369 * @exception IOException if an I/O error occurs when closing this socket.
1370 * @revised 1.4
1371 * @spec JSR-51
1372 * @see #isClosed
1373 */
1374 public synchronized void close() throws IOException {
1375 synchronized(closeLock) {
1376 if (isClosed())
1377 return;
1378 if (created)
1379 impl.close();
1380 closed = true;
1381 }
1382 }
1383
1384 /**
1385 * Places the input stream for this socket at "end of stream".
1386 * Any data sent to the input stream side of the socket is acknowledged
1387 * and then silently discarded.
1388 * <p>
1389 * If you read from a socket input stream after invoking
1390 * shutdownInput() on the socket, the stream will return EOF.
1391 *
1392 * @exception IOException if an I/O error occurs when shutting down this
1393 * socket.
1394 *
1395 * @since 1.3
1396 * @see java.net.Socket#shutdownOutput()
1397 * @see java.net.Socket#close()
1398 * @see java.net.Socket#setSoLinger(boolean, int)
1399 * @see #isInputShutdown
1400 */
1401 public void shutdownInput() throws IOException
1402 {
1403 if (isClosed())
1404 throw new SocketException("Socket is closed");
1405 if (!isConnected())
1406 throw new SocketException("Socket is not connected");
1407 if (isInputShutdown())
1408 throw new SocketException("Socket input is already shutdown");
1409 getImpl().shutdownInput();
1410 shutIn = true;
1411 }
1412
1413 /**
1414 * Disables the output stream for this socket.
1415 * For a TCP socket, any previously written data will be sent
1416 * followed by TCP's normal connection termination sequence.
1417 *
1418 * If you write to a socket output stream after invoking
1419 * shutdownOutput() on the socket, the stream will throw
1420 * an IOException.
1421 *
1422 * @exception IOException if an I/O error occurs when shutting down this
1423 * socket.
1424 *
1425 * @since 1.3
1426 * @see java.net.Socket#shutdownInput()
1427 * @see java.net.Socket#close()
1428 * @see java.net.Socket#setSoLinger(boolean, int)
1429 * @see #isOutputShutdown
1430 */
1431 public void shutdownOutput() throws IOException
1432 {
1433 if (isClosed())
1434 throw new SocketException("Socket is closed");
1435 if (!isConnected())
1436 throw new SocketException("Socket is not connected");
1437 if (isOutputShutdown())
1438 throw new SocketException("Socket output is already shutdown");
1439 getImpl().shutdownOutput();
1440 shutOut = true;
1441 }
1442
1443 /**
1444 * Converts this socket to a <code>String</code>.
1445 *
1446 * @return a string representation of this socket.
1447 */
1448 public String toString() {
1449 try {
1450 if (isConnected())
1451 return "Socket[addr=" + getImpl().getInetAddress() +
1452 ",port=" + getImpl().getPort() +
1453 ",localport=" + getImpl().getLocalPort() + "]";
1454 } catch (SocketException e) {
1455 }
1456 return "Socket[unconnected]";
1457 }
1458
1459 /**
1460 * Returns the connection state of the socket.
1461 *
1462 * @return true if the socket successfuly connected to a server
1463 * @since 1.4
1464 */
1465 public boolean isConnected() {
1466 // Before 1.3 Sockets were always connected during creation
1467 return connected || oldImpl;
1468 }
1469
1470 /**
1471 * Returns the binding state of the socket.
1472 *
1473 * @return true if the socket successfuly bound to an address
1474 * @since 1.4
1475 * @see #bind
1476 */
1477 public boolean isBound() {
1478 // Before 1.3 Sockets were always bound during creation
1479 return bound || oldImpl;
1480 }
1481
1482 /**
1483 * Returns the closed state of the socket.
1484 *
1485 * @return true if the socket has been closed
1486 * @since 1.4
1487 * @see #close
1488 */
1489 public boolean isClosed() {
1490 synchronized(closeLock) {
1491 return closed;
1492 }
1493 }
1494
1495 /**
1496 * Returns whether the read-half of the socket connection is closed.
1497 *
1498 * @return true if the input of the socket has been shutdown
1499 * @since 1.4
1500 * @see #shutdownInput
1501 */
1502 public boolean isInputShutdown() {
1503 return shutIn;
1504 }
1505
1506 /**
1507 * Returns whether the write-half of the socket connection is closed.
1508 *
1509 * @return true if the output of the socket has been shutdown
1510 * @since 1.4
1511 * @see #shutdownOutput
1512 */
1513 public boolean isOutputShutdown() {
1514 return shutOut;
1515 }
1516
1517 /**
1518 * The factory for all client sockets.
1519 */
1520 private static SocketImplFactory factory = null;
1521
1522 /**
1523 * Sets the client socket implementation factory for the
1524 * application. The factory can be specified only once.
1525 * <p>
1526 * When an application creates a new client socket, the socket
1527 * implementation factory's <code>createSocketImpl</code> method is
1528 * called to create the actual socket implementation.
1529 * <p>
1530 * Passing <code>null</code> to the method is a no-op unless the factory
1531 * was already set.
1532 * <p>If there is a security manager, this method first calls
1533 * the security manager's <code>checkSetFactory</code> method
1534 * to ensure the operation is allowed.
1535 * This could result in a SecurityException.
1536 *
1537 * @param fac the desired factory.
1538 * @exception IOException if an I/O error occurs when setting the
1539 * socket factory.
1540 * @exception SocketException if the factory is already defined.
1541 * @exception SecurityException if a security manager exists and its
1542 * <code>checkSetFactory</code> method doesn't allow the operation.
1543 * @see java.net.SocketImplFactory#createSocketImpl()
1544 * @see SecurityManager#checkSetFactory
1545 */
1546 public static synchronized void setSocketImplFactory(SocketImplFactory fac)
1547 throws IOException
1548 {
1549 if (factory != null) {
1550 throw new SocketException("factory already defined");
1551 }
1552 SecurityManager security = System.getSecurityManager();
1553 if (security != null) {
1554 security.checkSetFactory();
1555 }
1556 factory = fac;
1557 }
1558
1559 /**
1560 * Sets performance preferences for this socket.
1561 *
1562 * <p> Sockets use the TCP/IP protocol by default. Some implementations
1563 * may offer alternative protocols which have different performance
1564 * characteristics than TCP/IP. This method allows the application to
1565 * express its own preferences as to how these tradeoffs should be made
1566 * when the implementation chooses from the available protocols.
1567 *
1568 * <p> Performance preferences are described by three integers
1569 * whose values indicate the relative importance of short connection time,
1570 * low latency, and high bandwidth. The absolute values of the integers
1571 * are irrelevant; in order to choose a protocol the values are simply
1572 * compared, with larger values indicating stronger preferences. Negative
1573 * values represent a lower priority than positive values. If the
1574 * application prefers short connection time over both low latency and high
1575 * bandwidth, for example, then it could invoke this method with the values
1576 * <tt>(1, 0, 0)</tt>. If the application prefers high bandwidth above low
1577 * latency, and low latency above short connection time, then it could
1578 * invoke this method with the values <tt>(0, 1, 2)</tt>.
1579 *
1580 * <p> Invoking this method after this socket has been connected
1581 * will have no effect.
1582 *
1583 * @param connectionTime
1584 * An <tt>int</tt> expressing the relative importance of a short
1585 * connection time
1586 *
1587 * @param latency
1588 * An <tt>int</tt> expressing the relative importance of low
1589 * latency
1590 *
1591 * @param bandwidth
1592 * An <tt>int</tt> expressing the relative importance of high
1593 * bandwidth
1594 *
1595 * @since 1.5
1596 */
1597 public void setPerformancePreferences(int connectionTime,
1598 int latency,
1599 int bandwidth)
1600 {
1601 /* Not implemented yet */
1602 }
1603 }