OpenJDK 1.23 · java.net · APIdia, the JavaDoc alternative

Provides the classes for implementing networking applications.

The java.net package can be roughly divided in two sections:

A Low Level API, which deals with the following abstractions:
- Addresses, which are networking identifiers, like IP addresses.
- Sockets, which are basic bidirectional data communication mechanisms.
- Interfaces, which describe network interfaces.
A High Level API, which deals with the following abstractions:
- URIs, which represent Universal Resource Identifiers.
- URLs, which represent Universal Resource Locators.
- Connections, which represents connections to the resource pointed to by URLs.

Addresses

Addresses are used throughout the java.net APIs as either host identifiers, or socket endpoint identifiers.

The java.net.InetAddress class is the abstraction representing an IP (Internet Protocol) address. It has two subclasses:

java.net.Inet4Address for IPv4 addresses.
java.net.Inet6Address for IPv6 addresses.

But, in most cases, there is no need to deal directly with the subclasses, as the InetAddress abstraction should cover most of the needed functionality.

About IPv6

Not all systems have support for the IPv6 protocol, and while the Java networking stack will attempt to detect it and use it transparently when available, it is also possible to disable its use with a system property. In the case where IPv6 is not available, or explicitly disabled, Inet6Address are not valid arguments for most networking operations any more. While methods like java.net.InetAddress#getByName are guaranteed not to return an Inet6Address when looking up host names, it is possible, by passing literals, to create such an object. In which case, most methods, when called with an Inet6Address will throw an Exception.

Sockets

Sockets are means to establish a communication link between machines over the network. The java.net package provides 4 kinds of Sockets:

java.net.Socket is a TCP client API, and will typically be used to connect to a remote host.
java.net.ServerSocket is a TCP server API, and will typically accept connections from client sockets.
java.net.DatagramSocket is a UDP endpoint API and is used to send and receive datagram packets.
java.net.MulticastSocket is a subclass of DatagramSocket used when dealing with multicast groups.

Sending and receiving with TCP sockets is done through InputStreams and OutputStreams which can be obtained via the java.net.Socket#getInputStream and java.net.Socket#getOutputStream methods.

Interfaces

The java.net.NetworkInterface class provides APIs to browse and query all the networking interfaces (e.g. ethernet connection or PPP endpoint) of the local machine. It is through that class that you can check if any of the local interfaces is configured to support IPv6.

Note, all conforming implementations must support at least one NetworkInterface object, which must either be connected to a network, or be a "loopback" interface that can only communicate with entities on the same machine.

High level API

A number of classes in the java.net package do provide for a much higher level of abstraction and allow for easy access to resources on the network. The classes are:

java.net.URI is the class representing a Universal Resource Identifier, as specified in RFC 2396. As the name indicates, this is just an Identifier and doesn't provide directly the means to access the resource.
java.net.URL is the class representing a Universal Resource Locator, which is both an older concept for URIs and a means to access the resources.
java.net.URLConnection is created from a URL and is the communication link used to access the resource pointed by the URL. This abstract class will delegate most of the work to the underlying protocol handlers like http or https.
java.net.HttpURLConnection is a subclass of URLConnection and provides some additional functionalities specific to the HTTP protocol. This API has been superseded by the newer HTTP Client API.

The recommended usage is to use java.net.URI to identify resources, then convert it into a java.net.URL when it is time to access the resource. From that URL, you can either get the java.net.URLConnection for fine control, or get directly the InputStream.

Here is an example:

URI uri = new URI("http://www.example.com/");
URL url = uri.toURL();
InputStream in = url.openStream();

Protocol Handlers

As mentioned, URL and URLConnection rely on protocol handlers which must be present, otherwise an Exception is thrown. This is the major difference with URIs which only identify resources, and therefore don't need to have access to the protocol handler. So, while it is possible to create an URI with any kind of protocol scheme (e.g. myproto://myhost.mydomain/resource/), a similar URL will try to instantiate the handler for the specified protocol; if it doesn't exist an exception will be thrown.

By default the protocol handlers are loaded dynamically from the default location. It is, however, possible to deploy additional protocols handlers as services. Service providers of type java.net.spi.URLStreamHandlerProvider are located at runtime, as specified in the URL constructor.

Additional Specification

Networking System Properties

Modifier and Type	Interface and Description
public interface	ContentHandlerFactory This interface defines a factory for content handlers.
public interface	CookiePolicy CookiePolicy implementations decide which cookies should be accepted and which should be rejected.
public interface	CookieStore A CookieStore object represents a storage for cookie.
public interface	DatagramSocketImplFactory This interface defines a factory for datagram socket implementations.
public interface	FileNameMap A simple interface which provides a mechanism to map between a file name and a MIME type string.
pack-priv interface	InetAddressImpl
public interface	ProtocolFamily Represents a family of communication protocols.
public interface	SocketImplFactory This interface defines a factory for socket implementations.
public interface	SocketOption< The type of the socket option value. T> A socket option associated with a socket.
public interface	SocketOptions Interface of methods to get/set socket options.
pack-priv interface	SocksConsts Constants used by the SOCKS protocol implementation.
public interface	URLStreamHandlerFactory This interface defines a factory for `URL` stream protocol handlers.

Class Summary

Modifier and Type	Class and Description
public abstract class	Authenticator The class Authenticator represents an object that knows how to obtain authentication for a network connection.
public class	BindException Signals that an error occurred while attempting to bind a socket to a local address and port.
public abstract class	CacheRequest Represents channels for storing resources in the ResponseCache.
public abstract class	CacheResponse Represent channels for retrieving resources from the ResponseCache.
public class	ConnectException Signals that an error occurred while attempting to connect a socket to a remote address and port.
public abstract class	ContentHandler The abstract class `ContentHandler` is the superclass of all classes that read an `Object` from a `URLConnection`.
public abstract class	CookieHandler A CookieHandler object provides a callback mechanism to hook up a HTTP state management policy implementation into the HTTP protocol handler.
public class	CookieManager CookieManager provides a concrete implementation of `CookieHandler`, which separates the storage of cookies from the policy surrounding accepting and rejecting cookies.
public class	DatagramPacket This class represents a datagram packet.
public class	DatagramSocket This class represents a socket for sending and receiving datagram packets.
public abstract class	DatagramSocketImpl Abstract datagram and multicast socket implementation base class.
pack-priv class	DefaultInterface Choose a network interface to be the default for outgoing IPv6 traffic that does not specify a scope_id (and which needs one).
pack-priv class	DelegatingSocketImpl A SocketImpl that delegates all methods to another SocketImpl.
pack-priv class	FactoryURLClassLoader
pack-priv class	HostPortrange Parses a string containing a host/domain name and port range
pack-priv class	HttpConnectSocketImpl Basic SocketImpl that relies on the internal HTTP protocol handler implementation to perform the HTTP tunneling and authentication.
public class	HttpCookie An HttpCookie object represents an HTTP cookie, which carries state information between server and user agent.
public class	HttpRetryException Thrown to indicate that a HTTP request needs to be retried but cannot be retried automatically, due to streaming mode being enabled.
public abstract class	HttpURLConnection A URLConnection with support for HTTP-specific features.
public class	IDN Provides methods to convert internationalized domain names (IDNs) between a normal Unicode representation and an ASCII Compatible Encoding (ACE) representation.
public class	Inet4Address This class represents an Internet Protocol version 4 (IPv4) address.
pack-priv class	Inet4AddressImpl
public class	Inet6Address This class represents an Internet Protocol version 6 (IPv6) address.
pack-priv class	Inet6AddressImpl
public class	InetAddress This class represents an Internet Protocol (IP) address.
public class	InetSocketAddress This class implements an IP Socket Address (IP address + port number) It can also be a pair (hostname + port number), in which case an attempt will be made to resolve the hostname.
pack-priv class	InMemoryCookieStore A simple in-memory java.net.CookieStore implementation
public class	InterfaceAddress This class represents a Network Interface address.
public abstract class	JarURLConnection A URL Connection to a Java ARchive (JAR) file or an entry in a JAR file.
public class	MalformedURLException Thrown to indicate that a malformed URL has occurred.
public class	MulticastSocket A `MulticastSocket` is a datagram socket that is convenient for sending and receiving IP multicast datagrams.
pack-priv class	NetMulticastSocket A multicast datagram socket that delegates socket operations to a `DatagramSocketImpl`.
public class	NetPermission This class is for various network permissions.
public class	NetworkInterface This class represents a Network Interface made up of a name, and a list of IP addresses assigned to this interface.
public class	NoRouteToHostException Signals that an error occurred while attempting to connect a socket to a remote address and port.
public class	PasswordAuthentication The class PasswordAuthentication is a data holder that is used by Authenticator.
public class	PortUnreachableException Signals that an ICMP Port Unreachable message has been received on a connected datagram.
public class	ProtocolException Thrown to indicate that there is an error in the underlying protocol, such as a TCP error.
public class	Proxy This class represents a proxy setting, typically a type (http, socks) and a socket address.
public abstract class	ProxySelector Selects the proxy server to use, if any, when connecting to the network resource referenced by a URL.
public abstract class	ResponseCache Represents implementations of URLConnection caches.
public abstract class	SecureCacheResponse Represents a cache response originally retrieved through secure means, such as TLS.
public class	ServerSocket This class implements server sockets.
public class	Socket This class implements client sockets (also called just "sockets").
public abstract class	SocketAddress This class represents a Socket Address with no protocol attachment.
public class	SocketException Thrown to indicate that there is an error creating or accessing a Socket.
public abstract class	SocketImpl The abstract class `SocketImpl` is a common superclass of all classes that actually implement sockets.
public class	SocketPermission This class represents access to a network via sockets.
pack-priv class	SocketPermissionCollection if (init'd with IP, key is IP as string) if wildcard, its the wild card else its the cname?
public class	SocketTimeoutException Signals that a timeout has occurred on a socket read or accept.
pack-priv class	SocksSocketImpl SOCKS (V4 & V5) TCP socket implementation (RFC 1928).
public class	StandardSocketOptions Defines the standard socket options.
public class	UnixDomainSocketAddress A Unix domain socket address.
pack-priv class	UnknownContentHandler
public class	UnknownHostException Thrown to indicate that the IP address of a host could not be determined.
public class	UnknownServiceException Thrown to indicate that an unknown service exception has occurred.
public class	URI Represents a Uniform Resource Identifier (URI) reference.
public class	URISyntaxException Checked exception thrown to indicate that a string could not be parsed as a URI reference.
public class	URL Class `URL` represents a Uniform Resource Locator, a pointer to a "resource" on the World Wide Web.
public class	URLClassLoader This class loader is used to load classes and resources from a search path of URLs referring to both JAR files and directories.
public abstract class	URLConnection The abstract class `URLConnection` is the superclass of all classes that represent a communications link between the application and a URL.
public class	URLDecoder Utility class for HTML form decoding.
pack-priv class	UrlDeserializedState
public class	URLEncoder Utility class for HTML form encoding.
public class	URLPermission Represents permission to access a resource or set of resources defined by a given url, and for a given set of user-settable request methods and request headers.
public abstract class	URLStreamHandler The abstract class `URLStreamHandler` is the common superclass for all stream protocol handlers.

Package java.net