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( );
}
