java.net

Class Socket

Known Direct Subclasses:
LocalSocket, NIOSocket, SSLSocket

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.
Socket(String host, int port)
Initializes a new instance of Socket and connects to the hostname and port specified as arguments.
Socket(String host, int port, boolean stream)
Deprecated. Use the DatagramSocket class to create datagram oriented sockets.
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)
Initializes a new instance of Socket and connects to the address and port number specified as arguments.
Socket(InetAddress host, int port, boolean stream)
Deprecated. Use the DatagramSocket class to create datagram oriented sockets.
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(SocketImpl impl)
Initializes a new instance of Socket object without connecting to a remote host.

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.
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.
static void
setSocketImplFactory(SocketImplFactory fac)
Sets the SocketImplFactory.
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.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

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

Socket

public Socket(String host,
              int port)
            throws UnknownHostException,
                   IOException
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(String host,
              int port,
              boolean stream)
            throws IOException

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(String host,
              int port,
              InetAddress localAddr,
              int localPort)
            throws IOException
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)
            throws IOException
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(InetAddress host,
              int port,
              boolean stream)
            throws IOException

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

Socket

public Socket(InetAddress address,
              int port,
              InetAddress localAddr,
              int localPort)
            throws IOException
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

protected Socket(SocketImpl impl)
            throws SocketException
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

Method Details

bind

public void bind(SocketAddress bindpoint)
            throws IOException
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()
            throws IOException
Closes the socket.
Throws:
IOException - If an error occurs

connect

public void connect(SocketAddress endpoint)
            throws IOException
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)
            throws IOException
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
SecurityException - if the SocketAddress is an InetSocketAddress and a security manager is present which does not allow connections on the given host and port.
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()
            throws IOException
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()
            throws SocketException
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()
            throws SocketException
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()
            throws IOException
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()
            throws SocketException
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()
            throws SocketException
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()
            throws SocketException
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()
            throws SocketException
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()
            throws SocketException
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()
            throws SocketException
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()
            throws SocketException
Returns the current traffic class
Returns:
The current traffic class.
Throws:
SocketException - If an error occurs
Since:
1.4
See Also:
Socket.setTrafficClass(int tc)

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)
            throws IOException
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)
            throws SocketException
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)
            throws SocketException
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)
            throws SocketException
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)
            throws SocketException
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)
            throws SocketException
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

setSoLinger

public void setSoLinger(boolean on,
                        int linger)
            throws SocketException
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)
            throws SocketException
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

setSocketImplFactory

public static void setSocketImplFactory(SocketImplFactory fac)
            throws IOException
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.
IOException - If any other error occurs

setTcpNoDelay

public void setTcpNoDelay(boolean on)
            throws SocketException
Sets the TCP_NODELAY option on the socket.
Parameters:
on - true to enable, false to disable
Throws:
SocketException - If an error occurs or Socket is not connected
Since:
1.1

setTrafficClass

public void setTrafficClass(int tc)
            throws SocketException
Sets the traffic class value
Parameters:
tc - The traffic class
Throws:
SocketException - If an error occurs
IllegalArgumentException - If tc value is illegal
Since:
1.4

shutdownInput

public void shutdownInput()
            throws IOException
Closes the input side of the socket stream.
Throws:
IOException - If an error occurs.
Since:
1.3

shutdownOutput

public void shutdownOutput()
            throws IOException
Closes the output side of the socket stream.
Throws:
IOException - If an error occurs.
Since:
1.3

toString

public String toString()
Converts this Socket to a String.
Overrides:
toString in interface Object
Returns:
The String representation of this Socket

Socket.java -- Client socket implementation Copyright (C) 1998, 1999, 2000, 2002, 2003, 2004, 2006, 2007 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.