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 * <P>
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.<p></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 }