Package java.net

Class Socket

java.lang.Object

java.net.Socket

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

SSLSocket

public class Socket
extends Object
implements Closeable

Provides a client-side TCP socket.

Constructor Summary

Constructors

Modifier	Constructor	Description
	Socket()	Creates a new unconnected socket.
	Socket(String dstName, int dstPort)	Creates a new streaming socket connected to the target host specified by the parameters dstName and dstPort.
	Socket(String hostName, int port, boolean streaming)	Deprecated. Use Socket(String, int) instead of this for streaming sockets or an appropriate constructor of DatagramSocket for UDP transport.
	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(InetAddress dstAddress, int dstPort)	Creates a new streaming socket connected to the target host specified by the parameters dstAddress and dstPort.
	Socket(InetAddress addr, int port, boolean streaming)	Deprecated. Use Socket(InetAddress, int) instead of this for streaming sockets or an appropriate constructor of DatagramSocket for UDP transport.
	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(Proxy proxy)	Creates a new unconnected socket using the given proxy type.
protected	Socket(SocketImpl impl)	Creates an unconnected socket with the given socket implementation.

Method Summary

Modifier and Type	Method	Description
void	bind(SocketAddress localAddr)	Binds this socket to the given local host address and port specified by the SocketAddress localAddr.
void	close()	Closes the socket.
void	connect(SocketAddress remoteAddr)	Connects this socket to the given remote host address and port specified by the SocketAddress remoteAddr.
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.
SocketChannel	getChannel()	Returns this socket's SocketChannel, if one exists.
FileDescriptor	getFileDescriptor$()
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 SocketOptions.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 SocketOptions.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.
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 SocketOptions.SO_REUSEADDR setting.
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.
int	getSoTimeout()	Returns this socket's receive timeout.
boolean	getTcpNoDelay()	Returns this socket's SocketOptions#TCP_NODELAY setting.
int	getTrafficClass()	Returns this socket's {@see SocketOptions#IP_TOS} 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 SocketOptions.SO_KEEPALIVE option.
void	setOOBInline(boolean oobinline)	Sets this socket's SocketOptions.SO_OOBINLINE option.
void	setPerformancePreferences(int connectionTime, int latency, int bandwidth)	Sets performance preferences for connectionTime, latency and bandwidth.
void	setReceiveBufferSize(int size)	Sets this socket's receive buffer size.
void	setReuseAddress(boolean reuse)	Sets this socket's SocketOptions.SO_REUSEADDR option.
void	setSendBufferSize(int size)	Sets this socket's send buffer size.
static void	setSocketImplFactory(SocketImplFactory fac)	Sets the internal factory for creating socket implementations.
void	setSoLinger(boolean on, int timeout)	Sets this socket's linger timeout in seconds.
void	setSoTimeout(int timeout)	Sets this socket's read timeout in milliseconds.
void	setTcpNoDelay(boolean on)	Sets this socket's SocketOptions.TCP_NODELAY option.
void	setTrafficClass(int value)	Sets this socket's SocketOptions.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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

Socket

public Socket()

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:

SocketImplFactory, SocketImpl

Socket

public Socket(Proxy proxy)

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.

See Also:

SocketImplFactory, SocketImpl

Socket

public Socket(String dstName, int dstPort) throws UnknownHostException, IOException

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.

This implementation tries each IP address for the given hostname (in RFC 3484 order) until it either connects successfully or it exhausts the set.

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.

Socket

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

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.

This implementation tries each IP address for the given hostname (in RFC 3484 order) until it either connects successfully or it exhausts the set.

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.

Socket

@Deprecated public Socket(String hostName, int port, boolean streaming) throws IOException

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.

This implementation tries each IP address for the given hostname (in RFC 3484 order) until it either connects successfully or it exhausts the set.

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.

Socket

public Socket(InetAddress dstAddress, int dstPort) throws IOException

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.

Socket

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

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.

Socket

@Deprecated public Socket(InetAddress addr, int port, boolean streaming) throws IOException

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.

Socket

protected Socket(SocketImpl impl) throws SocketException

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.

Method Details

close

public void close() throws IOException

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.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - if an error occurs while closing the socket.

getInetAddress

public InetAddress getInetAddress()

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

getInputStream

public InputStream getInputStream() throws IOException

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.

getKeepAlive

public boolean getKeepAlive() throws SocketException

Returns this socket's SocketOptions.SO_KEEPALIVE setting.

Throws:

SocketException

getLocalAddress

public InetAddress getLocalAddress()

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

getLocalPort

public int getLocalPort()

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

getOutputStream

public OutputStream getOutputStream() throws IOException

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.

getPort

public int getPort()

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

getSoLinger

public int getSoLinger() throws SocketException

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

Throws:

SocketException

getReceiveBufferSize

public int getReceiveBufferSize() throws SocketException

Returns this socket's receive buffer size.

Throws:

SocketException

getSendBufferSize

public int getSendBufferSize() throws SocketException

Returns this socket's send buffer size.

Throws:

SocketException

getSoTimeout

public int getSoTimeout() throws SocketException

Returns this socket's receive timeout.

Throws:

SocketException

getTcpNoDelay

public boolean getTcpNoDelay() throws SocketException

Returns this socket's SocketOptions#TCP_NODELAY setting.

Throws:

SocketException

setKeepAlive

public void setKeepAlive(boolean keepAlive) throws SocketException

Sets this socket's SocketOptions.SO_KEEPALIVE option.

Throws:

SocketException

setSocketImplFactory

public static void setSocketImplFactory(SocketImplFactory fac) throws IOException

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.

setSendBufferSize

public void setSendBufferSize(int size) throws SocketException

Sets this socket's send buffer size.

Throws:

SocketException

setReceiveBufferSize

public void setReceiveBufferSize(int size) throws SocketException

Sets this socket's receive buffer size.

Throws:

SocketException

setSoLinger

public void setSoLinger(boolean on, int timeout) throws SocketException

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

Throws:

SocketException

setSoTimeout

public void setSoTimeout(int timeout) throws SocketException

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

setTcpNoDelay

public void setTcpNoDelay(boolean on) throws SocketException

Sets this socket's SocketOptions.TCP_NODELAY option.

Throws:

SocketException

toString

public String toString()

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

Overrides:

toString in class Object

Returns:

the textual representation of this socket.

shutdownInput

public void shutdownInput() throws IOException

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.

shutdownOutput

public void shutdownOutput() throws IOException

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.

getLocalSocketAddress

public SocketAddress getLocalSocketAddress()

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.

getRemoteSocketAddress

public SocketAddress getRemoteSocketAddress()

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.

isBound

public boolean isBound()

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.

isConnected

public boolean isConnected()

Returns whether this socket is connected to a remote host.

Returns:

true if the socket is connected, false otherwise.

isClosed

public boolean isClosed()

Returns whether this socket is closed.

Returns:

true if the socket is closed, false otherwise.

bind

public void bind(SocketAddress localAddr) throws IOException

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.

connect

public void connect(SocketAddress remoteAddr) throws IOException

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.

connect

public void connect(SocketAddress remoteAddr, int timeout) throws IOException

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.

isInputShutdown

public boolean isInputShutdown()

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.

isOutputShutdown

public boolean isOutputShutdown()

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.

setReuseAddress

public void setReuseAddress(boolean reuse) throws SocketException

Sets this socket's SocketOptions.SO_REUSEADDR option.

Throws:

SocketException

getReuseAddress

public boolean getReuseAddress() throws SocketException

Returns this socket's SocketOptions.SO_REUSEADDR setting.

Throws:

SocketException

setOOBInline

public void setOOBInline(boolean oobinline) throws SocketException

Sets this socket's SocketOptions.SO_OOBINLINE option.

Throws:

SocketException

getOOBInline

public boolean getOOBInline() throws SocketException

Returns this socket's SocketOptions.SO_OOBINLINE setting.

Throws:

SocketException

setTrafficClass

public void setTrafficClass(int value) throws SocketException

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

Throws:

SocketException

getTrafficClass

public int getTrafficClass() throws SocketException

Returns this socket's {@see SocketOptions#IP_TOS} setting.

Throws:

SocketException

sendUrgentData

public void sendUrgentData(int value) throws IOException

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.

getChannel

public SocketChannel getChannel()

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 ServerSocketChannel.accept() or SocketChannel.open().

getFileDescriptor$

public FileDescriptor getFileDescriptor$()

setPerformancePreferences

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

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.