Socket(InetAddress remoteAddr,  int remotePort)
Socket(String remoteHost,  int remotePort)
Socket(InetAddress remoteAddr,  int remotePort,  InetAddress localAddr,  int localPort)
Socket(String remoteHost,  int remotePort, InetAddress localAddr, int localPort)
Socket()

The first four constructors create a TCP socket and connect it to the specified remote address and port before returning. The first two do not specify the local address and port, so a default local address and some available port are chosen. Specifying the local address may be useful on a host with multiple interfaces. String arguments that specify destinations can be in the same formats that are accepted by the InetAddress creation methods. The last constructor creates an unconnected socket, which must be explicitly connected (via the connect() method, see below) before it can be used for communication.

void connect(SocketAddress destination)
void connect(SocketAddress destination, int timeout)
InputStream getInputStream()
OutputStream getOutputStream()
void close()
void shutdownInput()
void shutdownOutput()

The connect() methods cause a TCP connection to the specified endpoints to be opened. The abstract class SocketAddress represents a generic form of address for a socket; its subclass InetSocketAddress is specific to TCP/IP sockets (see description below). Communication with the remote system takes place via the associated I/O streams, which are obtained through the get... Stream() methods.

The close() method closes the socket and its associated I/O streams, preventing further operations on them. The shutDownInput() method closes the input side of a TCP stream. Any unread data is silently discarded, including data buffered by the socket, data in transit, and data arriving in the future. Any subsequent attempt to read from the socket will cause an exception to be thrown. The shutDownOutput() method has a similar effect on the output stream, but the implementation will attempt to ensure that any data already written to the socket’s output stream is delivered to the other end. See Section 4.5 for further details.

InetAddress getInetAddress()
int getPort()
InetAddress getLocalAddress()
int getLocalPort()
SocketAddress getRemoteSocketAddress()
SocketAddress getLocalSocketAddress()

These methods return the indicated attributes of the socket, and any method in this book that returns a SocketAddress actually returns an instance of InetSocketAddress. The InetSocketAddress encapsulates an InetAddress and a port number.

The Socket class actually has a large number of other associated attributes referred to as socket options. Because they are not necessary for writing basic applications, we postpone introduction of them until Section 4.4.

InetSocketAddress(InetAddress addr,  int port)
InetSocketAddress(int port)
InetSocketAddress(String hostname,  int port)
static InetSocketAddress createUnresolved(String host,  int port)
boolean isUnresolved()
InetAddress getAddress()
int getPort()
String getHostName()
String toString()

The InetSocketAddress class provides an immutable combination of host address and port. The port-only constructor uses the special “any” address, and is useful for servers. The constructor that takes a string hostname attempts to resolve the name to an IP address; the static createUnresolved() method allows an instance to be created without attempting this resolution step. The isUnresolved() method returns TRUE if the instance was created this way, or if the resolution attempt in the constructor failed. The get...() methods provide access to the indicated components, with getHostName() providing the name associated with the contained InetAddress. The toString() method overrides that of Object and returns a string consisting of the name associated with the contained address (if known), a ‘/’ (slash), the address in numeric form, a ‘:’ (colon), and the port number. If the InetSocketAddress is unresolved, only the String with which it was created precedes the colon.

ServerSocket(int localPort)
ServerSocket(int localPort, int queueLimit)
ServerSocket(int localPort, int queueLimit, InetAddress localAddr)
ServerSocket()

A TCP endpoint must be associated with a specific port in order for clients to direct their connections to it. The first three constructors create a TCP endpoint that is associated with the specified local port and ready to accept incoming connections. Valid port numbers are in the range 0–65,535. (If the port specified is zero, an arbitrary unused port will be picked.) Optionally, the size of the connection queue and the local address can also be set. Note that the maximum queue size may not be a hard limit, and cannot be used to control client population. The local address, if specified, must be an address of one of this host’s network interfaces. If the address is not specified, the socket will accept connections to any of the host’s IP addresses. This may be useful for hosts with multiple interfaces where the server wants to accept connections on only one of its interfaces.

The fourth constructor creates a ServerSocket that is not associated with any local port; it must be bound to a port (see bind() below) before it can be used.

void bind(int port)
void bind(int port, int queuelimit)
Socket accept()
void close()

The bind() methods associate this socket with a local port. A ServerSocket can only be associated with one port. If this instance is already associated with another port, or if the specified port is already in use, an IOException is thrown.

accept() returns a connected Socket instance for the next new incoming connection to the server socket. If no established connection is waiting, accept() blocks until one is established or a timeout occurs.

The close() method closes the socket. After invoking this method, incoming client connection requests for this socket are rejected.

InetAddress getInetAddress()
SocketAddress getLocalSocketAddress()
int getLocalPort()

These return the local address/port of the server socket. Note that, unlike a Socket, a ServerSocket has no associated I/O Streams. It does, however, have other attributes called options, which can be controlled via various methods, as described in Section 4.4.

abstract void write(int data)
void write(byte[] data))
void write(byte[] data)
, int offset, int length)
void flush()
void close()

The write() methods transfer to the output stream a single byte, an entire array of bytes, and the bytes in an array beginning at offset and continuing for length bytes, respectively. The single-byte method writes the low-order eight bits of the integer argument. These operations, if called on a stream associated with a TCP socket, may block if a lot of data has been sent, but the other end of the connection has not called read() on the associated input stream recently. This can have undesirable consequences if some care is not used (see Section 6.2).

The flush() method pushes any buffered data out to the output stream. The close() method terminates the stream, after which further calls to write() will throw an exception.

abstract int read()
int read(byte[]data)
int read(byte[]data, int offset, int length)
int available()
void close()

The first three methods get transfer data from the stream. The first form places a single byte in the low-order eight bits of the returned int. The second form transfers up to data.length bytes from the input stream into data and returns the number of bytes transferred. The third form does the same, but places data in the array beginning at offset, and transfers only up to length bytes. If no data is available, but the end-of-stream has not been detected, all the read() methods block until at least one byte can be read. All methods return −1 if called when no data is available and end-of-stream has been detected.

The available() method returns the number of bytes available for reading at the time it was called. close() shuts down the stream, causing further attempts to read to throw an IOException.

DatagramPacket(byte[]data, int length)
DatagramPacket(byte[]data, int offset, int length)
DatagramPacket(byte[]data, int length, InetAddress remoteAddr, int remotePort)
DatagramPacket(byte[]data, int offset, int length, InetAddress remoteAddr, int remotePort)
DatagramPacket(byte[]data, int length, SocketAddress sockAddr)
DatagramPacket(byte[]data, int offset, int length, SocketAddress sockAddr)

These constructors create a datagram whose data portion is contained in the given byte array. The first two forms are typically used to construct DatagramPackets for receiving because the destination address is not specified (although it could be specified later with setAddress() and setPort(), or setSocketAddress()). The last four forms are typically used to construct DatagramPackets for sending.

Where offset is specified, the data portion of the datagram will be transferred to/from the byte array beginning at the specified position in the array. The length parameter specifies the number of bytes that will be transferred from the byte array when sending, or the maximum number to be transferred when receiving; it may be smaller, but not larger than data.length.

The destination address and port may be specified separately, or together in a SocketAddress.

InetAddress getAddress()
void setAddress(InetAddress address)
int getPort()
void setPort(int port)
SocketAddress getSocketAddress()
void setSocketAddress(SocketAddress sockAddr)

In addition to constructors, these methods supply an alternative way to access and modify the address of a DatagramPacket. Note that in addition, the receive() method of DatagramSocket sets the address and port to the datagram sender’s address and port.

int getLength()
void setLength(int length)
int getOffset()
byte[] getData()
void setData(byte[]data)
void setData(byte[]buffer, int offset, int length)

The first two methods return/set the internal length of the data portion of the datagram. The internal datagram length can be set explicitly either by the constructor or by the setLength() method. Attempting to make it larger than the length of the associated buffer results in an IllegalArgumentException. The receive() method of DatagramSocket uses the internal length in two ways: on input, it specifies the maximum number of bytes of a received message that will be copied into the buffer and on return, it indicates the number of bytes actually placed in the buffer.

getOffset() returns the location in the buffer of the first byte of data to be sent/received. There is no setOffset() method; however, it can be set with setData().

The getData() method returns the byte array associated with the datagram. The returned object is a reference to the byte array that was most recently associated with this DatagramPacket, either by the constructor or by setData(). The length of the returned buffer may be greater than the internal datagram length, so the internal length and offset values should be used to determine the actual received data.

The setData() methods make the given byte array the data portion of the datagram. The first form makes the entire byte array the buffer; the second form makes bytes offset through offset + length− 1 the buffer. The second form always updates the internal offset and length.

DatagramSocket()
DatagramSocket(int localPort)
DatagramSocket(int localPort, InetAddress localAddr)

These constructors create a UDP socket. Either or both of the local port and address may be specified. If the local port is not specified, or is specified as 0, the socket is bound to any available local port. If the local address is not specified, the packet can receive datagrams addressed to any of the local addresses.

void connect(InetAddress remoteAddr, int remotePort)
void connect(SocketAddress remoteSockAddr)
void disconnect()
void close()

The connect() methods set the remote address and port of the socket. Once connected, the socket can only communicate with the specified address and port; attempting to send a datagram with a different address and port will throw an exception. The socket will only receive datagrams that originated from the specified port and address; datagrams arriving from any other port or address are ignored. Caveat: A socket connected to a multicast or broadcast address can only send datagrams because a datagram source address is always a unicast address (see Section 4.3). Note that connecting is strictly a local operation because (unlike TCP) there is no end-to-end packet exchange involved. disconnect() unsets the remote address and port, if any. The close() method indicates that the socket is no longer in use; further attempts to send or receive throw an exception.

InetAddress getInetAddress()
int getPort()
SocketAddress getRemoteSocketAddress()
InetAddress getLocalAddress()
int getLocalPort()
SocketAddress getLocalSocketAddress()

The first method returns an InetAddress instance representing the address of the remote socket to which this socket is connected, or null if it is not connected. Similarly, getPort() returns the port number to which the socket is connected, or −1 if it is not connected. The third method returns both address and port conveniently encapsulated in an instance of SocketAddress, or null if unconnected.

The last three methods provide the same service for the local address and port. If the socket has not been bound to a local address, getLocalAddress() returns the wildcard (“any local address”) address. getLocalPort() always returns a local port number; if the socket was not been bound before the call, the call causes the socket to be bound to any available local port. The getLocalSocketAddress() returns null if the socket is not bound.

void send(DatagramPacket packet)
void receive(DatagramPacket packet)

The send() method sends the DatagramPacket. If connected, the packet is sent to the address to which the socket is connected, unless the DatagramPacket specifies a different destination, in which case an exception is thrown. Otherwise, the packet is sent to the destination indicated by the DatagramPacket. This method does not block.

The receive() method blocks until a datagram is received, and then copies its data into the given DatagramPacket. If the socket is connected, the method blocks until a datagram is received from the remote socket to which it is connected.

int getSoTimeout()
void setSoTimeout(int timeoutMillis)

These methods return and set, respectively, the maximum amount of time that a receive() call will block for this socket. If the timer expires before data is available, an InterruptedIOException is thrown. The timeout value is given in milliseconds.

Like Socket and ServerSocket, the DatagramSocket class has many other options. They are described more fully in Section 4.4.