public class

Socket

extends Object
java.lang.Object
   ↳ java.net.Socket
Known Direct Subclasses

Class Overview

Provides a client-side TCP socket.

Summary

Public Constructors
Socket()
Creates a new unconnected socket.
Socket(Proxy proxy)
Creates a new unconnected socket using the given proxy type.
Socket(String dstName, int dstPort)
Creates a new streaming socket connected to the target host specified by the parameters dstName and dstPort.
Socket(String dstName, int dstPort, InetAddress localAddress, int localPort)
Creates a new streaming socket connected to the target host specified by the parameters dstName and dstPort.
Socket(String hostName, int port, boolean streaming)
This constructor is deprecated. Use Socket(String, int) instead of this for streaming sockets or an appropriate constructor of DatagramSocket for UDP transport.
Socket(InetAddress dstAddress, int dstPort)
Creates a new streaming socket connected to the target host specified by the parameters dstAddress and dstPort.
Socket(InetAddress dstAddress, int dstPort, InetAddress localAddress, int localPort)
Creates a new streaming socket connected to the target host specified by the parameters dstAddress and dstPort.
Socket(InetAddress addr, int port, boolean streaming)
This constructor is deprecated. Use Socket(InetAddress, int) instead of this for streaming sockets or an appropriate constructor of DatagramSocket for UDP transport.
Protected Constructors
Socket(SocketImpl impl)
Creates an unconnected socket with the given socket implementation.
Public Methods
void bind(SocketAddress localAddr)
Binds this socket to the given local host address and port specified by the SocketAddress localAddr.
synchronized void close()
Closes the socket.
void connect(SocketAddress remoteAddr, int timeout)
Connects this socket to the given remote host address and port specified by the SocketAddress remoteAddr with the specified timeout.
void connect(SocketAddress remoteAddr)
Connects this socket to the given remote host address and port specified by the SocketAddress remoteAddr.
SocketChannel getChannel()
Returns this socket's SocketChannel, if one exists.
InetAddress getInetAddress()
Returns the IP address of the target host this socket is connected to, or null if this socket is not yet connected.
InputStream getInputStream()
Returns an input stream to read data from this socket.
boolean getKeepAlive()
Returns this socket's SO_KEEPALIVE setting.
InetAddress getLocalAddress()
Returns the local IP address this socket is bound to, or InetAddress.ANY if the socket is unbound.
int getLocalPort()
Returns the local port this socket is bound to, or -1 if the socket is unbound.
SocketAddress getLocalSocketAddress()
Returns the local address and port of this socket as a SocketAddress or null if the socket is unbound.
boolean getOOBInline()
Returns this socket's SO_OOBINLINE setting.
OutputStream getOutputStream()
Returns an output stream to write data into this socket.
int getPort()
Returns the port number of the target host this socket is connected to, or 0 if this socket is not yet connected.
synchronized int getReceiveBufferSize()
Returns this socket's receive buffer size.
SocketAddress getRemoteSocketAddress()
Returns the remote address and port of this socket as a SocketAddress or null if the socket is not connected.
boolean getReuseAddress()
Returns this socket's SO_REUSEADDR setting.
synchronized int getSendBufferSize()
Returns this socket's send buffer size.
int getSoLinger()
Returns this socket's linger timeout in seconds, or -1 for no linger (i.e.
synchronized int getSoTimeout()
Returns this socket's receive timeout.
boolean getTcpNoDelay()
Returns this socket's SocketOptions#TCP_NODELAY setting.
int getTrafficClass()
Returns this socket's setting.
boolean isBound()
Returns whether this socket is bound to a local address and port.
boolean isClosed()
Returns whether this socket is closed.
boolean isConnected()
Returns whether this socket is connected to a remote host.
boolean isInputShutdown()
Returns whether the incoming channel of the socket has already been closed.
boolean isOutputShutdown()
Returns whether the outgoing channel of the socket has already been closed.
void sendUrgentData(int value)
Sends the given single byte data which is represented by the lowest octet of value as "TCP urgent data".
void setKeepAlive(boolean keepAlive)
Sets this socket's SO_KEEPALIVE option.
void setOOBInline(boolean oobinline)
Sets this socket's SO_OOBINLINE option.
void setPerformancePreferences(int connectionTime, int latency, int bandwidth)
Sets performance preferences for connectionTime, latency and bandwidth.
synchronized void setReceiveBufferSize(int size)
Sets this socket's receive buffer size.
void setReuseAddress(boolean reuse)
Sets this socket's SO_REUSEADDR option.
synchronized void setSendBufferSize(int size)
Sets this socket's send buffer size.
void setSoLinger(boolean on, int timeout)
Sets this socket's linger timeout in seconds.
synchronized void setSoTimeout(int timeout)
Sets this socket's read timeout in milliseconds.
synchronized static void setSocketImplFactory(SocketImplFactory fac)
Sets the internal factory for creating socket implementations.
void setTcpNoDelay(boolean on)
Sets this socket's TCP_NODELAY option.
void setTrafficClass(int value)
Sets this socket's IP_TOS value for every packet sent by this socket.
void shutdownInput()
Closes the input stream of this socket.
void shutdownOutput()
Closes the output stream of this socket.
String toString()
Returns a String containing a concise, human-readable description of the socket.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public Socket ()

Since: API Level 1

Creates a new unconnected socket. When a SocketImplFactory is defined it creates the internal socket implementation, otherwise the default socket implementation will be used for this socket.

See Also

public Socket (Proxy proxy)

Since: API Level 1

Creates a new unconnected socket using the given proxy type. When a SocketImplFactory is defined it creates the internal socket implementation, otherwise the default socket implementation will be used for this socket.

Example that will create a socket connection through a SOCKS proxy server:
Socket sock = new Socket(new Proxy(Proxy.Type.SOCKS, new InetSocketAddress("test.domain.org", 2130)));

Parameters
proxy the specified proxy for this socket.
Throws
IllegalArgumentException if the argument proxy is null or of an invalid type.
SecurityException if a security manager exists and it denies the permission to connect to the given proxy.
See Also

public Socket (String dstName, int dstPort)

Since: API Level 1

Creates a new streaming socket connected to the target host specified by the parameters dstName and dstPort. The socket is bound to any available port on the local host.

Implementation note: this implementation tries each IP address for the given hostname until it either connects successfully or it exhausts the set. It will try both IPv4 and IPv6 addresses in the order specified by the system property "java.net.preferIPv6Addresses".

Parameters
dstName the target host name or IP address to connect to.
dstPort the port on the target host to connect to.
Throws
UnknownHostException if the host name could not be resolved into an IP address.
IOException if an error occurs while creating the socket.
SecurityException if a security manager exists and it denies the permission to connect to the given address and port.

public Socket (String dstName, int dstPort, InetAddress localAddress, int localPort)

Since: API Level 1

Creates a new streaming socket connected to the target host specified by the parameters dstName and dstPort. On the local endpoint the socket is bound to the given address localAddress on port localPort. If host is null a loopback address is used to connect to.

Implementation note: this implementation tries each IP address for the given hostname until it either connects successfully or it exhausts the set. It will try both IPv4 and IPv6 addresses in the order specified by the system property "java.net.preferIPv6Addresses".

Parameters
dstName the target host name or IP address to connect to.
dstPort the port on the target host to connect to.
localAddress the address on the local host to bind to.
localPort the port on the local host to bind to.
Throws
UnknownHostException if the host name could not be resolved into an IP address.
IOException if an error occurs while creating the socket.
SecurityException if a security manager exists and it denies the permission to connect to the given address and port.

public Socket (String hostName, int port, boolean streaming)

Since: API Level 1

This constructor is deprecated.
Use Socket(String, int) instead of this for streaming sockets or an appropriate constructor of DatagramSocket for UDP transport.

Creates a new streaming or datagram socket connected to the target host specified by the parameters hostName and port. The socket is bound to any available port on the local host.

Implementation note: this implementation tries each IP address for the given hostname until it either connects successfully or it exhausts the set. It will try both IPv4 and IPv6 addresses in the order specified by the system property "java.net.preferIPv6Addresses".

Parameters
hostName the target host name or IP address to connect to.
port the port on the target host to connect to.
streaming if true a streaming socket is returned, a datagram socket otherwise.
Throws
UnknownHostException if the host name could not be resolved into an IP address.
IOException if an error occurs while creating the socket.
SecurityException if a security manager exists and it denies the permission to connect to the given address and port.

public Socket (InetAddress dstAddress, int dstPort)

Since: API Level 1

Creates a new streaming socket connected to the target host specified by the parameters dstAddress and dstPort. The socket is bound to any available port on the local host.

Parameters
dstAddress the target host address to connect to.
dstPort the port on the target host to connect to.
Throws
IOException if an error occurs while creating the socket.
SecurityException if a security manager exists and it denies the permission to connect to the given address and port.

public Socket (InetAddress dstAddress, int dstPort, InetAddress localAddress, int localPort)

Since: API Level 1

Creates a new streaming socket connected to the target host specified by the parameters dstAddress and dstPort. On the local endpoint the socket is bound to the given address localAddress on port localPort.

Parameters
dstAddress the target host address to connect to.
dstPort the port on the target host to connect to.
localAddress the address on the local host to bind to.
localPort the port on the local host to bind to.
Throws
IOException if an error occurs while creating the socket.
SecurityException if a security manager exists and it denies the permission to connect to the given address and port.

public Socket (InetAddress addr, int port, boolean streaming)

Since: API Level 1

This constructor is deprecated.
Use Socket(InetAddress, int) instead of this for streaming sockets or an appropriate constructor of DatagramSocket for UDP transport.

Creates a new streaming or datagram socket connected to the target host specified by the parameters addr and port. The socket is bound to any available port on the local host.

Parameters
addr the Internet address to connect to.
port the port on the target host to connect to.
streaming if true a streaming socket is returned, a datagram socket otherwise.
Throws
IOException if an error occurs while creating the socket.
SecurityException if a security manager exists and it denies the permission to connect to the given address and port.

Protected Constructors

protected Socket (SocketImpl impl)

Since: API Level 1

Creates an unconnected socket with the given socket implementation.

Parameters
impl the socket implementation to be used.
Throws
SocketException if an error occurs while creating the socket.

Public Methods

public void bind (SocketAddress localAddr)

Since: API Level 1

Binds this socket to the given local host address and port specified by the SocketAddress localAddr. If localAddr is set to null, this socket will be bound to an available local address on any free port.

Parameters
localAddr the specific address and port on the local machine to bind to.
Throws
IllegalArgumentException if the given SocketAddress is invalid or not supported.
IOException if the socket is already bound or an error occurs while binding.

public synchronized void close ()

Since: API Level 1

Closes the socket. It is not possible to reconnect or rebind to this socket thereafter which means a new socket instance has to be created.

Throws
IOException if an error occurs while closing the socket.

public void connect (SocketAddress remoteAddr, int timeout)

Since: API Level 1

Connects this socket to the given remote host address and port specified by the SocketAddress remoteAddr with the specified timeout. The connecting method will block until the connection is established or an error occurred.

Parameters
remoteAddr the address and port of the remote host to connect to.
timeout the timeout value in milliseconds or 0 for an infinite timeout.
Throws
IllegalArgumentException if the given SocketAddress is invalid or not supported or the timeout value is negative.
IOException if the socket is already connected or an error occurs while connecting.

public void connect (SocketAddress remoteAddr)

Since: API Level 1

Connects this socket to the given remote host address and port specified by the SocketAddress remoteAddr.

Parameters
remoteAddr the address and port of the remote host to connect to.
Throws
IllegalArgumentException if the given SocketAddress is invalid or not supported.
IOException if the socket is already connected or an error occurs while connecting.

public SocketChannel getChannel ()

Since: API Level 1

Returns this socket's SocketChannel, if one exists. A channel is available only if this socket wraps a channel. (That is, you can go from a channel to a socket and back again, but you can't go from an arbitrary socket to a channel.) In practice, this means that the socket must have been created by accept() or open().

public InetAddress getInetAddress ()

Since: API Level 1

Returns the IP address of the target host this socket is connected to, or null if this socket is not yet connected.

public InputStream getInputStream ()

Since: API Level 1

Returns an input stream to read data from this socket.

Returns
  • the byte-oriented input stream.
Throws
IOException if an error occurs while creating the input stream or the socket is in an invalid state.

public boolean getKeepAlive ()

Since: API Level 1

Returns this socket's SO_KEEPALIVE setting.

Throws
SocketException

public InetAddress getLocalAddress ()

Since: API Level 1

Returns the local IP address this socket is bound to, or InetAddress.ANY if the socket is unbound.

public int getLocalPort ()

Since: API Level 1

Returns the local port this socket is bound to, or -1 if the socket is unbound.

public SocketAddress getLocalSocketAddress ()

Since: API Level 1

Returns the local address and port of this socket as a SocketAddress or null if the socket is unbound. This is useful on multihomed hosts.

public boolean getOOBInline ()

Since: API Level 1

Returns this socket's SO_OOBINLINE setting.

Throws
SocketException

public OutputStream getOutputStream ()

Since: API Level 1

Returns an output stream to write data into this socket.

Returns
  • the byte-oriented output stream.
Throws
IOException if an error occurs while creating the output stream or the socket is in an invalid state.

public int getPort ()

Since: API Level 1

Returns the port number of the target host this socket is connected to, or 0 if this socket is not yet connected.

public synchronized int getReceiveBufferSize ()

Since: API Level 1

Returns this socket's receive buffer size.

Throws
SocketException

public SocketAddress getRemoteSocketAddress ()

Since: API Level 1

Returns the remote address and port of this socket as a SocketAddress or null if the socket is not connected.

Returns
  • the remote socket address and port.

public boolean getReuseAddress ()

Since: API Level 1

Returns this socket's SO_REUSEADDR setting.

Throws
SocketException

public synchronized int getSendBufferSize ()

Since: API Level 1

Returns this socket's send buffer size.

Throws
SocketException

public int getSoLinger ()

Since: API Level 1

Returns this socket's linger timeout in seconds, or -1 for no linger (i.e. close will return immediately).

Throws
SocketException

public synchronized int getSoTimeout ()

Since: API Level 1

Returns this socket's receive timeout.

Throws
SocketException

public boolean getTcpNoDelay ()

Since: API Level 1

Returns this socket's SocketOptions#TCP_NODELAY setting.

Throws
SocketException

public int getTrafficClass ()

Since: API Level 1

Returns this socket's setting.

Throws
SocketException
See Also

public boolean isBound ()

Since: API Level 1

Returns whether this socket is bound to a local address and port.

Returns
  • true if the socket is bound to a local address, false otherwise.

public boolean isClosed ()

Since: API Level 1

Returns whether this socket is closed.

Returns
  • true if the socket is closed, false otherwise.

public boolean isConnected ()

Since: API Level 1

Returns whether this socket is connected to a remote host.

Returns
  • true if the socket is connected, false otherwise.

public boolean isInputShutdown ()

Since: API Level 1

Returns whether the incoming channel of the socket has already been closed.

Returns
  • true if reading from this socket is not possible anymore, false otherwise.

public boolean isOutputShutdown ()

Since: API Level 1

Returns whether the outgoing channel of the socket has already been closed.

Returns
  • true if writing to this socket is not possible anymore, false otherwise.

public void sendUrgentData (int value)

Since: API Level 1

Sends the given single byte data which is represented by the lowest octet of value as "TCP urgent data".

Parameters
value the byte of urgent data to be sent.
Throws
IOException if an error occurs while sending urgent data.

public void setKeepAlive (boolean keepAlive)

Since: API Level 1

Sets this socket's SO_KEEPALIVE option.

Throws
SocketException

public void setOOBInline (boolean oobinline)

Since: API Level 1

Sets this socket's SO_OOBINLINE option.

Throws
SocketException

public void setPerformancePreferences (int connectionTime, int latency, int bandwidth)

Since: API Level 1

Sets performance preferences for connectionTime, latency and bandwidth.

This method does currently nothing.

Parameters
connectionTime the value representing the importance of a short connecting time.
latency the value representing the importance of low latency.
bandwidth the value representing the importance of high bandwidth.

public synchronized void setReceiveBufferSize (int size)

Since: API Level 1

Sets this socket's receive buffer size.

Throws
SocketException

public void setReuseAddress (boolean reuse)

Since: API Level 1

Sets this socket's SO_REUSEADDR option.

Throws
SocketException

public synchronized void setSendBufferSize (int size)

Since: API Level 1

Sets this socket's send buffer size.

Throws
SocketException

public void setSoLinger (boolean on, int timeout)

Since: API Level 1

Sets this socket's linger timeout in seconds. If on is false, timeout is irrelevant.

Throws
SocketException

public synchronized void setSoTimeout (int timeout)

Since: API Level 1

Sets this socket's read timeout in milliseconds. Use 0 for no timeout. To take effect, this option must be set before the blocking method was called.

Throws
SocketException

public static synchronized void setSocketImplFactory (SocketImplFactory fac)

Since: API Level 1

Sets the internal factory for creating socket implementations. This may only be executed once during the lifetime of the application.

Parameters
fac the socket implementation factory to be set.
Throws
IOException if the factory has been already set.

public void setTcpNoDelay (boolean on)

Since: API Level 1

Sets this socket's TCP_NODELAY option.

Throws
SocketException

public void setTrafficClass (int value)

Since: API Level 1

Sets this socket's IP_TOS value for every packet sent by this socket.

Throws
SocketException

public void shutdownInput ()

Since: API Level 1

Closes the input stream of this socket. Any further data sent to this socket will be discarded. Reading from this socket after this method has been called will return the value EOF.

Throws
IOException if an error occurs while closing the socket input stream.
SocketException if the input stream is already closed.

public void shutdownOutput ()

Since: API Level 1

Closes the output stream of this socket. All buffered data will be sent followed by the termination sequence. Writing to the closed output stream will cause an IOException.

Throws
IOException if an error occurs while closing the socket output stream.
SocketException if the output stream is already closed.

public String toString ()

Since: API Level 1

Returns a String containing a concise, human-readable description of the socket.

Returns
  • the textual representation of this socket.