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