Generated by
JDiff

java.net Documentation Differences

This file contains all the changes in documentation in the package java.net as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class DatagramPacket

This class represents a datagram packet.

Datagram packets are used to implement a connectionless packet delivery service. Each message is routed from one machine to another based solely on information contained within that packet. Multiple packets sent from one machine to another might be routed differently and might arrive in any order. Packet delivery is not guaranteed. @author Pavani Diwanji @author Benjamin Renaud @version 1.40 1241 04/0308/0102 @since JDK1.0

Class DatagramPacket, constructor DatagramPacket(byte[], int, SocketAddress)

Constructs a datagram packet for sending packets of length length to the specified port number on the specified host. The length argument must be less than or equal to buf.length. @param buf the packet data. @param length the packet length. @param address the destination address. @throws SocketExceptionIllegalArgumentException if address type is not supported @since 1.4 @see java.net.InetAddress
Class DatagramPacket, constructor DatagramPacket(byte[], int, int, SocketAddress)

Constructs a datagram packet for sending packets of length length with offset ioffsetto the specified port number on the specified host. The length argument must be less than or equal to buf.length. @param buf the packet data. @param offset the packet data offset. @param length the packet data length. @param address the destination socket address. @throws SocketExceptionIllegalArgumentException if address type is not supported @see java.net.InetAddress @since 1.4

Class DatagramSocket

This class represents a socket for sending and receiving datagram packets.

A datagram socket is the sending or receiving point for a packet delivery service. Each packet sent or received on a datagram socket is individually addressed and routed. Multiple packets sent from one machine to another may be routed differently and may arrive in any order.

UDP broadcasts sends are always enabled on a DatagramSocket. In order to receive broadcast packets a DatagramSocket should be bound to the wildcard address. In some implementations broadcast packets may also be received when a DatagramSocket is bound to a more specific address.

Example: DatagramSocket s = new DatagramSocket(null); s.bind(new InetSocketAddress(8888)); Which is equivalent to: DatagramSocket s = new DatagramSocket(8888); Both cases will create a DatagramSocket able to receive broadcasts on UDP port 8888. @author Pavani Diwanji @version 1.84 1287 04/0309/0102 @see java.net.DatagramPacket @see java.nio.channels.DatagramChannel @since JDK1.0

Class DatagramSocket, SocketAddress getRemoteSocketAddress()

Returns the address of the endpoint this socket is connected to or null if it is unconnected. @return a SocketAddress reprensenting the remote endpoint of this socket or null if it is not connected yet. @see #getInetAddress() @see #getPort() @see #connect(SocketAddress int) @see #connect(SocketAddress) @since 1.4

Class DatagramSocketImplFactory, DatagramSocketImpl createDatagramSocketImpl()

Creates a new DatagramSocketImpl instance. @return a new instance of DatagramSocketImpl. @see java.ionet.DatagramSocketImpl

Class HttpURLConnection, int getResponseCode()

Gets the status code from an HTTP response statusmessage. fromFor example in the case of the following responses likestatus lines:
 HTTP/1.0 200 OK HTTP/1.0 401 Unauthorized 
ExtractsIt the intswill return 200 and 401 respectively. Returns -1 if noneno code can be discerned from the response (i.e. the response is not valid HTTP). @throws IOException if an error occurred connecting to the server. @return the HTTP Status-Code or -1

Class InetAddress

This class represents an Internet Protocol (IP) address.

An IP address is either a 32-bit or 128-bit unsigned number used by IP a lower-level protocol on which protocols like UDP and TCP are built. The IP address architecture is defined by RFC 790: Assigned Numbers RFC 1918: Address Allocation for Private Internets RFC 2365: Administratively Scoped IP Multicast and RFC 2373: IP Version 6 Addressing Architecture. An instance of an InetAddress consists of an IP address and possibly its corresponding host name (depending on whether it is constructed with a host name or whether it has already done reverse host name resolution).

Address types

unicast An identifier for a single interface. A packet sent to a unicast address is delivered to the interface identified by that address.

The Unspecified Address -- Also called anylocal or wildcard address. It must never be assigned to any node. It indicates the absence of an address. One example of its use is as the target of bind which allows a server to accept a client connection on any interface in case the server host has multiple interfaces.

The unspecified address must not be used as the destination address of an IP packet.

The Loopback Addresses -- This is the address assigned to the loopback interface. Anything sent to this IP address loops around and becomes IP input on the local host. This address is often used when testing a client.

multicast An identifier for a set of interfaces (typically belonging to different nodes). A packet sent to a multicast address is delivered to all interfaces identified by that address.

IP address scope

Link-local addresses are designed to be used for addressing on a single link for purposes such as auto-address configuration neighbor discovery or when no routers are present.

Site-local addresses are designed to be used for addressing inside of a site without the need for a global prefix.

Global addresses are unique across the internet.

Textual representation of IP addresses

The textual representation of an IP address is address family specific.

For IPv4 address format please refer to Inet4Address#format; For IPv6 address format please refer to Inet6Address#format.

Host Name Resolution

Host name-to-IP address resolution is accomplished through the use of a combination of local machine configuration information and network naming services such as the Domain Name System (DNS) and Network Information Service(NIS). The particular naming services(s) being used is by default the local machine configured one. For any host name its corresponding IP address is returned.

Reverse name resolution means that for any IP address the host associated with the IP address is returned.

The InetAddress class provides methods to resolve host names to their IP addresses and vise versa.

InetAddress Caching

The InetAddress class has a cache to store successful as well as unsuccessful host name resolutions. The positive caching is there to guard against DNS spoofing attacks; while the negative caching is used to improve performance.

By default the result of positive host name resolutions are cached forever because there is no general rule to decide when it is safe to remove cache entries. The result of unsuccessful host name resolution is cached for a very short period of time (10 seconds) to improve performance.

Under certain circumstances where it can be determined that DNS spoofing attacks are not possible a Java security property can be set to a different Time-to-live (TTL) value for positive caching. Likewise a system admin can configure a different negative caching TTL value when needed.

Two Java security properties control the TTL values used for positive and negative host name resolution caching:

networkaddress.cache.ttl (default: -1)
Indicates the caching policy for successful name lookups from the name service. The value is specified as as integer to indicate the number of seconds to cache the successful lookup.

A value of -1 indicates "cache forever".

networkaddress.cache.negative.ttl (default: 10)
Indicates the caching policy for un-successful name lookups from the name service. The value is specified as as integer to indicate the number of seconds to cache the failure for un-successful lookups.

A value of 0 indicates "never cache". A value of -1 indicates "cache forever".

@author Chris Warth @version 1.9195 12/03/0114/02 @see java.net.InetAddress#getByAddress(byte[]) @see java.net.InetAddress#getByAddress(java.lang.String byte[]) @see java.net.InetAddress#getAllByName(java.lang.String) @see java.net.InetAddress#getByName(java.lang.String) @see java.net.InetAddress#getLocalHost() @since JDK1.0

Class InetSocketAddress, constructor InetSocketAddress(String, int)

Creates a socket address from a hostname and a port number.

An attempt will be made to resolve the hostname into an InetAddress. If that attempt fails the address will be flagged as unresolved.

A valid port value is between 0 and 65535. A port number of zero will let the system pick up an ephemeral port in a bind operation.

@param hostname the Host name @param port The port number @throws IllegalArgumentException if the port parameter is outside the range of valid port values or if the hostname parameter is null. @see #isUnresolved()

Class InetSocketAddress, boolean equals(Object)

Compares this object against the specified object. The result is true if and only if the argument is not null and it represents the same address as this object.

Two instances of InetSocketAddress represent the same address if both the InetAddresses (or hostnames if it is unresolved) and port numbers are equal. If both addresses are unresolved then the hostname & the port number are compared. @param obj the object to compare against. @return true if the objects are the same; false otherwise. @see java.net.InetAddress#equals(java.lang.Object)


Class MulticastSocket, NetworkInterface getNetworkInterface()

Get the multicast network interface set. @exception SocketException if there is an error in the underlying protocol such as a TCP error. @return the multicast NetworkInterface currently set @see #setNetworkInterface(NetworkInterface) @since 1.4
Class MulticastSocket, void joinGroup(SocketAddress, NetworkInterface)

Joins the specified multicast group at the specified interface.

If there is a security manager this method first calls its checkMulticast method with the mcastaddr argument as its argument. @param mcastaddr is the multicast address to join @param netIf specifies the local interface to receive multicast datagram packets or null to defer to the interface set by MulticastSocket#setInterface(InetAddress) or MulticastSocket#setNetworkInterface(NetworkInterface) @exception IOException if there is an error joining or when the address is not a multicast address. @exception SecurityException if a security manager exists and its checkMulticast method doesn't allow the join. @throws IllegalArgumentException if mcastaddr is null or is a SocketAddress subclass not supported by this socket @see SecurityManager#checkMulticast(InetAddress) @since 1.4

Class MulticastSocket, void leaveGroup(SocketAddress, NetworkInterface)

Leave a multicast group on a specified local interface.

If there is a security manager this method first calls its checkMulticast method with the mcastaddr argument as its argument. @param mcastaddr is the multicast address to leave @param netIf specifies the local interface or null to defer to the interface set by MulticastSocket#setInterface(InetAddress) or MulticastSocket#setNetworkInterface(NetworkInterface) @exception IOException if there is an error leaving or when the address is not a multicast address. @exception SecurityException if a security manager exists and its checkMulticast method doesn't allow the operation. @throws IllegalArgumentException if mcastaddr is null or is a SocketAddress subclass not supported by this socket @see SecurityManager#checkMulticast(InetAddress) @since 1.4


Class NetPermission

This class is for various network permissions. A NetPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

The target name is the name of the network permission (see below). The naming convention follows the hierarchical property naming convention. Also an asterisk may appear at the end of the name following a "." or by itself to signify a wildcard match. For example: "foo.*" or "*" is valid "*foo" or "a*b" is not valid.

The following table lists all the possible NetPermission target names and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

Permission Target Name What the Permission Allows Risks of Allowing this Permission
setDefaultAuthenticator The ability to set the way authentication information is retrieved when a proxy or HTTP server asks for authentication Malicious code can set an authenticator that monitors and steals user authentication input as it retrieves the input from the user.
requestPasswordAuthentication The ability to ask the authenticator registered with the system for a password Malicious code may steal this password.
specifyStreamHandler The ability to specify a stream handler when constructing a URL Malicious code may create a URL with resources that it would normally not have access to (like file:/foo/fum/) specifying a stream handler that gets the actual bytes from someplace it does have access to. Thus it might be able to trick the system into creating a ProtectionDomain/CodeSource for a class even though that class really didn't come from that location.
@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.40 0141 02/1202/0301 @author Marianne Mueller @author Roland Schemers

Class NetPermission, constructor NetPermission(String, String)

Creates a new NetPermission object with the specified name. The name is the symbolic name of the NetPermission and the actions String is currently unused and should be null. This constructor exists for use by the Policy object to instantiate new Permission objects. @param name the name of the NetPermission. @param actions should be null.

Class NetworkInterface, NetworkInterface getByInetAddress(InetAddress)

Convenience method to getsearch for a network interface giventhat has the specified Internet itsProtocol (IP) address. @parambound addrto anit. InetAddress

If the interfacespecified IP address is bound to multiple network interfaces it is not defined which network interface is returned. @param addr The InetAddress to search with. @return theA NetworkInterface or null if there is no obtainednetwork interface fromwith the itsspecified IP address. @exceptionthrows SocketException ifIf an I/O error occurs. @throws NullPointerException If the specified address is null.

Class NetworkInterface, NetworkInterface getByName(String)

Get aSearches for the network interface knowingwith the itsspecified name. @param name s String representingThe the name of the network interface. @return theA NetworkInterface with the specified name or null if obtained from itsthere is no network interface with the specified name. @exceptionthrows SocketException ifIf an I/O error occurs. @throws NullPointerException If the specified name is null.

Class ServerSocket

This class implements server sockets. A server socket waits for requests to come in over the network. It performs some operation based on that request and then possibly returns a result to the requester.

The actual work of the server socket is performed by an instance of the SocketImpl class. An application can change the socket factory that creates the socket implementation to configure itself to create sockets appropriate to the local firewall. @author unascribed @version 1.69 1273 04/0312/0102 @see java.net.SocketImpl @see java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory) @see java.nio.channels.ServerSocketChannel @since JDK1.0

Class ServerSocket, constructor ServerSocket(int)

Creates a server socket onbound ato the specified port. A port of 0 creates a socket on any free port.

The maximum queue length for incoming connection indications (a request to connect) is set to 50. If a connection indication arrives when the queue is full the connection is refused.

If the application has specified a server socket factory that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

If there is a security manager its checkListen method is called with the port argument as its argument to ensure the operation is allowed. This could result in a SecurityException. @param port the port number or 0 to use any free port. @exception IOException if an I/O error occurs when opening the socket. @exception SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @see java.net.SocketImpl @see java.net.SocketImplFactory#createSocketImpl() @see java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory) @see SecurityManager#checkListen

Class ServerSocket, InetAddress getInetAddress()

Returns the local address of this server socket. @return the address to which this socket is connectedbound or null if the socket is not yet connectedunbound.

Class Socket

This class implements client sockets (also called just "sockets"). A socket is an endpoint for communication between two machines.

The actual work of the socket is performed by an instance of the SocketImpl class. An application by changing the socket factory that creates the socket implementation can configure itself to create sockets appropriate to the local firewall. @author unascribed @version 1.90 1293 04/0323/0102 @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory) @see java.net.SocketImpl @see java.nio.channels.SocketChannel @since JDK1.0

Class Socket, InputStream getInputStream()

Returns an input stream for this socket.

If this socket has an associated channel then the resulting input stream delegates all of its operations to the channel. If the channel is in non-blocking mode then the input stream's read operations will throw an java.nio.channels.IllegalBlockingModeException

Under abnormal conditions the underlying connection may be broken by the remote host or the network software (for example a connection reset in the case of TCP connections). When a broken connection is detected by the network software the following applies to the returned input stream :-

@return an input stream for reading bytes from this socket. @exception IOException if an I/O error occurs when creating the input stream or ifthe socket is closed the socket is not connected. or the socket input has been shutdown using #shutdownInput() @revised 1.4 @spec JSR-51
Class Socket, SocketAddress getRemoteSocketAddress()

Returns the address of the endpoint this socket is connected to or null if it is unconnected. @return a SocketAddress reprensenting the remote endpoint of this socket or null if it is not connected yet. @see #getInetAddress() @see #getPort() @see #connect(SocketAddress int) @see #connect(SocketAddress) @since 1.4

Class SocketOptions

Interface of methods to get/set socket options. This interface is implemented by: SocketImpl and DatagramSocketImpl. Subclasses of these should override the methods of this interface in order to support their own options.

The methods and constants which specify options in this interface are for implementation only. If you're not subclassing SocketImpl or DatagramSocketImpl you won't use these directly. There are type-safe methods to get/set each of these options in Socket ServerSocket DatagramSocket and MulticastSocket.

@version 1.28 1229 02/0322/0102 @author David Brown

Class SocketOptions, int IP_MULTICAST_IF

Set which outgoing interface on which to send multicast packets. Useful on hosts with multiple network interfaces where applications want to use other than the system default. Takes/returns an InetAddress.

Valid for Multicast: DatagramSocketImpl

@see MulticastSocket#setInterface(InetAddress) @see MulitcastSocket#getInterface()

Class SocketOptions, int IP_MULTICAST_IF2

Same as above. This option is introduced so that the behaviour with IP_MULTICAST_IF will be kept the same as before while this new option can support setting outgoing interfaces with either IPv4 and IPv6 addresses. NOTE: make sure there is no conflict with this @see MulticastSocket#setNetworkInterface(NetworkInterface) @see MulticastSocket#getNetworkInterface() @since 1.4

Class URI

Represents a Uniform Resource Identifier (URI) reference.

An instance of this class represents a URI reference as defined by RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax amended by RFC 2732: Format for Literal IPv6 Addresses in URLs and with the minor deviations noted below. This class provides constructors for creating URI instances from their components or by parsing their string forms methods for accessing the various components of an instance and methods for normalizing resolving and relativizing URI instances. Instances of this class are immutable.

URI syntax and components

At the highest level a URI reference (hereinafter simply "URI") in string form has the syntax
[scheme:]scheme-specific-part[#fragment]
where square brackets [...] delineate optional components and the characters : and # stand for themselves.

An absolute URI specifies a scheme; a URI that is not absolute is said to be relative. URIs are also classified according to whether they are opaque or hierarchical.

An opaque URI is an absolute URI whose scheme-specific part does not begin with a slash character ('/'). Opaque URIs are not subject to further parsing. Some examples of opaque URIs are:

mailto:java-net@java.sun.com
news:comp.lang.java
urn:isbn:096139210x

A hierarchical URI is either an absolute URI whose scheme-specific part begins with a slash character or a relative URI that is a URI that does not specify a scheme. Some examples of hierarchical URIs are:

http://java.sun.com/j2se/1.3/
docs/guide/collections/designfaq.html#28
../../../demo/jfc/SwingSet2/src/SwingSet2.java
file:///~/calendar

A hierarchical URI is subject to further parsing according to the syntax

[scheme:][//authority][path][ query][#fragment]
where the characters : / and # stand for themselves. The scheme-specific part of a hierarchical URI consists of the characters between the scheme and fragment components.

The authority component of a hierarchical URI is if specified either server-based or registry-based. A server-based authority parses according to the familiar syntax

[user-info@]host[:port]
where the characters @ and : stand for themselves. Nearly all URI schemes currently in use are server-based. An authority component that does not parse in this way is considered to be registry-based.

The path component of a hierarchical URI is itself said to be absolute if it begins with a slash character ('/'); otherwise it is relative. The path of a hierarchical URI that is either absolute or specifies an authority is always absolute.

All told then a URI instance has the following nine components:

ComponentType
schemeString
scheme-specific-part    String
authorityString
user-infoString
hostString
portint
pathString
queryString
fragmentString
In a given instance any particular component is either undefined or defined with a distinct value. Undefined string components are represented by null while undefined integer components are represented by -1. A string component may be defined to have the empty string as its value; this is not equivalent to that component being undefined.

Whether a particular component is or is not defined in an instance depends upon the type of the URI being represented. An absolute URI has a scheme component. An opaque URI has a scheme a scheme-specific part and possibly a fragment but has no other components. A hierarchical URI always has a path (though it may be empty) and a scheme-specific-part (which at least contains the path) and may have any of the other components. If the authority component is present and is server-based then the host component will be defined and the user-information and port components may be defined.

Operations on URI instances

The key operations supported by this class are those of normalization resolution and relativization.

Normalization is the process of removing unnecessary "." and ".." segments from the path component of a hierarchical URI. Each "." segment is simply removed. A ".." segment is removed only if it is preceded by a non-".." segment. Normalization has no effect upon opaque URIs.

Resolution is the process of resolving one URI against another base URI. The resulting URI is constructed from components of both URIs in the manner specified by RFC 2396 taking components from the base URI for those not specified in the original. For hierarchical URIs the path of the original is resolved against the path of the base and then normalized. The result for example of resolving

docs/guide/collections/designfaq.html#28          (1)
against the base URI http://java.sun.com/j2se/1.3/ is the result URI
http://java.sun.com/j2se/1.3/docs/guide/collections/designfaq.html#28
Resolving the relative URI
../../../demo/jfc/SwingSet2/src/SwingSet2.java    (2)
against this result yields in turn
http://java.sun.com/j2se/1.3/demo/jfc/SwingSet2/src/SwingSet2.java
Resolution of both absolute and relative URIs and of both absolute and relative paths in the case of hierarchical URIs is supported. Resolving the URI file:///~calendar against any other URI simply yields the original URI since it is absolute. Resolving the relative URI (2) above against the relative base URI (1) yields the normalized but still relative URI
demo/jfc/SwingSet2/src/SwingSet2.java

Relativization finally is the inverse of resolution: For any two normalized URIs u and v

u.relativize(u.resolve(v)).equals(v)  and
u.resolve(u.relativize(v)).equals(v)  .
This operation is often useful when constructing a document containing URIs that must be made relative to the base URI of the document wherever possible. For example relativizing the URI
http://java.sun.com/j2se/1.3/docs/guide/index.html
against the base URI
http://java.sun.com/j2se/1.3
yields the relative URI docs/guide/index.html.

Character categories

RFC 2396 specifies precisely which characters are permitted in the various components of a URI reference. The following categories most of which are taken from that specification are used below to describe these constraints:
alpha The US-ASCII alphabetic characters 'A' through 'Z' and 'a' through 'z'
digit The US-ASCII decimal digit characters '0' through '9'
alphanum All alpha and digit characters
unreserved     All alphanum characters together with those in the string "_- .~'()*"
punct The characters in the string " ;:$&+="
reserved All punct characters together with those in the string " /[]@"
escaped Escaped octets that is triplets consisting of the percent character ('%') followed by two hexadecimal digits ('0'-'9' 'A'-'F' and 'a'-'f')
other The Unicode characters that are not in the US-ASCII character set are not control characters (according to the Character.isISOControl method) and are not space characters (according to the Character.isSpaceChar method)  (Deviation from RFC 2396 which is limited to US-ASCII)

The set of all legal URI characters consists of the unreserved reserved escaped and other characters.

Escaped octets quotation encoding and decoding

RFC 2396 allows escaped octets to appear in the user-info path query and fragment components. Escaping serves two purposes in URIs:
  • To encode non-US-ASCII characters when a URI is required to conform strictly to RFC 2396 by not containing any other characters.

  • To quote characters that are otherwise illegal in a component. The user-info path query and fragment components differ slightly in terms of which characters are considered legal and illegal.

These purposes are served in this class by three related operations:
These operations are exposed in the constructors and methods of this class as follows:

Identities

For any URI u it is always the case that
new URI(u.toString()).equals(u) .
For any URI u that does not contain redundant syntax such as two slashes before an empty authority (as in file:///tmp/ ) or a colon following a host name but no port (as in http://java.sun.com: ) and that does not encode characters except those that must be quoted the following identities also hold:
new URI(u.getScheme()
        
u.getSchemeSpecificPart()
        
u.getFragment())
.equals(
u)
in all cases
new URI(u.getScheme()
        
u.getUserInfo()  u.getAuthority()
        
u.getPath()  u.getQuery()
        
u.getFragment())
.equals(
u)
if u is hierarchical and
new URI(u.getScheme()
        
u.getUserInfo()  u.getHost()  u.getPort()
        
u.getPath()  u.getQuery()
        
u.getFragment())
.equals(
u)
if u is hierarchical and has either no authority or a server-based authority.

URIs URLs and URNs

A URI is a uniform resource identifier while a URL is a uniform resource locator. Hence every URL is a URI abstractly speaking but not every URI is a URL. This is because there is another subcategory of URIs uniform resource names (URNs) which name resources but do not specify how to locate them. The mailto news and isbn URIs shown above are examples of URNs.

The conceptual distinction between URIs and URLs is reflected in the differences between this class and the URL class.

An instance of this class represents a URI reference in the syntactic sense defined by RFC 2396. A URI may be either absolute or relative. A URI string is parsed according to the generic syntax without regard to the scheme if any that it specifies. No lookup of the host if any is performed and no scheme-dependent stream handler is constructed. Equality hashing and comparison are defined strictly in terms of the character content of the instance. In other words a URI instance is little more than a structured string that supports the syntactic scheme-independent operations of comparison normalization resolution and relativization.

An instance of the URL class by contrast represents the syntactic components of a URL together with some of the information required to access the resource that it describes. A URL must be absolute that is it must always specify a scheme. A URL string is parsed according to its scheme. A stream handler is always established for a URL and in fact it is impossible to create a URL instance for a scheme for which no handler is available. Equality and hashing depend upon both the scheme and the Internet address of the host if any; comparison is not defined. In other words a URL is a structured string that supports the syntactic operation of resolution as well as the network I/O operations of looking up the host and opening a connection to the specified resource. @version 1.20 0125 02/1204/0317 @author Mark Reinhold @since 1.4 @see RFC 2279: UTF-8 a transformation format of ISO 10646
RFC 2373: IPv6 Addressing Architecture
RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax
RFC 2732: Format for Literal IPv6 Addresses in URLs
URISyntaxException

Class URI, URI resolve(String)

Constructs a new URI by parsing the given string and then resolving it against this URI.

This convenience method works as if invoking it were equivalent to evaluating the expression {@link #resolve(java.net.URI) resolve}(new URI.{@link #create(String) create}(str)).

@param str The string to be parsed into a URI @return The resulting URI @throws NullPointerException If str is null @throws IllegalArgumentException If the given string violates RFC 2396

Class URL

Class URL represents a Uniform Resource Locator a pointer to a "resource" on the World Wide Web. A resource can be something as simple as a file or a directory or it can be a reference to a more complicated object such as a query to a database or to a search engine. More information on the types of URLs and their formats can be found at:
http://archive.ncsa.uiuc.edu:80/SDG/Software/Mosaic/Demo/url-primer.html

In general a URL can be broken into several parts. The previous example of a URL indicates that the protocol to use is http (HyperText Transfer Protocol) and that the information resides on a host machine named www.ncsa.uiuc.edu. The information on that host machine is named /demowebSDG/Software/Mosaic/Demo/url-primer.html. The exact meaning of this name on the host machine is both protocol dependent and host dependent. The information normally resides in a file but it could be generated on the fly. This component of the URL is called the path component.

A URL can optionally specify a "port" which is the port number to which the TCP connection is made on the remote host machine. If the port is not specified the default port for the protocol is used instead. For example the default port for http is 80. An alternative port could be specified as:

 http://archive.ncsa.uiuc.edu:80/SDG/Software/Mosaic/Demo/url-primer.html 

The syntax of URL is defined by RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax amended by RFC 2732: Format for Literal IPv6 Addresses in URLs.

A URL may have appended to it a "fragment" also known as a "ref" or a "reference". The fragment is indicated by the sharp sign character "#" followed by more characters. For example

 http://java.sun.com/index.html#chapter1 

This fragment is not technically part of the URL. Rather it indicates that after the specified resource is retrieved the application is specifically interested in that part of the document that has the tag chapter1 attached to it. The meaning of a tag is resource specific.

An application can also specify a "relative URL" which contains only enough information to reach the resource relative to another URL. Relative URLs are frequently used within HTML pages. For example if the contents of the URL:

 http://java.sun.com/index.html 
contained within it the relative URL:
 FAQ.html 
it would be a shorthand for:
 http://java.sun.com/FAQ.html 

The relative URL need not specify all the components of a URL. If the protocol host name or port number is missing the value is inherited from the fully specified URL. The file component must be specified. The optional fragment is not inherited. @author James Gosling @version 1.116 12117 02/0307/0102 @since JDK1.0

Class URL, String getFile()

Gets the file name of this URL. The returned file portion will be the same as getPath() plus the concatenation of the value of getQuery() if any. If there is no query portion this method and getPath() will return identical results. @return the file name of this URL or an empty string if one does not exist

Class URLClassLoader

This class loader is used to load classes and resources from a search path of URLs referring to both JAR files and directories. Any URL that ends with a '/' is assumed to refer to a directory. Otherwise the URL is assumed to refer to a JAR file which will be opened as needed.

The AccessControlContext of the thread that created the instance of URLClassLoader will be used when subsequently loading classes and resources.

The classes that are loaded are by default granted permission only to access the URLs specified when the URLClassLoader was created. @author David Connelly @version 1.74 1277 07/0318/0102 @since 1.2


Class URLConnection

The abstract class URLConnection is the superclass of all classes that represent a communications link between the application and a URL. Instances of this class can be used both to read from and to write to the resource referenced by the URL. In general creating a connection to a URL is a multistep process:

openConnection() connect()
Manipulate parameters that affect the connection to the remote resource. Interact with the resource; query header fields and contents.
---------------------------->
time
  1. The connection object is created by invoking the openConnection method on a URL.
  2. The setup parameters and general request properties are manipulated.
  3. The actual connection to the remote object is made using the connect method.
  4. The remote object becomes available. The header fields and the contents of the remote object can be accessed.

The setup parameters are modified using the following methods:

and the general request properties are modified using the method:

Default values for the AllowUserInteraction and UseCaches parameters can be set using the methods setDefaultAllowUserInteraction and setDefaultUseCaches.

Each of the above set methods has a corresponding get method to retrieve the value of the parameter or general request property. The specific parameters and general request properties that are applicable are protocol specific.

The following methods are used to access the header fields and the contents after the connection is made to the remote object:

Certain header fields are accessed frequently. The methods:

provide convenient access to these fields. The getContentType method is used by the getContent method to determine the type of the remote object; subclasses may find it convenient to override the getContentType method.

In the common case all of the pre-connection parameters and general request properties can be ignored: the pre-connection parameters and request properties default to sensible values. For most clients of this interface there are only two interesting methods: getInputStream and getContent which are mirrored in the URL class by convenience methods.

More information on the request properties and header fields of an http connection can be found at:

 http://www.ietf.org/rfc/rfc2068.txt 
Note about fileNameMap: In versions prior to JDK 1.1.6 field fileNameMap of URLConnection was public. In JDK 1.1.6 and later fileNameMap is private; accessor and mutator methods getFileNameMap and setFileNameMap are added to access it. This change is also described on the Compatibility page. Calling the close() methods on the InputStream or OutputStream of an URLConnection after a request may free network resources associated with this instance unless particular protocol specifications specify different behaviours for it. @author James Gosling @version 1.88 1289 04/0319/0102 @see java.net.URL#openConnection() @see java.net.URLConnection#connect() @see java.net.URLConnection#getContent() @see java.net.URLConnection#getContentEncoding() @see java.net.URLConnection#getContentLength() @see java.net.URLConnection#getContentType() @see java.net.URLConnection#getDate() @see java.net.URLConnection#getExpiration() @see java.net.URLConnection#getHeaderField(int) @see java.net.URLConnection#getHeaderField(java.lang.String) @see java.net.URLConnection#getInputStream() @see java.net.URLConnection#getLastModified() @see java.net.URLConnection#getOutputStream() @see java.net.URLConnection#setAllowUserInteraction(boolean) @see java.net.URLConnection#setDefaultUseCaches(boolean) @see java.net.URLConnection#setDoInput(boolean) @see java.net.URLConnection#setDoOutput(boolean) @see java.net.URLConnection#setIfModifiedSince(long) @see java.net.URLConnection#setRequestProperty(java.lang.String java.lang.String) @see java.net.URLConnection#setUseCaches(boolean) @since JDK1.0

Class URLDecoder

Utility class for HTML form decoding. This class contains static methods for decoding a String from the application/x-www-form-urlencoded MIME format.

To conversion process is the reverse of that used by the URLEncoder class. It is assumed that all characters in the encoded string are one of the following: "a" through "z" "A" through "Z" "0" through "9" and "-" "_" "." and "*". The character "%" is allowed but is interpreted as the start of a special escaped sequence.

The following rules are applied in the conversion:

There are two possible ways in which this decoder could deal with illegal strings. It could either leave illegal characters alone or it could throw an {@link java.lang.IllegalArgumentException}. Which approach the decoder takes is left to the implementation. @author Mark Chamness @author Michael McCloskey @version 1.20 1221 04/0315/0102 @since 1.2

Class URLDecoder, String decode(String, String)

Decodes a application/x-www-form-urlencoded string using a specific encoding scheme. The supplied encoding is used to determine what characters are represented by any consecutive sequences of the form "%xy".

Note: The World Wide Web Consortium Recommendation states that UTF-8 should be used. Not doing so may introduce incompatibilites. @param s the String to decode @param enc The name of a supported character encoding. @return the newly decoded String @exception UnsupportedEncodingException If the named encoding is not supported @see URLEncoder#encode(java.lang.String java.lang.String) @since 1.4


Class URLEncoder

Utility class for HTML form encoding. This class contains static methods for converting a String to the application/x-www-form-urlencoded MIME format. For more information about HTML form encoding consult the HTML specification.

When encoding a String the following rules apply:

For example using UTF-8 as the encoding scheme the string "The string ü@foo-bar" would get converted to "The+string+%C3%BC%40foo-bar" because in UTF-8 the character ü is encoded as two bytes C3 (hex) and BC (hex) and the character @ is encoded as one byte 40 (hex). @author Herb Jellinek @version 1.25 1226 04/0315/0102 @since JDK1.0

Class URLEncoder, String encode(String, String)

Translates a string into application/x-www-form-urlencoded format using a specific encoding scheme. This method uses the supplied encoding scheme to obtain the bytes for unsafe characters.

Note: The World Wide Web Consortium Recommendation states that UTF-8 should be used. Not doing so may introduce incompatibilites. @param s String to be translated. @param enc The name of a supported character encoding. @return the translated String. @exception UnsupportedEncodingException If the named encoding is not supported @see URLDecoder#decode(java.lang.String java.lang.String) @since 1.4


Class URLStreamHandler

The abstract class URLStreamHandler is the common superclass for all stream protocol handlers. A stream protocol handler knows how to make a connection for a particular protocol type such as http ftp or gopher.

In most cases an instance of a URLStreamHandler subclass is not created directly by an application. Rather the first time a protocol name is encountered when constructing a URL the appropriate stream protocol handler is automatically loaded. @author James Gosling @version 1.5558 12/03/0105/02 @see java.net.URL#URL(java.lang.String java.lang.String int java.lang.String) @since JDK1.0

Class URLStreamHandler, void setURL(URL, String, String, int, String, String)

Sets the fields of the URL argument to the indicated values. Only classes derived from URLStreamHandler are supposed to be able to call the set method on a URL. @param u the URL to modify. @param protocol the protocol name. This value is ignored since 1.2. @param host the remote host value for the URL. @param port the port on the remote machine. @param file the file. @param ref the reference. @exception SecurityException if the protocol handler of the URL is different from this one @deprecated Use setURL(URL String String int String String String String);
Class URLStreamHandler, void setURL(URL, String, String, int, String, String, String, String, String)

Sets the fields of the URL argument to the indicated values. Only classes derived from URLStreamHandler are supposed to be able to call the set method on a URL. @param u the URL to modify. @param protocol the protocol name. @param host the remote host value for the URL. @param port the port on the remote machine. @param authority the authority part for the URL. @param userInfo the userInfo part of the URL. @param path the path component of the URL. @param query the query part for the URL. @param ref the reference. @exception SecurityException if the protocol handler of the URL is different from this one @see java.net.URL#set(java.lang.String java.lang.String int java.lang.String java.lang.String)