|
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.<p> |
|
131 * <p>Here is an example:</p> |
|
132 * <p><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.<p> |
|
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; |