1 /*
   2  * Copyright (c) 1995, 2019, 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.FileDescriptor;
  29 import java.io.IOException;
  30 import java.io.InputStream;
  31 import java.io.OutputStream;
  32 import java.security.AccessController;
  33 import java.security.PrivilegedAction;
  34 import java.util.Objects;
  35 import java.util.Set;
  36 
  37 import sun.net.NetProperties;
  38 import sun.net.PlatformSocketImpl;
  39 import sun.nio.ch.NioSocketImpl;
  40 
  41 /**
  42  * The abstract class {@code SocketImpl} is a common superclass
  43  * of all classes that actually implement sockets. It is used to
  44  * create both client and server sockets.
  45  *
  46  * @implNote Client and server sockets created with the {@code Socket} and
  47  * {@code SocketServer} public constructors create a system-default
  48  * {@code SocketImpl}. The JDK historically used a {@code SocketImpl}
  49  * implementation type named "PlainSocketImpl" that has since been replaced by a
  50  * newer implementation. The JDK continues to ship with the older implementation
  51  * to allow code to run that depends on unspecified behavior that differs between
  52  * the old and new implementations. The old implementation will be used if the
  53  * Java virtual machine is started with the system property {@systemProperty
  54  * jdk.net.usePlainSocketImpl} set to use the old implementation. It may also be
  55  * set in the JDK's network configuration file, located in {@code
  56  * ${java.home}/conf/net.properties}. The value of the property is the string
  57  * representation of a boolean. If set without a value then it defaults to {@code
  58  * true}, hence running with {@code -Djdk.net.usePlainSocketImpl} or {@code
  59  * -Djdk.net.usePlainSocketImpl=true} will configure the Java virtual machine
  60  * to use the old implementation. The property and old implementation will be
  61  * removed in a future version.
  62  *
  63  * @author  unascribed
  64  * @since   1.0
  65  */
  66 public abstract class SocketImpl implements SocketOptions {
  67     private static final boolean USE_PLAINSOCKETIMPL = usePlainSocketImpl();
  68 
  69     private static boolean usePlainSocketImpl() {
  70         PrivilegedAction<String> pa = () -> NetProperties.get("jdk.net.usePlainSocketImpl");
  71         String s = AccessController.doPrivileged(pa);
  72         return (s != null) && !s.equalsIgnoreCase("false");
  73     }
  74 
  75     /**
  76      * Creates an instance of platform's SocketImpl
  77      */
  78     @SuppressWarnings("unchecked")
  79     static <S extends SocketImpl & PlatformSocketImpl> S createPlatformSocketImpl(boolean server) {
  80         if (USE_PLAINSOCKETIMPL) {
  81             return (S) new PlainSocketImpl(server);
  82         } else {
  83             return (S) new NioSocketImpl(server);
  84         }
  85     }
  86 
  87     /**
  88      * The file descriptor object for this socket.
  89      */
  90     protected FileDescriptor fd;
  91 
  92     /**
  93      * The IP address of the remote end of this socket.
  94      */
  95     protected InetAddress address;
  96 
  97     /**
  98      * The port number on the remote host to which this socket is connected.
  99      */
 100     protected int port;
 101 
 102     /**
 103      * The local port number to which this socket is connected.
 104      */
 105     protected int localport;
 106 
 107     /**
 108      * Initialize a new instance of this class
 109      */
 110     public SocketImpl() { }
 111 
 112     /**
 113      * Creates either a stream or a datagram socket.
 114      *
 115      * @param      stream   if {@code true}, create a stream socket;
 116      *                      otherwise, create a datagram socket.
 117      * @exception  IOException  if an I/O error occurs while creating the
 118      *               socket.
 119      */
 120     protected abstract void create(boolean stream) throws IOException;
 121 
 122     /**
 123      * Connects this socket to the specified port on the named host.
 124      *
 125      * @param      host   the name of the remote host.
 126      * @param      port   the port number.
 127      * @exception  IOException  if an I/O error occurs when connecting to the
 128      *               remote host.
 129      */
 130     protected abstract void connect(String host, int port) throws IOException;
 131 
 132     /**
 133      * Connects this socket to the specified port number on the specified host.
 134      *
 135      * @param      address   the IP address of the remote host.
 136      * @param      port      the port number.
 137      * @exception  IOException  if an I/O error occurs when attempting a
 138      *               connection.
 139      */
 140     protected abstract void connect(InetAddress address, int port) throws IOException;
 141 
 142     /**
 143      * Connects this socket to the specified port number on the specified host.
 144      * A timeout of zero is interpreted as an infinite timeout. The connection
 145      * will then block until established or an error occurs.
 146      *
 147      * @param      address   the Socket address of the remote host.
 148      * @param     timeout  the timeout value, in milliseconds, or zero for no timeout.
 149      * @exception  IOException  if an I/O error occurs when attempting a
 150      *               connection.
 151      * @since 1.4
 152      */
 153     protected abstract void connect(SocketAddress address, int timeout) throws IOException;
 154 
 155     /**
 156      * Binds this socket to the specified local IP address and port number.
 157      *
 158      * @param      host   an IP address that belongs to a local interface.
 159      * @param      port   the port number.
 160      * @exception  IOException  if an I/O error occurs when binding this socket.
 161      */
 162     protected abstract void bind(InetAddress host, int port) throws IOException;
 163 
 164     /**
 165      * Sets the maximum queue length for incoming connection indications
 166      * (a request to connect) to the {@code count} argument. If a
 167      * connection indication arrives when the queue is full, the
 168      * connection is refused.
 169      *
 170      * @param      backlog   the maximum length of the queue.
 171      * @exception  IOException  if an I/O error occurs when creating the queue.
 172      */
 173     protected abstract void listen(int backlog) throws IOException;
 174 
 175     /**
 176      * Accepts a connection.
 177      *
 178      * @param      s   the accepted connection.
 179      * @exception  IOException  if an I/O error occurs when accepting the
 180      *               connection.
 181      */
 182     protected abstract void accept(SocketImpl s) throws IOException;
 183 
 184     /**
 185      * Returns an input stream for this socket.
 186      *
 187      * @return     a stream for reading from this socket.
 188      * @exception  IOException  if an I/O error occurs when creating the
 189      *               input stream.
 190     */
 191     protected abstract InputStream getInputStream() throws IOException;
 192 
 193     /**
 194      * Returns an output stream for this socket.
 195      *
 196      * @return     an output stream for writing to this socket.
 197      * @exception  IOException  if an I/O error occurs when creating the
 198      *               output stream.
 199      */
 200     protected abstract OutputStream getOutputStream() throws IOException;
 201 
 202     /**
 203      * Returns the number of bytes that can be read from this socket
 204      * without blocking.
 205      *
 206      * @return     the number of bytes that can be read from this socket
 207      *             without blocking.
 208      * @exception  IOException  if an I/O error occurs when determining the
 209      *               number of bytes available.
 210      */
 211     protected abstract int available() throws IOException;
 212 
 213     /**
 214      * Closes this socket.
 215      *
 216      * @exception  IOException  if an I/O error occurs when closing this socket.
 217      */
 218     protected abstract void close() throws IOException;
 219 
 220     /**
 221      * Closes this socket, ignoring any IOException that is thrown by close.
 222      */
 223     void closeQuietly() {
 224         try {
 225             close();
 226         } catch (IOException ignore) { }
 227     }
 228 
 229     /**
 230      * Places the input stream for this socket at "end of stream".
 231      * Any data sent to this socket is acknowledged and then
 232      * silently discarded.
 233      *
 234      * If you read from a socket input stream after invoking this method on the
 235      * socket, the stream's {@code available} method will return 0, and its
 236      * {@code read} methods will return {@code -1} (end of stream).
 237      *
 238      * @exception IOException if an I/O error occurs when shutting down this
 239      * socket.
 240      * @see java.net.Socket#shutdownOutput()
 241      * @see java.net.Socket#close()
 242      * @see java.net.Socket#setSoLinger(boolean, int)
 243      * @since 1.3
 244      */
 245     protected void shutdownInput() throws IOException {
 246       throw new IOException("Method not implemented!");
 247     }
 248 
 249     /**
 250      * Disables the output stream for this socket.
 251      * For a TCP socket, any previously written data will be sent
 252      * followed by TCP's normal connection termination sequence.
 253      *
 254      * If you write to a socket output stream after invoking
 255      * shutdownOutput() on the socket, the stream will throw
 256      * an IOException.
 257      *
 258      * @exception IOException if an I/O error occurs when shutting down this
 259      * socket.
 260      * @see java.net.Socket#shutdownInput()
 261      * @see java.net.Socket#close()
 262      * @see java.net.Socket#setSoLinger(boolean, int)
 263      * @since 1.3
 264      */
 265     protected void shutdownOutput() throws IOException {
 266       throw new IOException("Method not implemented!");
 267     }
 268 
 269     /**
 270      * Returns the value of this socket's {@code fd} field.
 271      *
 272      * @return  the value of this socket's {@code fd} field.
 273      * @see     java.net.SocketImpl#fd
 274      */
 275     protected FileDescriptor getFileDescriptor() {
 276         return fd;
 277     }
 278 
 279     /**
 280      * Returns the value of this socket's {@code address} field.
 281      *
 282      * @return  the value of this socket's {@code address} field.
 283      * @see     java.net.SocketImpl#address
 284      */
 285     protected InetAddress getInetAddress() {
 286         return address;
 287     }
 288 
 289     /**
 290      * Returns the value of this socket's {@code port} field.
 291      *
 292      * @return  the value of this socket's {@code port} field.
 293      * @see     java.net.SocketImpl#port
 294      */
 295     protected int getPort() {
 296         return port;
 297     }
 298 
 299     /**
 300      * Returns whether or not this SocketImpl supports sending
 301      * urgent data. By default, false is returned
 302      * unless the method is overridden in a sub-class
 303      *
 304      * @return  true if urgent data supported
 305      * @see     java.net.SocketImpl#address
 306      * @since 1.4
 307      */
 308     protected boolean supportsUrgentData () {
 309         return false; // must be overridden in sub-class
 310     }
 311 
 312     /**
 313      * Send one byte of urgent data on the socket.
 314      * The byte to be sent is the low eight bits of the parameter
 315      * @param data The byte of data to send
 316      * @exception IOException if there is an error
 317      *  sending the data.
 318      * @since 1.4
 319      */
 320     protected abstract void sendUrgentData (int data) throws IOException;
 321 
 322     /**
 323      * Returns the value of this socket's {@code localport} field.
 324      *
 325      * @return  the value of this socket's {@code localport} field.
 326      * @see     java.net.SocketImpl#localport
 327      */
 328     protected int getLocalPort() {
 329         return localport;
 330     }
 331 
 332     /**
 333      * Returns the address and port of this socket as a {@code String}.
 334      *
 335      * @return  a string representation of this socket.
 336      */
 337     public String toString() {
 338         return "Socket[addr=" + getInetAddress() +
 339             ",port=" + getPort() + ",localport=" + getLocalPort()  + "]";
 340     }
 341 
 342     void reset() {
 343         fd = null;
 344         address = null;
 345         port = 0;
 346         localport = 0;
 347     }
 348 
 349     /**
 350      * Sets performance preferences for this socket.
 351      *
 352      * <p> Sockets use the TCP/IP protocol by default.  Some implementations
 353      * may offer alternative protocols which have different performance
 354      * characteristics than TCP/IP.  This method allows the application to
 355      * express its own preferences as to how these tradeoffs should be made
 356      * when the implementation chooses from the available protocols.
 357      *
 358      * <p> Performance preferences are described by three integers
 359      * whose values indicate the relative importance of short connection time,
 360      * low latency, and high bandwidth.  The absolute values of the integers
 361      * are irrelevant; in order to choose a protocol the values are simply
 362      * compared, with larger values indicating stronger preferences. Negative
 363      * values represent a lower priority than positive values. If the
 364      * application prefers short connection time over both low latency and high
 365      * bandwidth, for example, then it could invoke this method with the values
 366      * {@code (1, 0, 0)}.  If the application prefers high bandwidth above low
 367      * latency, and low latency above short connection time, then it could
 368      * invoke this method with the values {@code (0, 1, 2)}.
 369      *
 370      * By default, this method does nothing, unless it is overridden in
 371      * a sub-class.
 372      *
 373      * @param  connectionTime
 374      *         An {@code int} expressing the relative importance of a short
 375      *         connection time
 376      *
 377      * @param  latency
 378      *         An {@code int} expressing the relative importance of low
 379      *         latency
 380      *
 381      * @param  bandwidth
 382      *         An {@code int} expressing the relative importance of high
 383      *         bandwidth
 384      *
 385      * @since 1.5
 386      */
 387     protected void setPerformancePreferences(int connectionTime,
 388                                           int latency,
 389                                           int bandwidth)
 390     {
 391         /* Not implemented yet */
 392     }
 393 
 394     /**
 395      * Called to set a socket option.
 396      *
 397      * @implSpec
 398      * The default implementation of this method first checks that the given
 399      * socket option {code name} is not null, then throws {@code
 400      * UnsupportedOperationException}. Subclasses should override this method
 401      * with an appropriate implementation.
 402      *
 403      * @param <T> The type of the socket option value
 404      * @param name The socket option
 405      * @param value The value of the socket option. A value of {@code null}
 406      *              may be valid for some options.
 407      *
 408      * @throws UnsupportedOperationException if the SocketImpl does not
 409      *         support the option
 410      * @throws IllegalArgumentException if the value is not valid for
 411      *         the option
 412      * @throws IOException if an I/O error occurs, or if the socket is closed
 413      * @throws NullPointerException if name is {@code null}
 414      *
 415      * @since 9
 416      */
 417     protected <T> void setOption(SocketOption<T> name, T value) throws IOException {
 418         Objects.requireNonNull(name);
 419         throw new UnsupportedOperationException("'" + name + "' not supported");
 420     }
 421 
 422     /**
 423      * Called to get a socket option.
 424      *
 425      * @implSpec
 426      * The default implementation of this method first checks that the given
 427      * socket option {code name} is not null, then throws {@code
 428      * UnsupportedOperationException}. Subclasses should override this method
 429      * with an appropriate implementation.
 430      *
 431      * @param <T> The type of the socket option value
 432      * @param name The socket option
 433      * @return the value of the named option
 434      *
 435      * @throws UnsupportedOperationException if the SocketImpl does not
 436      *         support the option
 437      * @throws IOException if an I/O error occurs, or if the socket is closed
 438      * @throws NullPointerException if name is {@code null}
 439      *
 440      * @since 9
 441      */
 442     protected <T> T getOption(SocketOption<T> name) throws IOException {
 443         Objects.requireNonNull(name);
 444         throw new UnsupportedOperationException("'" + name + "' not supported");
 445     }
 446 
 447     /**
 448      * Attempts to copy socket options from this SocketImpl to a target SocketImpl.
 449      * At this time, only the SO_TIMEOUT make sense to copy.
 450      */
 451     void copyOptionsTo(SocketImpl target) {
 452         try {
 453             Object timeout = getOption(SocketOptions.SO_TIMEOUT);
 454             if (timeout instanceof Integer) {
 455                 target.setOption(SocketOptions.SO_TIMEOUT, timeout);
 456             }
 457         } catch (IOException ignore) { }
 458     }
 459 
 460     /**
 461      * Returns a set of SocketOptions supported by this impl
 462      * and by this impl's socket (Socket or ServerSocket)
 463      *
 464      * @implSpec
 465      * The default implementation of this method returns an empty set.
 466      * Subclasses should override this method with an appropriate implementation.
 467      *
 468      * @return a Set of SocketOptions
 469      *
 470      * @since 9
 471      */
 472     protected Set<SocketOption<?>> supportedOptions() {
 473         return Set.of();
 474     }
 475 }