src.java.net.package-info Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* 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 {@link java.net.InetAddress} class is the abstraction representing an
* IP (Internet Protocol) address. It has two subclasses:
*
* - {@link java.net.Inet4Address} for IPv4 addresses.
* - {@link 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 {@link 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:
*
* - {@link java.net.Socket} is a TCP client API, and will typically
* be used to {@linkplain java.net.Socket#connect(SocketAddress)
* connect} to a remote host.
* - {@link java.net.ServerSocket} is a TCP server API, and will
* typically {@linkplain java.net.ServerSocket#accept accept}
* connections from client sockets.
* - {@link java.net.DatagramSocket} is a UDP endpoint API and is used
* to {@linkplain java.net.DatagramSocket#send send} and
* {@linkplain java.net.DatagramSocket#receive receive}
* {@linkplain java.net.DatagramPacket datagram packets}.
* - {@link java.net.MulticastSocket} is a subclass of
* {@code 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
* {@link java.net.Socket#getInputStream} and
* {@link java.net.Socket#getOutputStream} methods.
* Interfaces
* The {@link 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
* {@code 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:
*
* - {@link 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.
* - {@link 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.
* - {@link 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.
* - {@link java.net.HttpURLConnection} is a subclass of URLConnection
* and provides some additional functionalities specific to the
* HTTP protocol.
*
* The recommended usage is to use {@link java.net.URI} to identify
* resources, then convert it into a {@link java.net.URL} when it is time to
* access the resource. From that URL, you can either get the
* {@link java.net.URLConnection} for fine control, or get directly the
* InputStream.
*
Here is an example:
*
* URI uri = new URI("http://java.sun.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. {@code 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 add to the search path by setting
* the {@code java.protocol.handler.pkgs} system property. For instance if
* it is set to {@code myapp.protocols}, then the URL code will try, in the
* case of http, first to load {@code myapp.protocols.http.Handler}, then,
* if this fails, {@code http.Handler} from the default location.
*
Note that the Handler class has to be a subclass of the abstract
* class {@link java.net.URLStreamHandler}.
* Additional Specification
*
*
* @since JDK1.0
*/
package java.net;