home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Java Fundamental Classes Reference

Previous Chapter 15
The java.net Package
Next
 

ServerSocket

Name

ServerSocket

Synopsis

Class Name:

java.net.ServerSocket

Superclass:

java.lang.Object

Immediate Subclasses:

None

Interfaces Implemented:

None

Availability:

JDK 1.0 or later

Description

The ServerSocket class represents a socket that listens for connection requests from clients on a specified port. When a connection is requested, a Socket object is created to handle the communication.

The low-level network access in ServerSocket is provided by a subclass of the abstract class SocketImpl. An application can change the server socket factory that creates the SocketImpl subclass by supplying a SocketImplFactory using the setSocketFactory() method. This feature allows an application to create sockets that are appropriate for the local network configuration and accommodate such things as firewalls.

Class Summary

public class java.net.ServerSocket extends java.lang.Object {
  // Constructors
  public ServerSocket(int port);
  public ServerSocket(int port, int backlog);
  public ServerSocket(int port, int backlog, 
                      InetAddress bindAddr);              // New in 1.1
  // Class Methods
  public static synchronized void setSocketFactory(SocketImplFactory fac);
  // Instance Methods
  public Socket accept();
  public void close();
  public InetAddress getInetAddress();
  public int getLocalPort();
  public synchronized int getSoTimeout()                  // New in 1.1
  public synchronized void setSoTimeout(int timeout);     // New in 1.1
  public String toString();
  // Protected Instance Methods
  protected final void implAccept(Socket s);              // New in 1.1
}

Constructors

ServerSocket

public ServerSocket(int port) throws IOException

Parameters

port

A port number, or 0 for any available port.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to listen on the given port.

Description

This method creates a server socket that listens for a connection on the given port. A default of 50 pending connections can be queued by the ServerSocket. Calling accept() removes a pending connections from the queue. If the queue is full, additional connection requests are refused.

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

public ServerSocket(int port, int backlog) throws IOException

Parameters

port

A port number, or 0 for any available port.

backlog

The maximum length of the pending connections queue.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to listen on the given port.

Description

This method creates a server socket that listens for a connection on the given port. The backlog parameter specifies how many pending connections can be queued by the ServerSocket. Calling accept() removes a pending connection from the queue. If the queue is full, additional connection requests are refused.

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

 public ServerSocket(int port, int backlog, InetAddress bindAddr) throws IOException 

Availability

New as of JDK 1.1

Parameters

port

A port number, or 0 for any available port.

backlog

The maximum length of the pending connections queue.

bindAddr

A local address.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to listen on the given port.

Description

This method creates a server socket that listens for a connection on the given port of bindAddr. On machines with multiple addresses, bindAddr specifies the address on which this ServerSocket listens. The backlog parameter specifies how many pending connections can be queued by the ServerSocket. Calling accept() removes pending connections from the queue. If the queue is full, additional connection requests are refused.

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

Class Methods

setSocketFactory

 public static synchronized void setSocketFactory( 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 is used to set the SocketImplFactory. This factory object produces instances of subclasses of SocketImpl that do the low-level work of server sockets. When a ServerSocket constructor is called, the createSocketImpl() method of the factory is called to create the server socket implementation.

Instance Methods

accept

public Socket accept() throws IOException

Returns

A Socket object for the connection.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to accept the connection.

Description

This method accepts a connection and returns a Socket object to handle communication. If there are pending connections, the method accepts a pending connection from the queue and returns immediately. Otherwise, the method may block until a connection is requested. If a time-out value has been specified using the setSoTimeout() method, accept() may time out and throw an InterruptedIOException if no connection is requested in the time-out period.

close

public void close() throws IOException

Throws

IOException

If any kind of I/O error occurs.

Description

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

getInetAddress

public InetAddress getInetAddress()

Returns

The IP address to which this ServerSocket is listening.

Description

Generally, this method returns the address of the local host. However, a ServerSocket can be constructed with an alternate address using ServerSocket(int, int, InetAddress). The method returns null if the socket is not yet connected.

getLocalPort

public int getLocalPort()

Returns

The port number to which this ServerSocket is listening.

Description

This method returns the port number to which this object is connected.

getSoTimeout

public synchronized int getSoTimeout() throws IOException

Availability

New as of JDK 1.1

Returns

The receive timeout value for the socket.

Throws

IOException

If any kind of I/O error occurs.

Description

This method returns the receive time-out value for this socket. A value of zero indicates that accept() waits indefinitely for an incoming packet, while a non-zero value indicates the number of milliseconds it waits.

setSoTimeout

 public synchronized void setSoTimeout(int timeout) throws SocketException 

Availability

New as of JDK 1.1

Parameters

timeout

The new time-out value, in milliseconds, for this 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 accept(). A nonzero value is the length of time, in milliseconds, the ServerSocket should wait for a connection. A value of zero indicates that the ServerSocket should wait indefinitely. If a time-out value is needed, this method must be called before accept().

toString

public String toString()

Returns

The string representation of this ServerSocket.

Overrides

Object.toString()

Description

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

Protected Instance Methods

implAccept

protected final void implAccept(Socket s) throws IOException

Availability

New as of JDK 1.1

Parameters

s

The Socket object to be connected.

Throws

IOException

If any kind of I/O error occurs.

SecurityException

If the application is not allowed to accept the connection.

Description

This method is a helper method for accept(). It can be overridden in subclasses of ServerSocket to support new subclasses of 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

See Also

InetAddress, IOException, SecurityException, Socket, SocketException, SocketImpl, SocketImplFactory


Previous Home Next
ProtocolException Book Index Socket

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java