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 anImpl)
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()
Gets the SocketChannel of this socket, if one is available.
InetAddress getInetAddress()
Gets the IP address of the target host this socket is connected to.
InputStream getInputStream()
Gets an input stream to read data from this socket.
boolean getKeepAlive()
Gets the setting of the socket option SocketOptions.SO_KEEPALIVE.
InetAddress getLocalAddress()
Gets the local IP address this socket is bound to.
int getLocalPort()
Gets the local port this socket is bound to.
SocketAddress getLocalSocketAddress()
Gets the local address and port of this socket as a SocketAddress or null if the socket is unbound.
boolean getOOBInline()
Gets the setting of the socket option SocketOptions.SO_OOBINLINE.
OutputStream getOutputStream()
Gets an output stream to write data into this socket.
int getPort()
Gets the port number of the target host this socket is connected to.
synchronized int getReceiveBufferSize()
Gets the receive buffer size of this socket.
SocketAddress getRemoteSocketAddress()
Gets the remote address and port of this socket as a SocketAddress or null if the socket is not connected.
boolean getReuseAddress()
Gets the setting of the socket option SocketOptions.SO_REUSEADDR.
synchronized int getSendBufferSize()
Gets the send buffer size of this socket.
int getSoLinger()
Gets the value of the socket option SocketOptions.SO_LINGER.
synchronized int getSoTimeout()
Gets the timeout for this socket during which a reading operation shall block while waiting for data.
boolean getTcpNoDelay()
Gets the setting of the socket option SocketOptions.TCP_NODELAY.
int getTrafficClass()
Gets the value of the socket option SocketOptions.IP_TOS.
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 value)
Sets the state of the SocketOptions.SO_KEEPALIVE for this socket.
void setOOBInline(boolean oobinline)
Sets the state of the SocketOptions.SO_OOBINLINE for this socket.
void setPerformancePreferences(int connectionTime, int latency, int bandwidth)
Sets performance preferences for connectionTime, latency and bandwidth.
synchronized void setReceiveBufferSize(int size)
Sets the receive buffer size of this socket.
void setReuseAddress(boolean reuse)
Sets the state of the SocketOptions.SO_REUSEADDR for this socket.
synchronized void setSendBufferSize(int size)
Sets the send buffer size of this socket.
void setSoLinger(boolean on, int timeout)
Sets the state of the SocketOptions.SO_LINGER with the given timeout in seconds.
synchronized void setSoTimeout(int timeout)
Sets the reading timeout in milliseconds for this socket.
synchronized static void setSocketImplFactory(SocketImplFactory fac)
Sets the internal factory for creating socket implementations.
void setTcpNoDelay(boolean on)
Sets the state of the SocketOptions.TCP_NODELAY for this socket.
void setTrafficClass(int value)
Sets the value of the SocketOptions.IP_TOS for 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 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 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 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 anImpl)

Since: API Level 1

Creates an unconnected socket with the given socket implementation.

Parameters
anImpl 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

Gets the SocketChannel of this socket, if one is available. The current implementation of this method returns always null.

Returns
  • the related SocketChannel or null if no channel exists.

public InetAddress getInetAddress ()

Since: API Level 1

Gets the IP address of the target host this socket is connected to.

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

public InputStream getInputStream ()

Since: API Level 1

Gets 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

Gets the setting of the socket option SocketOptions.SO_KEEPALIVE.

Returns
  • true if the SocketOptions.SO_KEEPALIVE is enabled, false otherwise.
Throws
SocketException if an error occurs while reading the socket option.
See Also

public InetAddress getLocalAddress ()

Since: API Level 1

Gets the local IP address this socket is bound to.

Returns
  • the local IP address of this socket or InetAddress.ANY if the socket is unbound.

public int getLocalPort ()

Since: API Level 1

Gets the local port this socket is bound to.

Returns
  • the local port of this socket or -1 if the socket is unbound.

public SocketAddress getLocalSocketAddress ()

Since: API Level 1

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

Returns
  • the bound local socket address and port.

public boolean getOOBInline ()

Since: API Level 1

Gets the setting of the socket option SocketOptions.SO_OOBINLINE.

Returns
  • true if the SocketOptions.SO_OOBINLINE is enabled, false otherwise.
Throws
SocketException if an error occurs while reading the socket option.
See Also

public OutputStream getOutputStream ()

Since: API Level 1

Gets 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

Gets the port number of the target host this socket is connected to.

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

public synchronized int getReceiveBufferSize ()

Since: API Level 1

Gets the receive buffer size of this socket.

Returns
  • the current value of the option SocketOptions.SO_RCVBUF.
Throws
SocketException if an error occurs while reading the socket option.
See Also

public SocketAddress getRemoteSocketAddress ()

Since: API Level 1

Gets 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

Gets the setting of the socket option SocketOptions.SO_REUSEADDR.

Returns
  • true if the SocketOptions.SO_REUSEADDR is enabled, false otherwise.
Throws
SocketException if an error occurs while reading the socket option.
See Also

public synchronized int getSendBufferSize ()

Since: API Level 1

Gets the send buffer size of this socket.

Returns
  • the current value of the option SocketOptions.SO_SNDBUF.
Throws
SocketException if an error occurs while reading the socket option.
See Also

public int getSoLinger ()

Since: API Level 1

Gets the value of the socket option SocketOptions.SO_LINGER.

Returns
  • the current value of the option SocketOptions.SO_LINGER or -1 if this option is disabled.
Throws
SocketException if an error occurs while reading the socket option.
See Also

public synchronized int getSoTimeout ()

Since: API Level 1

Gets the timeout for this socket during which a reading operation shall block while waiting for data.

Returns
  • the current value of the option SocketOptions.SO_TIMEOUT or 0 which represents an infinite timeout.
Throws
SocketException if an error occurs while reading the socket option.
See Also

public boolean getTcpNoDelay ()

Since: API Level 1

Gets the setting of the socket option SocketOptions.TCP_NODELAY.

Returns
  • true if the SocketOptions.TCP_NODELAY is enabled, false otherwise.
Throws
SocketException if an error occurs while reading the socket option.
See Also

public int getTrafficClass ()

Since: API Level 1

Gets the value of the socket option SocketOptions.IP_TOS.

Returns
  • the value which represents the type of service.
Throws
SocketException if an error occurs while reading the socket option.
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 value)

Since: API Level 1

Sets the state of the SocketOptions.SO_KEEPALIVE for this socket.

Parameters
value the state whether this option is enabled or not.
Throws
SocketException if an error occurs while setting the option.
See Also

public void setOOBInline (boolean oobinline)

Since: API Level 1

Sets the state of the SocketOptions.SO_OOBINLINE for this socket. When this option is enabled urgent data can be received in-line with normal data.

Parameters
oobinline whether this option is enabled or not.
Throws
SocketException if an error occurs while setting the option.
See Also

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 the receive buffer size of this socket.

Parameters
size the buffer size in bytes. This value must be a positive number greater than 0.
Throws
SocketException if an error occurs while setting the size or the given value is an invalid size.
See Also

public void setReuseAddress (boolean reuse)

Since: API Level 1

Sets the state of the SocketOptions.SO_REUSEADDR for this socket.

Parameters
reuse the state whether this option is enabled or not.
Throws
SocketException if an error occurs while setting the option.
See Also

public synchronized void setSendBufferSize (int size)

Since: API Level 1

Sets the send buffer size of this socket.

Parameters
size the buffer size in bytes. This value must be a positive number greater than 0.
Throws
SocketException if an error occurs while setting the size or the given value is an invalid size.
See Also

public void setSoLinger (boolean on, int timeout)

Since: API Level 1

Sets the state of the SocketOptions.SO_LINGER with the given timeout in seconds. The timeout value for this option is silently limited to the maximum of 65535.

Parameters
on the state whether this option is enabled or not.
timeout the linger timeout value in seconds.
Throws
SocketException if an error occurs while setting the option.
See Also

public synchronized void setSoTimeout (int timeout)

Since: API Level 1

Sets the reading timeout in milliseconds for this socket. The read operation will block indefinitely if this option value is set to 0. The timeout must be set before calling the read operation. A SocketTimeoutException is thrown when this timeout expires.

Parameters
timeout the reading timeout value as number greater than 0 or 0 for an infinite timeout.
Throws
SocketException if an error occurs while setting the option.
See Also

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 the state of the SocketOptions.TCP_NODELAY for this socket.

Parameters
on the state whether this option is enabled or not.
Throws
SocketException if an error occurs while setting the option.
See Also

public void setTrafficClass (int value)

Since: API Level 1

Sets the value of the SocketOptions.IP_TOS for this socket. See the specification RFC 1349 for more information about the type of service field.

Parameters
value the value to be set for this option with a valid range of 0-255.
Throws
SocketException if an error occurs while setting the option.
See Also

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.