diff -r f2358d18923a -r 1d9cb0d080e3 jdk/src/share/classes/java/net/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/jdk/src/share/classes/java/net/package-info.java Tue Jul 30 11:04:19 2013 -0700 @@ -0,0 +1,161 @@ +/* + * 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:

+ * + *

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: + *

+ *

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:

+ * + *

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: + *

+ *

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;