1 /* 2 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 * Provides the classes for implementing networking applications. 28 * 29 * <p> The java.net package can be roughly divided in two sections:</p> 30 * <ul> 31 * <li><p><i>A Low Level API</i>, which deals with the 32 * following abstractions:</p> 33 * <ul> 34 * <li><p><i>Addresses</i>, which are networking identifiers, 35 * like IP addresses.</p></li> 36 * <li><p><i>Sockets</i>, which are basic bidirectional data communication 37 * mechanisms.</p></li> 38 * <li><p><i>Interfaces</i>, which describe network interfaces. </p></li> 39 * </ul></li> 40 * <li> <p><i>A High Level API</i>, which deals with the following 41 * abstractions:</p> 42 * <ul> 43 * <li><p><i>URIs</i>, which represent 44 * Universal Resource Identifiers.</p></li> 45 * <li><p><i>URLs</i>, which represent 46 * Universal Resource Locators.</p></li> 47 * <li><p><i>Connections</i>, which represents connections to the resource 48 * pointed to by <i>URLs</i>.</p></li> 49 * </ul></li> 50 * </ul> 51 * <h2>Addresses</h2> 52 * <p>Addresses are used throughout the java.net APIs as either host 53 * identifiers, or socket endpoint identifiers.</p> 54 * <p>The {@link java.net.InetAddress} class is the abstraction representing an 55 * IP (Internet Protocol) address. It has two subclasses: 56 * <ul> 57 * <li>{@link java.net.Inet4Address} for IPv4 addresses.</li> 58 * <li>{@link java.net.Inet6Address} for IPv6 addresses.</li> 59 * </ul> 60 * <p>But, in most cases, there is no need to deal directly with the subclasses, 61 * as the InetAddress abstraction should cover most of the needed 62 * functionality.</p> 63 * <h3><b>About IPv6</b></h3> 64 * <p>Not all systems have support for the IPv6 protocol, and while the Java 65 * networking stack will attempt to detect it and use it transparently when 66 * available, it is also possible to disable its use with a system property. 67 * In the case where IPv6 is not available, or explicitly disabled, 68 * Inet6Address are not valid arguments for most networking operations any 69 * more. While methods like {@link java.net.InetAddress#getByName} are 70 * guaranteed not to return an Inet6Address when looking up host names, it 71 * is possible, by passing literals, to create such an object. In which 72 * case, most methods, when called with an Inet6Address will throw an 73 * Exception.</p> 74 * <h2>Sockets</h2> 75 * <p>Sockets are means to establish a communication link between machines over 76 * the network. The java.net package provides 4 kinds of Sockets:</p> 77 * <ul> 78 * <li>{@link java.net.Socket} is a TCP client API, and will typically 79 * be used to {@linkplain java.net.Socket#connect(SocketAddress) 80 * connect} to a remote host.</li> 81 * <li>{@link java.net.ServerSocket} is a TCP server API, and will 82 * typically {@linkplain java.net.ServerSocket#accept accept} 83 * connections from client sockets.</li> 84 * <li>{@link java.net.DatagramSocket} is a UDP endpoint API and is used 85 * to {@linkplain java.net.DatagramSocket#send send} and 86 * {@linkplain java.net.DatagramSocket#receive receive} 87 * {@linkplain java.net.DatagramPacket datagram packets}.</li> 88 * <li>{@link java.net.MulticastSocket} is a subclass of 89 * {@code DatagramSocket} used when dealing with multicast 90 * groups.</li> 91 * </ul> 92 * <p>Sending and receiving with TCP sockets is done through InputStreams and 93 * OutputStreams which can be obtained via the 94 * {@link java.net.Socket#getInputStream} and 95 * {@link java.net.Socket#getOutputStream} methods.</p> 96 * <h2>Interfaces</h2> 97 * <p>The {@link java.net.NetworkInterface} class provides APIs to browse and 98 * query all the networking interfaces (e.g. ethernet connection or PPP 99 * endpoint) of the local machine. It is through that class that you can 100 * check if any of the local interfaces is configured to support IPv6.</p> 101 * <p>Note, all conforming implementations must support at least one 102 * {@code NetworkInterface} object, which must either be connected to a 103 * network, or be a "loopback" interface that can only communicate with 104 * entities on the same machine.</p> 105 * 106 * <h2>High level API</h2> 107 * <p>A number of classes in the java.net package do provide for a much higher 108 * level of abstraction and allow for easy access to resources on the 109 * network. The classes are: 110 * <ul> 111 * <li>{@link java.net.URI} is the class representing a 112 * Universal Resource Identifier, as specified in RFC 2396. 113 * As the name indicates, this is just an Identifier and doesn't 114 * provide directly the means to access the resource.</li> 115 * <li>{@link java.net.URL} is the class representing a 116 * Universal Resource Locator, which is both an older concept for 117 * URIs and a means to access the resources.</li> 118 * <li>{@link java.net.URLConnection} is created from a URL and is the 119 * communication link used to access the resource pointed by the 120 * URL. This abstract class will delegate most of the work to the 121 * underlying protocol handlers like http or https.</li> 122 * <li>{@link java.net.HttpURLConnection} is a subclass of URLConnection 123 * and provides some additional functionalities specific to the 124 * HTTP protocol.</li> 125 * </ul> 126 * <p>The recommended usage is to use {@link java.net.URI} to identify 127 * resources, then convert it into a {@link java.net.URL} when it is time to 128 * access the resource. From that URL, you can either get the 129 * {@link java.net.URLConnection} for fine control, or get directly the 130 * InputStream. 131 * <p>Here is an example:</p> 132 * <pre> 133 * URI uri = new URI("http://java.sun.com/"); 134 * URL url = uri.toURL(); 135 * InputStream in = url.openStream(); 136 * </pre> 137 * <h2>Protocol Handlers</h2> 138 * As mentioned, URL and URLConnection rely on protocol handlers which must be 139 * present, otherwise an Exception is thrown. This is the major difference with 140 * URIs which only identify resources, and therefore don't need to have access 141 * to the protocol handler. So, while it is possible to create an URI with any 142 * kind of protocol scheme (e.g. {@code myproto://myhost.mydomain/resource/}), 143 * a similar URL will try to instantiate the handler for the specified protocol; 144 * if it doesn't exist an exception will be thrown. 145 * <p>By default the protocol handlers are loaded dynamically from the default 146 * location. It is, however, possible to add to the search path by setting 147 * the {@code java.protocol.handler.pkgs} system property. For instance if 148 * it is set to {@code myapp.protocols}, then the URL code will try, in the 149 * case of http, first to load {@code myapp.protocols.http.Handler}, then, 150 * if this fails, {@code http.Handler} from the default location. 151 * <p>Note that the Handler class <b>has to</b> be a subclass of the abstract 152 * class {@link java.net.URLStreamHandler}.</p> 153 * <h2>Additional Specification</h2> 154 * <ul> 155 * <li><a href="doc-files/net-properties.html"> 156 * Networking System Properties</a></li> 157 * </ul> 158 * 159 * @since JDK1.0 160 */ 161 package java.net; 162
