package.html revision 3665
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest This code is free software; you can redistribute it and/or modify it
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest under the terms of the GNU General Public License version 2 only, as
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest published by the Free Software Foundation. Oracle designates this
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest particular file as subject to the "Classpath" exception as provided
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest by Oracle in the LICENSE file that accompanied this code.
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest This code is distributed in the hope that it will be useful, but WITHOUT
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest version 2 for more details (a copy is included in the LICENSE file that
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest accompanied this code).
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest You should have received a copy of the GNU General Public License version
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest 2 along with this work; if not, write to the Free Software Foundation,
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest or visit www.oracle.com if you need additional information or have any
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew ForrestProvides the classes for implementing networking applications.
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p> The java.net package can be roughly divided in two sections:</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li> <p><i>A Low Level API</i>, which deals with the following abstractions:</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><p><i>Addresses</i>, which are networking identifiers, like IP addresses.</p></li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><p><i>Sockets</i>, which are basic bidirectional data communication mechanisms.</p></li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><p><i>Interfaces</i>, which describe network interfaces. </p></li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li> <p><i>A High Level API</i>, which deals with the following abstractions:</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><p><i>URIs</i>, which represent Universal Resource Identifiers.</p></li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><p><i>URLs</i>, which represent Universal Resource Locators.</p></li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><p><i>Connections</i>, which represents connections to the resource pointed to by <i>URLs</i>.</p></li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>Addresses are used throughout the java.net APIs as either host identifiers, or socket endpoint identifiers.</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>The {@link java.net.InetAddress} class is the abstraction representing an IP (Internet Protocol) address. It has two subclasses:
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@link java.net.Inet4Address} for IPv4 addresses.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@link java.net.Inet6Address} for IPv6 addresses.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>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.</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>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.</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>Sockets are means to establish a communication link between machines over the network. The java.net package provides 4 kinds of Sockets:</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@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.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@link java.net.ServerSocket} is a TCP server API, and will typically {@linkplain java.net.ServerSocket#accept accept} connections from client sockets.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@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}.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@link java.net.MulticastSocket} is a subclass of {@code DatagramSocket} used when dealing with multicast groups.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>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.</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>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.</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>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:
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@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.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@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.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@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 ftp.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li>{@link java.net.HttpURLConnection} is a subclass of URLConnection and provides some additional functionalities specific to the HTTP protocol.</li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>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.<p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew ForrestURI uri = new URI("http://java.sun.com/");<br>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew ForrestInputStream in = url.openStream();
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew ForrestAs 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/</code>), a similar URL will try to instantiate the handler for the specified protocol; if it doesn't exist an exception will be thrown.</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>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</code> system property. For instance if it is set to <code>myapp.protocols</code>, then the URL code will try, in the case of http, first to load <code>myapp.protocols.http.Handler</code>, then, if this fails, <code>http.Handler</code> from the default location.<p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<p>Note that the Handler class <b>has to</b> be a subclass of the abstract class {@link java.net.URLStreamHandler}.</p>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><a href="doc-files/net-properties.html">Networking System Properties</a></li>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<h2>Package Specification</h2>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest<h2>Related Documentation</h2>
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew ForrestFor overviews, tutorials, examples, guides, and tool documentation, please see:
507f293cae556f4b7077d3bcfc882525da3cfe6bAndrew Forrest <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>