This class implements a socket for
stream-based communication over the network. See
URL for a higher-level interface to networking and
DatagramSocket for a lower-level interface.
Before you can use a socket for communication, it must be
bound to a local address and
connected to a remote address. Binding and
connection are done automatically for you when you call any of the
Socket( ) constructors except the no-argument
constructor. These constructors allow you to specify either the name
or the InetAddress of the computer to connect to,
and also require you to specify the port number to connect to. Two of
these constructors also allow you to specify the local
InetAddress and port number to bind the socket to.
Most applications do not need to specify a local address, and can
simply use one of the two-argument versions of Socket(
) and can allow the constructor to choose an ephemeral
local port to bind the socket to.
The no-argument Socket( ) constructor is different
from the others: it creates an unbound and unconnected socket. In
Java 1.4 and later, you can explicitly call bind(
) and
connect( ) to bind and connect the socket. It can
be useful to do this when you want to set a socket option (described
below) that must be set before binding or connection. bind(
) uses a SocketAddress object to
describe the local address to bind to, and connect(
) uses a SocketAddress to specify the
remote address to connect to. There is also a version of
connect( ) that takes a timeout value in
milliseconds: if the connection attempt takes longer than the
specified amount of time, connect( ) throws an
IOException. (See ServerSocket
for a description of how to write server code that accepts socket
connection requests from client code.) Java 5.0 includes a
constructor that takes a Proxy object as its sole
argument. Like the no-argument constructor, this creates an unbound
and unconnected socket. When you attempt to connect it, the
connection will be made through the specified
Proxy.
Use isBound( )
and
isConnected( ) to determine whether a
Socket is bound and connected. Use
getInetAddress(
)
and getPort( ) to
determine the IP address and port number that the socket is connected
to. Or, in Java 1.4 and later, use geTRemoteSocketAddress(
) to obtain the remote address as a
SocketAddress object. Similarly, use
getLocalAddress(
)
and
getLocalPort( ) or use
getLocalSocketAddress( ) to find out what address
a socket is bound to.
Once you have a
Socket object that is bound and connected, use
getInputStream( ) and getOutputStream(
) to obtain InputStream and
OutputStream objects you can use to communicate
with the remote host. You can use these streams just as you would use
similar streams for file input and output. When you are done with a
Socket, use close( ) to close
it. Once a socket has been closed, it is not possible to call
connect( ) again to reuse it, and you should not
call any of its methods except isClosed( ).
Because networking code can throw many exceptions, it is common
practice to close( ) a socket in the
finally clause of a try/catch
statement to ensure that the socket always gets closed. Note,
however, that the close( ) method itself can throw
an IOException, and you may need to put it in its
own try block. In Java 1.3 and later
shutdownInput( ) and shutdownOutput(
) allow you to close the input and output communication
channels individually without closing the entire socket. In Java 1.4
and later, isInputShutdown(
) and isOutputShutdown(
) allow you to test for this.
The
Socket class defines a number of methods that
allow you to set (and query) "socket
options" that affect the low-level networking
behavior of the socket. setSendBufferSize( ) and
setReceiveBufferSize( ) provide hints to the
underlying networking system about what
buffer size is best to use with this
socket. setSoTimeout(
) specifies
the number of milliseconds a read( ) call on the
input stream returned by getInputStream( ) waits
for data before throwing an
InterruptedIOException. The default value of
0 specifies that the stream blocks indefinitely.
setSoLinger( ) specifies what to do when a socket is
closed while there is still data waiting to be transmitted. If
lingering is turned on, the close( ) call blocks
for up to the specified number of seconds while attempting to
transmit the remaining data. Calling setTcpNoDelay(
) with an argument of
TRue causes data to be sent through the socket as
soon as it is available, instead of waiting for the TCP packet to
become more full before sending it. In Java 1.3, use
setKeepAlive( ) to enable or disable the periodic
exchange of control messages across an idle socket connection. The
keepalive protocol enables a client to
determine if its server has crashed without closing the socket and
vice versa. In Java 1.4, pass true to
setOOBInline( ) if you want to receive
"out of band" data sent to this
socket "inline" on the input stream
of the socket (by default such data is simply discarded). This can be
used to receive bytes sent with sendUrgentData(
). Java 1.4 also adds
setReuseAddress(
) which you
can use before binding the socket to specify that the socket should
be allowed to bind to a port that is still nominally in use by
another socket that is in the process of shutting
down. setTrafficClass( )
is also new in Java 1.4; it sets the "traffic
class" field for the socket, and requires an
understanding of the low-level details of the IP protocol.
The getChannel( )
method is a link between this Socket class and the
New I/O java.nio.channels.SocketChannel class. It
returns the SocketChannel associated with this
Socket if there is one. Note, however, that this
method always returns null for sockets created
with any of the Socket( ) constructors. If you
create a SocketChannel object, and obtain a
Socket from it, then the getChannel(
) method provides a way to link back to the parent channel.
public class
Socket {
// Public Constructors
1.1 public
Socket ( );
5.0 public
Socket (java.net.Proxy
proxy );
public
Socket (String
host , int
port )
throws UnknownHostException, java.io.IOException;
public
Socket (InetAddress
address , int
port ) throws java.io.IOException;
# public
Socket (String
host , int
port , boolean
stream )
throws java.io.IOException;
# public
Socket (InetAddress
host , int
port , boolean
stream )
throws java.io.IOException;
1.1 public
Socket (String
host , int
port , InetAddress
localAddr , int
localPort )
throws java.io.IOException;
1.1 public
Socket (InetAddress
address , int
port , InetAddress
localAddr ,
int
localPort ) throws java.io.IOException;
// Protected Constructors
1.1 protected
Socket (SocketImpl
impl ) throws SocketException;
// Public Class Methods
public static void
setSocketImplFactory (SocketImplFactory
fac )
throws java.io.IOException; synchronized
// Public Instance Methods
1.4 public void
bind (SocketAddress
bindpoint ) throws java.io.IOException;
public void
close ( ) throws java.io.IOException; synchronized
1.4 public void
connect (SocketAddress
endpoint ) throws java.io.IOException;
1.4 public void
connect (SocketAddress
endpoint , int
timeout )
throws java.io.IOException;
1.4 public java.nio.channels.SocketChannel
getChannel ( ); constant default:null
public InetAddress
getInetAddress ( ); default:null
public java.io.InputStream
getInputStream ( ) throws java.io.IOException;
1.3 public boolean
getKeepAlive ( ) throws SocketException; default:false
1.1 public InetAddress
getLocalAddress ( ); default:Inet4Address
public int
getLocalPort ( ); default:-1
1.4 public SocketAddress
getLocalSocketAddress ( ); default:null
1.4 public boolean
getOOBInline ( ) throws SocketException; default:false
public java.io.OutputStream
getOutputStream ( ) throws java.io.IOException;
public int
getPort ( ); default:0
1.2 public int
getReceiveBufferSize ( )
throws SocketException; synchronized default:43690
1.4 public SocketAddress
getRemoteSocketAddress ( ); default:null
1.4 public boolean
getReuseAddress ( ) throws SocketException; default:false
1.2 public int
getSendBufferSize ( ) throws SocketException;
synchronized default:8192
1.1 public int
getSoLinger ( ) throws SocketException; default:-1
1.1 public int
getSoTimeout ( ) throws SocketException; synchronized default:0
1.1 public boolean
getTcpNoDelay ( ) throws SocketException; default:false
1.4 public int
getTrafficClass ( ) throws SocketException; default:0
1.4 public boolean
isBound ( ); default:false
1.4 public boolean
isClosed ( ); default:false
1.4 public boolean
isConnected ( ); default:false
1.4 public boolean
isInputShutdown ( ); default:false
1.4 public boolean
isOutputShutdown ( ); default:false
1.4 public void
sendUrgentData (int
data ) throws java.io.IOException;
1.3 public void
setKeepAlive (boolean
on ) throws SocketException;
1.4 public void
setOOBInline (boolean
on ) throws SocketException;
5.0 public void
setPerformancePreferences (int
connectionTime , int
latency ,
int
bandwidth ); empty
1.2 public void
setReceiveBufferSize (int
size )
throws SocketException; synchronized
1.4 public void
setReuseAddress (boolean
on ) throws SocketException;
1.2 public void
setSendBufferSize (int
size )
throws SocketException; synchronized
1.1 public void
setSoLinger (boolean
on , int
linger ) throws SocketException;
1.1 public void
setSoTimeout (int
timeout )
throws SocketException; synchronized
1.1 public void
setTcpNoDelay (boolean
on ) throws SocketException;
1.4 public void
setTrafficClass (int
tc ) throws SocketException;
1.3 public void
shutdownInput ( ) throws java.io.IOException;
1.3 public void
shutdownOutput ( ) throws java.io.IOException;
// Public Methods Overriding Object
public String
toString ( );
}
ServerSocket.implAccept( ),
javax.net.ssl.SSLSocketFactory.createSocket( ),
javax.net.ssl.X509KeyManager.{chooseClientAlias(
), chooseServerAlias( )}
ServerSocket.accept( ),
java.nio.channels.SocketChannel.socket( ),
javax.net.SocketFactory.createSocket( ),
javax.net.ssl.SSLSocketFactory.createSocket( )