Chapter 15
The java.net Package

Socket

Name

Socket

Synopsis

Class Name:

java.net.Socket

Superclass:

java.lang.Object

Immediate Subclasses:

None

Interfaces Implemented:

None

Availability:

JDK 1.0 or later

The Socket class implements stream-based, connection-oriented, reliable data communication. Although Socket objects are often used with the Transmission Control Protocol, commonly known as TCP, they are independent of the actual protocol being used. The Socket class encapsulates client logic that is common to connection-oriented protocols. Sockets are two-way data pipes that are connected on either end to an address and port number. As of JDK 1.1, new constructors allow you to specify the local address and port as well as the remote address and port.

A Socket object uses an object that belongs to a subclass of the abstract class SocketImpl to access protocol-specific logic. A program can specify the subclass of SocketImpl that is used by passing an appropriate SocketImplFactory object to the setSocketImplFactory() method before any Socket objects are created. This feature allows a program to create sockets that are able to accommodate such things as firewalls or even work with different protocols.

Class Summary

public class java.net.Socket extends java.lang.Object {
  // Constructors
  public Socket(String host, int port);
  public Socket(InetAddress address, int port);
  public Socket(String host, int port, 
                InetAddress localAddr, int localPort);     // New in 1.1
  public Socket(InetAddress address, int port, 
                InetAddress localAddr, int localPort);     // New in 1.1
  public Socket(String host, int port, 
                boolean stream);                     // Deprecated in 1.1
  public Socket(InetAddress host, int port, 
                boolean stream);                     // Deprecated in 1.1
  protected Socket();                                      // New in 1.1
  protected Socket(SocketImpl impl);                       // New in 1.1
  // Class Methods
  public static synchronized void setSocketImplFactory(
                                  SocketImplFactory fac); 
  // Instance Methods
  public synchronized void close();
  public InetAddress getInetAddress();
  public InputStream getInputStream();
  public InetAddress getLocalAddress();                    // New in 1.1
  public int getLocalPort();
  public OutputStream getOutputStream();
  public int getPort();
  public int getSoLinger();                                // New in 1.1
  public synchronized int getSoTimeout();                  // New in 1.1
  public boolean getTcpNoDelay();                          // New in 1.1
  public void setSoLinger(boolean on, int val);            // New in 1.1
  public synchronized void setSoTimeout(int timeout);      // New in 1.1
  public void setTcpNoDelay(boolean on);                   // New in 1.1
  public String toString();
}

Constructors

Socket

 public Socket(String host, int port) throws IOException, UnknownHostException

Parameters

host

The name of a remote machine.

port

A port on a remote machine.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to connect to the given host and port.

UnknownHostException

If the IP address of the given hostname cannot be determined.

Description

This constructor creates a Socket and connects it to the specified port on the given host.

If a program has specified a socket factory, the createSocketImpl() method of that factory is called to create the actual socket implementation. Otherwise, the constructor creates a plain socket.

public Socket(InetAddress address, int port) throws IOException

Parameters

address

The IP address of a remote machine.

port

A port on a remote machine.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to connect to the given address and port.

Description

This constructor creates a Socket and connects it to the specified port on the host at the given address.

If a program has specified a socket factory, the createSocketImpl() method of that factory is called to create the actual socket implementation. Otherwise, the constructor creates a plain socket.

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

Availability

New as of JDK 1.1

Parameters

host

The name of a remote machine.

port

A port on a remote machine.

localAddr

An IP address on the local host.

localPort

A port on the local host.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to connect to the given host and port.

Description

This constructor creates a Socket and connects it to the specified port on the given host. The constructor also binds the Socket to the specified local address and port.

If a program has specified a socket factory, the createSocketImpl() method of that factory is called to create the actual socket implementation. Otherwise, the constructor creates a plain socket.

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

Availability

New as of JDK 1.1

Parameters

address

The IP address of a remote machine.

port

A port on a remote machine.

localAddr

An IP address on the local host.

localPort

A port on the local host.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to connect to the given address and port.

Description

This constructor creates a Socket and connects it to the specified port on the host at the given address. The constructor also binds the Socket to the specified local address and port.

If a program has specified a socket factory, the createSocketImpl() method of that factory is called to create the actual socket implementation. Otherwise, the constructor creates a plain socket.

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

Availability

Deprecated as of JDK 1.1

Parameters

host

The name of a remote machine.

port

A port on a remote machine.

stream

A boolean value that indicates if this socket is a stream socket.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to connect to the given host and port.

Description

This constructor creates a Socket and connects it to the specified port on the given host.

If the stream argument is true, a stream socket is created. Otherwise, a datagram socket is created. This constructor is deprecated as of JDK 1.1; use DatagramSocket for datagrams.

If a program has specified a socket factory, the createSocketImpl() method of that factory is called to create the actual socket implementation. Otherwise, the constructor creates a plain socket.

 public Socket(InetAddress address, int port, boolean stream) throws IOException

Availability

Deprecated as of JDK 1.1

Parameters

address

The IP address of a remote machine.

port

A port on a remote machine.

stream

A boolean value that indicates if this socket is a stream socket.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to connect to the given host and port.

Description

This constructor creates a Socket and connects it to the specified port on the host at the given address.

If the stream argument is true, a stream socket is created. Otherwise, a datagram socket is created. This constructor is deprecated as of JDK 1.1; use DatagramSocket for datagrams.

If a program has specified a socket factory, the createSocketImpl() method of that factory is called to create the actual socket implementation. Otherwise, the constructor creates a plain socket.

protectedSocket()

Availability

New as of JDK 1.1

Description

This constructor creates a Socket that uses an instance of the system default SocketImpl subclass for its low-level network access.

protectedSocket(SocketImpl impl) throws SocketException

Availability

New as of JDK 1.1

Parameters

impl: The socket implementation to use.

Throws

SocketException: This exception is never thrown by this constructor.

Description

This constructor creates a Socket that uses the given object for its low-level network access.

Class Methods

setSocketImplFactory

 public static synchronized void setSocketImplFactory( SocketImplFactory fac) throws IOException

Parameters

fac: An object that implements SocketImplFactory.

Throws

IOException

If the factory has already been defined.

SecurityException

If the application does not have permission to set the factory.

Description

This method sets the SocketImplFactory. This factory produces instances of subclasses of SocketImpl that do the low-level work of sockets. When a Socket constructor is called, the createSocketImpl() method of the factory is called to create the socket implementation.

Instance Methods

close

public synchronized void close() throws IOException

Throws

IOException: If any kind of I/O error occurs.

Description

This method closes this socket, releasing any system resources it holds.

getInetAddress

public InetAddress getInetAddress()

Returns

The remote IP address to which this Socket is connected.

Description

This method returns the IP address of the remote host to which this socket is connected.

getInputStream

public InputStream getInputStream() throws IOException

Returns

An InputStream that wraps this socket.

Throws

IOException: If any kind of I/O error occurs.

Description

This method returns an InputStream that reads data from the socket.

getLocalAddress

public InetAddress getLocalAddress()

Availability

New as of JDK 1.1

Returns

The local IP address from which this Socket originates.

Description

This method returns the local address that is the origin of the socket.

getLocalPort

public int getLocalPort()

Returns

The local port number from which this Socket originates.

Description

This method returns the local port number that is the origin of the socket.

getOutputStream

public OutputStream getOutputStream() throws IOException

Returns

An OutputStream that wraps this socket.

Throws

IOException: If any kind of I/O error occurs.

Description

This method returns an OutputStream that sends data through the socket.

getPort

public int getPort()

Returns

The remote port number to which this Socket is connected.

Description

This method returns the port number of the remote host to which this socket is connected.

getSoLinger

public int getSoLinger() throws SocketException

Availability

New as of JDK 1.1

Returns

The close time-out value for the socket.

Throws

SocketException: If any kind of socket error occurs.

Description

This method returns the close time-out value for this socket. A value of -1 or 0 indicates that close()closes the socket immediately. A value greater than 0 indicates the amount of time, in seconds, that close() blocks, waiting for unsent data to be sent.

getSoTimeout

public synchronized int getSoTimeout() throws SocketException

Availability

New as of JDK 1.1

Returns

The read time-out value for the socket.

Throws

SocketException: If any kind of socket error occurs.

Description

This method returns the read time-out value for this socket. A value of zero indicates that the read() method of the associated InputStream waits indefinitely for an incoming packet, while a non-zero value indicates the number of milliseconds it waits before throwing an InterruptedIOException.

getTcpNoDelay

public boolean getTcpNoDelay() throws SocketException

Availability

New as of JDK 1.1

Returns

true if Nagle's algorithm is disabled for this connection; false otherwise.

Throws

SocketException: If any kind of socket error occurs.

Description

This method indicates whether Nagle's algorithm is disabled for this socket or not. Said another way, it indicates whether the TCPNODELAY option is enabled or not.

In essence, Nagle's algorithm takes small outgoing packets that are closely spaced in time and combines them into larger packets. This improves overall efficiency, since each packet has a certain amount of overhead; however, it does so at the expense of immediacy.

setSoLinger

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

Availability

New as of JDK 1.1

Parameters

on

A boolean value that specifies whether or not close() blocks

val

The new close time-out value, in seconds, for this socket.

Throws

SocketException: If any kind of socket error occurs.

Description

This method sets the close timeout value for this socket. If val is -1 or 0, or if on is false, close() closes the socket immediately. If on is true and val is greater than 0, val indicates the amount of time, in seconds, that close() blocks, waiting for unsent data to be sent.

setSoTimeout

 public synchronized void setSoTimeout(int timeout) throws SocketException

Availability

New as of JDK 1.1

Parameters

timeout: The new read time-out value, in milliseconds, for the socket.

Throws

SocketException: If any kind of socket error occurs.

Description

This method is used to set the time-out value that is used for the read() method of the corresponding InputStream. A non-zero value is the length of time, in milliseconds, that the Socket should wait for data before throwing an InterruptedIOException. A value of zero indicates that the Socket should wait indefinitely. If a timeout value is needed, this method must be called before read().

setTcpNoDelay

public void setTcpNoDelay(boolean on) throws SocketException

Availability

New as of JDK 1.1

Parameters

on: A boolean value that specifies whether or not to disable Nagle's algorithm.

Throws

SocketException: If any kind of socket error occurs.

Description

This method specifies whether Nagle's algorithm is disabled for this socket or not. Said another way, it determines whether the TCPNODELAY option is enabled or not.

toString

public String toString()

Returns

The string representation of this Socket.

Overrides

Object.toString()

Description

This method returns a String that contains the address and port of this Socket.

Inherited Methods

Method	Inherited From	Method	Inherited From
`clone()`	`Object`	`equals(Object)`	`Object`
`finalize()`	`Object`	`getClass()`	`Object`
`hashCode()`	`Object`	`notify()`	`Object`
`notifyAll()`	`Object`	`wait()`	`Object`
`wait(long)`	`Object`	`wait(long, int)`	`Object`