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