java.net

Class Socket

public class Socket extends Object

This class models a client site socket. A socket is a TCP/IP endpoint for network communications conceptually similar to a file handle.

This class does not actually do any work. Instead, it redirects all of its calls to a socket implementation object which implements the SocketImpl interface. The implementation class is instantiated by factory class that implements the SocketImplFactory interface. A default factory is provided, however the factory may be set by a call to the setSocketImplFactory method. Note that this may only be done once per virtual machine. If a subsequent attempt is made to set the factory, a SocketException will be thrown.

Constructor Summary
	Socket() Initializes a new instance of `Socket` object without connecting to a remote host.
protected	Socket(SocketImpl impl) Initializes a new instance of `Socket` object without connecting to a remote host.
	Socket(String host, int port) Initializes a new instance of `Socket` and connects to the hostname and port specified as arguments.
	Socket(InetAddress address, int port) Initializes a new instance of `Socket` and connects to the address and port number specified as arguments.
	Socket(String host, int port, InetAddress localAddr, int localPort) Initializes a new instance of `Socket` that connects to the named host on the specified port and binds to the specified local address and port.
	Socket(InetAddress address, int port, InetAddress localAddr, int localPort) Initializes a new instance of `Socket` and connects to the address and port number specified as arguments, plus binds to the specified local address and port.
	Socket(String host, int port, boolean stream) Initializes a new instance of `Socket` and connects to the hostname and port specified as arguments.
	Socket(InetAddress host, int port, boolean stream) Initializes a new instance of `Socket` and connects to the address and port number specified as arguments.

Method Summary
void	bind(SocketAddress bindpoint) Binds the socket to the given local address/port
void	close() Closes the socket.
void	connect(SocketAddress endpoint) Connects the socket with a remote address.
void	connect(SocketAddress endpoint, int timeout) Connects the socket with a remote address.
SocketChannel	getChannel() Returns the socket channel associated with this socket.
InetAddress	getInetAddress() Returns the address of the remote end of the socket.
InputStream	getInputStream() Returns an InputStream for reading from this socket.
boolean	getKeepAlive() This method returns the value of the socket level socket option SO_KEEPALIVE.
InetAddress	getLocalAddress() Returns the local address to which this socket is bound.
int	getLocalPort() Returns the local port number to which this socket is bound.
SocketAddress	getLocalSocketAddress() Returns local socket address.
boolean	getOOBInline() Returns the current setting of the SO_OOBINLINE option for this socket
OutputStream	getOutputStream() Returns an OutputStream for writing to this socket.
int	getPort() Returns the port number of the remote end of the socket connection.
int	getReceiveBufferSize() This method returns the value of the system level socket option SO_RCVBUF, which is used by the operating system to tune buffer sizes for data transfers.
SocketAddress	getRemoteSocketAddress() Returns the remote socket address.
boolean	getReuseAddress() Checks if the SO_REUSEADDR option is enabled
int	getSendBufferSize() This method returns the value of the system level socket option SO_SNDBUF, which is used by the operating system to tune buffer sizes for data transfers.
int	getSoLinger() Returns the value of the SO_LINGER option on the socket.
int	getSoTimeout() Returns the value of the SO_TIMEOUT option on the socket.
boolean	getTcpNoDelay() Tests whether or not the TCP_NODELAY option is set on the socket.
int	getTrafficClass() Returns the current traffic class
boolean	isBound() Checks if the socket is already bound.
boolean	isClosed() Checks if the socket is closed.
boolean	isConnected() Checks if the socket is connected
boolean	isInputShutdown() Checks if the socket's input stream is shutdown
boolean	isOutputShutdown() Checks if the socket's output stream is shutdown
void	sendUrgentData(int data) Sends urgent data through the socket
void	setKeepAlive(boolean on) This method sets the value for the socket level socket option SO_KEEPALIVE.
void	setOOBInline(boolean on) Enables/disables the SO_OOBINLINE option
void	setReceiveBufferSize(int size) This method sets the value for the system level socket option SO_RCVBUF to the specified value.
void	setReuseAddress(boolean reuseAddress) Enables/Disables the SO_REUSEADDR option
void	setSendBufferSize(int size) This method sets the value for the system level socket option SO_SNDBUF to the specified value.
static void	setSocketImplFactory(SocketImplFactory fac) Sets the `SocketImplFactory`.
void	setSoLinger(boolean on, int linger) Sets the value of the SO_LINGER option on the socket.
void	setSoTimeout(int timeout) Sets the value of the SO_TIMEOUT option on the socket.
void	setTcpNoDelay(boolean on) Sets the TCP_NODELAY option on the socket.
void	setTrafficClass(int tc) Sets the traffic class value
void	shutdownInput() Closes the input side of the socket stream.
void	shutdownOutput() Closes the output side of the socket stream.
String	toString() Converts this `Socket` to a `String`.

Constructor Detail

Socket

public Socket()

Initializes a new instance of Socket object without connecting to a remote host. This useful for subclasses of socket that might want this behavior.

Since: 1.1

UNKNOWN: This constructor is public since JDK 1.4

Socket

protected Socket(SocketImpl impl)

Initializes a new instance of Socket object without connecting to a remote host. This is useful for subclasses of socket that might want this behavior.

Additionally, this socket will be created using the supplied implementation class instead the default class or one returned by a factory. If this value is null, the default Socket implementation is used.

Parameters: impl The SocketImpl to use for this Socket

Throws: SocketException If an error occurs

Since: 1.1

Socket

public Socket(String host, int port)

Initializes a new instance of Socket and connects to the hostname and port specified as arguments.

Parameters: host The name of the host to connect to port The port number to connect to

Throws: UnknownHostException If the hostname cannot be resolved to a network address. IOException If an error occurs SecurityException If a security manager exists and its checkConnect method doesn't allow the operation

Socket

public Socket(InetAddress address, int port)

Initializes a new instance of Socket and connects to the address and port number specified as arguments.

Parameters: address The address to connect to port The port number to connect to

Throws: IOException If an error occurs SecurityException If a security manager exists and its checkConnect method doesn't allow the operation

Socket

public Socket(String host, int port, InetAddress localAddr, int localPort)

Initializes a new instance of Socket that connects to the named host on the specified port and binds to the specified local address and port.

Parameters: host The name of the remote host to connect to. port The remote port to connect to. localAddr The local address to bind to. localPort The local port to bind to.

Throws: SecurityException If the SecurityManager exists and does not allow a connection to the specified host/port or binding to the specified local host/port. IOException If a connection error occurs.

Since: 1.1

Socket

public Socket(InetAddress address, int port, InetAddress localAddr, int localPort)

Initializes a new instance of Socket and connects to the address and port number specified as arguments, plus binds to the specified local address and port.

Parameters: address The remote address to connect to port The remote port to connect to localAddr The local address to connect to localPort The local port to connect to

Throws: IOException If an error occurs SecurityException If a security manager exists and its checkConnect method doesn't allow the operation

Since: 1.1

Socket

public Socket(String host, int port, boolean stream)

Deprecated: Use the DatagramSocket class to create datagram oriented sockets.

Initializes a new instance of Socket and connects to the hostname and port specified as arguments. If the stream argument is set to true, then a stream socket is created. If it is false, a datagram socket is created.

Parameters: host The name of the host to connect to port The port to connect to stream true for a stream socket, false for a datagram socket

Throws: IOException If an error occurs SecurityException If a security manager exists and its checkConnect method doesn't allow the operation

Socket

public Socket(InetAddress host, int port, boolean stream)

Deprecated: Use the DatagramSocket class to create datagram oriented sockets.

Initializes a new instance of Socket and connects to the address and port number specified as arguments. If the stream param is true, a stream socket will be created, otherwise a datagram socket is created.

Parameters: host The address to connect to port The port number to connect to stream true to create a stream socket, false to create a datagram socket.

Throws: IOException If an error occurs SecurityException If a security manager exists and its checkConnect method doesn't allow the operation

Method Detail

bind

public void bind(SocketAddress bindpoint)

Binds the socket to the given local address/port

Parameters: bindpoint The address/port to bind to

Throws: IOException If an error occurs SecurityException If a security manager exists and its checkConnect method doesn't allow the operation IllegalArgumentException If the address type is not supported

Since: 1.4

close

public void close()

Closes the socket.

Throws: IOException If an error occurs

connect

public void connect(SocketAddress endpoint)

Connects the socket with a remote address.

Parameters: endpoint The address to connect to

Throws: IOException If an error occurs IllegalArgumentException If the addess type is not supported IllegalBlockingModeException If this socket has an associated channel, and the channel is in non-blocking mode

Since: 1.4

connect

public void connect(SocketAddress endpoint, int timeout)

Connects the socket with a remote address. A timeout of zero is interpreted as an infinite timeout. The connection will then block until established or an error occurs.

Parameters: endpoint The address to connect to timeout The length of the timeout in milliseconds, or 0 to indicate no timeout.

Throws: IOException If an error occurs IllegalArgumentException If the address type is not supported IllegalBlockingModeException If this socket has an associated channel, and the channel is in non-blocking mode SocketTimeoutException If the timeout is reached

Since: 1.4

getChannel

public SocketChannel getChannel()

Returns the socket channel associated with this socket.

Returns: the associated socket channel, null if no associated channel exists

Since: 1.4

getInetAddress

public InetAddress getInetAddress()

Returns the address of the remote end of the socket. If this socket is not connected, then null is returned.

Returns: The remote address this socket is connected to

getInputStream

public InputStream getInputStream()

Returns an InputStream for reading from this socket.

Returns: The InputStream object

Throws: IOException If an error occurs or Socket is not connected

getKeepAlive

public boolean getKeepAlive()

This method returns the value of the socket level socket option SO_KEEPALIVE.

Returns: The setting

Throws: SocketException If an error occurs or Socket is not connected

Since: 1.3

getLocalAddress

public InetAddress getLocalAddress()

Returns the local address to which this socket is bound. If this socket is not connected, then a wildcard address, for which

Returns: The local address

Since: 1.1

getLocalPort

public int getLocalPort()

Returns the local port number to which this socket is bound. If this socket is not connected, then -1 is returned.

Returns: The local port

getLocalSocketAddress

public SocketAddress getLocalSocketAddress()

Returns local socket address.

Returns: the local socket address, null if not bound

Since: 1.4

getOOBInline

public boolean getOOBInline()

Returns the current setting of the SO_OOBINLINE option for this socket

Returns: True if SO_OOBINLINE is set, false otherwise.

Throws: SocketException If an error occurs

Since: 1.4

getOutputStream

public OutputStream getOutputStream()

Returns an OutputStream for writing to this socket.

Returns: The OutputStream object

Throws: IOException If an error occurs or Socket is not connected

getPort

public int getPort()

Returns the port number of the remote end of the socket connection. If this socket is not connected, then 0 is returned.

Returns: The remote port this socket is connected to

getReceiveBufferSize

public int getReceiveBufferSize()

This method returns the value of the system level socket option SO_RCVBUF, which is used by the operating system to tune buffer sizes for data transfers.

Returns: The receive buffer size.

Throws: SocketException If an error occurs or Socket is not connected

Since: 1.2

getRemoteSocketAddress

public SocketAddress getRemoteSocketAddress()

Returns the remote socket address.

Returns: the remote socket address, null of not connected

Since: 1.4

getReuseAddress

public boolean getReuseAddress()

Checks if the SO_REUSEADDR option is enabled

Returns: True if SO_REUSEADDR is set, false otherwise.

Throws: SocketException If an error occurs

Since: 1.4

getSendBufferSize

public int getSendBufferSize()

This method returns the value of the system level socket option SO_SNDBUF, which is used by the operating system to tune buffer sizes for data transfers.

Returns: The send buffer size.

Throws: SocketException If an error occurs or socket not connected

Since: 1.2

getSoLinger

public int getSoLinger()

Returns the value of the SO_LINGER option on the socket. If the SO_LINGER option is set on a socket and there is still data waiting to be sent when the socket is closed, then the close operation will block until either that data is delivered or until the timeout period expires. This method either returns the timeouts (in hundredths of of a second (platform specific?)) if SO_LINGER is set, or -1 if SO_LINGER is not set.

Returns: The SO_LINGER timeout in hundreths of a second or -1 if SO_LINGER not set

Throws: SocketException If an error occurs or Socket is not connected

Since: 1.1

getSoTimeout

public int getSoTimeout()

Returns the value of the SO_TIMEOUT option on the socket. If this value is set, and an read/write is performed that does not complete within the timeout period, a short count is returned (or an EWOULDBLOCK signal would be sent in Unix if no data had been read). A value of 0 for this option implies that there is no timeout (ie, operations will block forever). On systems that have separate read and write timeout values, this method returns the read timeout. This value is in thousandths of a second (implementation specific?).

Returns: The length of the timeout in thousandth's of a second or 0 if not set

Throws: SocketException If an error occurs or Socket not connected

Since: 1.1

getTcpNoDelay

public boolean getTcpNoDelay()

Tests whether or not the TCP_NODELAY option is set on the socket. Returns true if enabled, false if disabled. When on it disables the Nagle algorithm which means that packets are always send immediatly and never merged together to reduce network trafic.

Returns: Whether or not TCP_NODELAY is set

Throws: SocketException If an error occurs or Socket not connected

Since: 1.1

getTrafficClass

public int getTrafficClass()

Returns the current traffic class

Returns: The current traffic class.

Throws: SocketException If an error occurs

Since: 1.4

isBound

public boolean isBound()

Checks if the socket is already bound.

Returns: True if socket is bound, false otherwise.

Since: 1.4

isClosed

public boolean isClosed()

Checks if the socket is closed.

Returns: True if socket is closed, false otherwise.

Since: 1.4

isConnected

public boolean isConnected()

Checks if the socket is connected

Returns: True if socket is connected, false otherwise.

Since: 1.4

isInputShutdown

public boolean isInputShutdown()

Checks if the socket's input stream is shutdown

Returns: True if input is shut down.

Since: 1.4

isOutputShutdown

public boolean isOutputShutdown()

Checks if the socket's output stream is shutdown

Returns: True if output is shut down.

Since: 1.4

sendUrgentData

public void sendUrgentData(int data)

Sends urgent data through the socket

Parameters: data The data to send. Only the lowest eight bits of data are sent

Throws: IOException If an error occurs

Since: 1.4

setKeepAlive

public void setKeepAlive(boolean on)

This method sets the value for the socket level socket option SO_KEEPALIVE.

Parameters: on True if SO_KEEPALIVE should be enabled

Throws: SocketException If an error occurs or Socket is not connected

Since: 1.3

setOOBInline

public void setOOBInline(boolean on)

Enables/disables the SO_OOBINLINE option

Parameters: on True if SO_OOBLINE should be enabled

Throws: SocketException If an error occurs

Since: 1.4

setReceiveBufferSize

public void setReceiveBufferSize(int size)

This method sets the value for the system level socket option SO_RCVBUF to the specified value. Note that valid values for this option are specific to a given operating system.

Parameters: size The new receive buffer size.

Throws: SocketException If an error occurs or Socket is not connected IllegalArgumentException If size is 0 or negative

Since: 1.2

setReuseAddress

public void setReuseAddress(boolean reuseAddress)

Enables/Disables the SO_REUSEADDR option

Parameters: reuseAddress true if SO_REUSEADDR should be enabled, false otherwise

Throws: SocketException If an error occurs

Since: 1.4

setSendBufferSize

public void setSendBufferSize(int size)

This method sets the value for the system level socket option SO_SNDBUF to the specified value. Note that valid values for this option are specific to a given operating system.

Parameters: size The new send buffer size.

Throws: SocketException If an error occurs or Socket not connected IllegalArgumentException If size is 0 or negative

Since: 1.2

setSocketImplFactory

public static void setSocketImplFactory(SocketImplFactory fac)

Sets the SocketImplFactory. This may be done only once per virtual machine. Subsequent attempts will generate a SocketException. Note that a SecurityManager check is made prior to setting the factory. If insufficient privileges exist to set the factory, then an IOException will be thrown.

Parameters: fac the factory to set

Throws: SecurityException If the SecurityManager does not allow this operation. SocketException If the SocketImplFactory is already defined IOException If any other error occurs

setSoLinger

public void setSoLinger(boolean on, int linger)

Sets the value of the SO_LINGER option on the socket. If the SO_LINGER option is set on a socket and there is still data waiting to be sent when the socket is closed, then the close operation will block until either that data is delivered or until the timeout period expires. The linger interval is specified in hundreths of a second (platform specific?)

Parameters: on true to enable SO_LINGER, false to disable linger The SO_LINGER timeout in hundreths of a second or -1 if SO_LINGER not set.

Throws: SocketException If an error occurs or Socket not connected IllegalArgumentException If linger is negative

Since: 1.1

setSoTimeout

public void setSoTimeout(int timeout)

Sets the value of the SO_TIMEOUT option on the socket. If this value is set, and an read/write is performed that does not complete within the timeout period, a short count is returned (or an EWOULDBLOCK signal would be sent in Unix if no data had been read). A value of 0 for this option implies that there is no timeout (ie, operations will block forever). On systems that have separate read and write timeout values, this method returns the read timeout. This value is in milliseconds.

Parameters: timeout The length of the timeout in milliseconds, or 0 to indicate no timeout.

Throws: SocketException If an error occurs or Socket not connected

Since: 1.1