View Javadoc
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 }