The class Authenticator represents an object that knows how to obtain
authentication for a network connection.  Usually, it will do this
by prompting the user for information.

Applications use this class by overriding getPasswordAuthentication() in a sub-class. This method will
typically use the various getXXX() accessor methods to get information
about the entity requesting authentication. It must then acquire a
username and password either by interacting with the user or through
some other non-interactive means. The credentials are then returned
as a PasswordAuthentication return value.

An instance of this concrete sub-class is then registered
with the system by calling setDefault(Authenticator).
When authentication is required, the system will invoke one of the
requestPasswordAuthentication() methods which in turn will call the
getPasswordAuthentication() method of the registered object.

All methods that request authentication have a default implementation
that fails.

Signals that an error occurred while attempting to bind a
socket to a local address and port.  Typically, the port is
in use, or the requested local address could not be assigned.

Represents channels for storing resources in the
ResponseCache. Instances of such a class provide an
OutputStream object which is called by protocol handlers to
store the resource data into the cache, and also an abort() method
which allows a cache store operation to be interrupted and
abandoned. If an IOException is encountered while reading the
response or writing to the cache, the current cache store operation
will be aborted.

Represent channels for retrieving resources from the
ResponseCache. Instances of such a class provide an
InputStream that returns the entity body, and also a
getHeaders() method which returns the associated response headers.

Signals that an error occurred while attempting to connect a
socket to a remote address and port.  Typically, the connection
was refused remotely (e.g., no process is listening on the
remote address/port).

{package-prefix}.{major}.{minor}

The abstract class ContentHandler is the superclass
of all classes that read an Object from a
URLConnection.

An application does not generally call the
getContent method in this class directly. Instead, an
application calls the getContent method in class
URL or in URLConnection.
The application's content handler factory (an instance of a class that
implements the interface ContentHandlerFactory set
up by a call to setContentHandler) is
called with a String giving the MIME type of the
object being received on the socket. The factory returns an
instance of a subclass of ContentHandler, and its
getContent method is called to create the object.

If no content handler could be found, URLConnection will
look for a content handler in a user-defineable set of places.
By default it looks in sun.net.www.content, but users can define a
vertical-bar delimited set of class prefixes to search through in
addition by defining the java.content.handler.pkgs property.
The class name must be of the form:


    {package-prefix}.{major}.{minor}
e.g.
    YoyoDyne.experimental.text.plain
If the loading of the content handler class would be performed by
a classloader that is outside of the delegation chain of the caller,
the JVM will need the RuntimePermission "getClassLoader".

This interface defines a factory for content handlers. An
implementation of this interface should map a MIME type into an
instance of ContentHandler.

This interface is used by the URLStreamHandler class
to create a ContentHandler for a MIME type.

A CookieHandler object provides a callback mechanism to hook up a
HTTP state management policy implementation into the HTTP protocol
handler. The HTTP state management mechanism specifies a way to
create a stateful session with HTTP requests and responses.

A system-wide CookieHandler that to used by the HTTP protocol
handler can be registered by doing a
CookieHandler.setDefault(CookieHandler). The currently registered
CookieHandler can be retrieved by calling
CookieHandler.getDefault().

For more information on HTTP state management, see RFC 2965: HTTP
State Management Mechanism

             use

CookieHandler is at the core of cookie management. User can call
CookieHandler.setDefault to set a concrete CookieHanlder implementation
to be used.


CookiePolicy.shouldAccept will be called by CookieManager.put to see whether
or not one cookie should be accepted and put into cookie store. User can use
any of three pre-defined CookiePolicy, namely ACCEPT_ALL, ACCEPT_NONE and
ACCEPT_ORIGINAL_SERVER, or user can define his own CookiePolicy implementation
and tell CookieManager to use it.


CookieStore is the place where any accepted HTTP cookie is stored in.
If not specified when created, a CookieManager instance will use an internal
in-memory implementation. Or user can implements one and tell CookieManager
to use it.


Currently, only CookieStore.add(URI, HttpCookie) and CookieStore.get(URI)
are used by CookieManager. Others are for completeness and might be needed
by a more sophisticated CookieStore implementation, e.g. a NetscapeCookieSotre.

  // this should be done at the beginning of an HTTP session
  CookieHandler.setDefault(new CookieManager(new MyCookieStore(), new MyCookiePolicy()));

  // this should be done at the beginning of an HTTP session
  CookieHandler.setDefault(new CookieManager());
  // this can be done at any point of an HTTP session
  ((CookieManager)CookieHandler.getDefault()).setCookiePolicy(new MyCookiePolicy());

CookieManager provides a concrete implementation of CookieHandler,
which separates the storage of cookies from the policy surrounding accepting
and rejecting cookies. A CookieManager is initialized with a CookieStore
which manages storage, and a CookiePolicy object, which makes
policy decisions on cookie acceptance/rejection.

 The HTTP cookie management in java.net package looks like:



                 use
CookieHandler <------- HttpURLConnection
      ^
      | impl
      |         use
CookieManager -------> CookiePolicy
            |   use
            |--------> HttpCookie
            |              ^
            |              | use
            |   use        |
            |--------> CookieStore
                           ^
                           | impl
                           |
                 Internal in-memory implementation


    CookieHandler is at the core of cookie management. User can call
    CookieHandler.setDefault to set a concrete CookieHanlder implementation
    to be used.


    CookiePolicy.shouldAccept will be called by CookieManager.put to see whether
    or not one cookie should be accepted and put into cookie store. User can use
    any of three pre-defined CookiePolicy, namely ACCEPT_ALL, ACCEPT_NONE and
    ACCEPT_ORIGINAL_SERVER, or user can define his own CookiePolicy implementation
    and tell CookieManager to use it.


    CookieStore is the place where any accepted HTTP cookie is stored in.
    If not specified when created, a CookieManager instance will use an internal
    in-memory implementation. Or user can implements one and tell CookieManager
    to use it.


    Currently, only CookieStore.add(URI, HttpCookie) and CookieStore.get(URI)
    are used by CookieManager. Others are for completeness and might be needed
    by a more sophisticated CookieStore implementation, e.g. a NetscapeCookieSotre.




There're various ways user can hook up his own HTTP cookie management behavior, e.g.


  Use CookieHandler.setDefault to set a brand new CookieHandler implementation
  Let CookieManager be the default CookieHandler implementation,
      but implement user's own CookieStore and CookiePolicy
      and tell default CookieManager to use them:


      // this should be done at the beginning of an HTTP session
      CookieHandler.setDefault(new CookieManager(new MyCookieStore(), new MyCookiePolicy()));
  Let CookieManager be the default CookieHandler implementation, but
      use customized CookiePolicy:


      // this should be done at the beginning of an HTTP session
      CookieHandler.setDefault(new CookieManager());
      // this can be done at any point of an HTTP session
      ((CookieManager)CookieHandler.getDefault()).setCookiePolicy(new MyCookiePolicy());



The implementation conforms to RFC 2965, section 3.3.

CookiePolicy implementations decide which cookies should be accepted
and which should be rejected. Three pre-defined policy implementations
are provided, namely ACCEPT_ALL, ACCEPT_NONE and ACCEPT_ORIGINAL_SERVER.

See RFC 2965 sec. 3.3 and 7 for more detail.

A CookieStore object represents a storage for cookie. Can store and retrieve
cookies.

CookieManager will call CookieStore.add to save cookies
for every incoming HTTP response, and call CookieStore.get to
retrieve cookie for every outgoing HTTP request. A CookieStore
is responsible for removing HttpCookie instances which have expired.

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.

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.

 Where possible, a newly constructed DatagramSocket has the
SO_BROADCAST socket option enabled so as
to allow the transmission of broadcast datagrams. 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.

Abstract datagram and multicast socket implementation base class.

This interface defines a factory for datagram socket implementations. It
is used by the classes DatagramSocket to create actual socket
implementations.

A simple interface which provides a mechanism to map
between a file name and a MIME type string.

An HttpCookie object represents an HTTP cookie, which carries state
information between server and user agent. Cookie is widely adopted
to create stateful sessions.

 There are 3 HTTP cookie specifications:

  Netscape draft
  RFC 2109 -
http://www.ietf.org/rfc/rfc2109.txt
  RFC 2965 -
http://www.ietf.org/rfc/rfc2965.txt


 HttpCookie class can accept all these 3 forms of syntax.

Thrown to indicate that a HTTP request needs to be retried
but cannot be retried automatically, due to streaming mode
being enabled.

A URLConnection with support for HTTP-specific features. See
 the spec  for
details.


Each HttpURLConnection instance is used to make a single request
but the underlying network connection to the HTTP server may be
transparently shared by other instances. Calling the close() methods
on the InputStream or OutputStream of an HttpURLConnection
after a request may free network resources associated with this
instance but has no effect on any shared persistent connection.
Calling the disconnect() method may close the underlying socket
if a persistent connection is otherwise idle at that time.

The HTTP protocol handler has a few settings that can be accessed through
System Properties. This covers
Proxy settings as well as
 various other settings.


Security permissions

If a security manager is installed, and if a method is called which results in an
attempt to open a connection, the caller must possess either:-
a "connect" SocketPermission to the host/port combination of the
destination URL or
a URLPermission that permits this request.

If automatic redirection is enabled, and this request is redirected to another
destination, then the caller must also have permission to connect to the
redirected host/URL.

If the ALLOW_UNASSIGNED flag is used, the domain name string to be converted
    can contain code points that are unassigned in Unicode 3.2, which is the
    Unicode version on which IDN conversion is based. If the flag is not used,
    the presence of such unassigned code points is treated as an error.
If the USE_STD3_ASCII_RULES flag is used, ASCII strings are checked against RFC 1122 and RFC 1123.
    It is an error if they don't meet the requirements.

Provides methods to convert internationalized domain names (IDNs) between
a normal Unicode representation and an ASCII Compatible Encoding (ACE) representation.
Internationalized domain names can use characters from the entire range of
Unicode, while traditional domain names are restricted to ASCII characters.
ACE is an encoding of Unicode strings that uses only ASCII characters and
can be used with software (such as the Domain Name System) that only
understands traditional domain names.

Internationalized domain names are defined in RFC 3490.
RFC 3490 defines two operations: ToASCII and ToUnicode. These 2 operations employ
Nameprep algorithm, which is a
profile of Stringprep, and
Punycode algorithm to convert
domain name string back and forth.

The behavior of aforementioned conversion process can be adjusted by various flags:

    If the ALLOW_UNASSIGNED flag is used, the domain name string to be converted
        can contain code points that are unassigned in Unicode 3.2, which is the
        Unicode version on which IDN conversion is based. If the flag is not used,
        the presence of such unassigned code points is treated as an error.
    If the USE_STD3_ASCII_RULES flag is used, ASCII strings are checked against RFC 1122 and RFC 1123.
        It is an error if they don't meet the requirements.

These flags can be logically OR'ed together.

The security consideration is important with respect to internationalization
domain name support. For example, English domain names may be homographed
- maliciously misspelled by substitution of non-Latin letters.
Unicode Technical Report #36
discusses security issues of IDN support as well as possible solutions.
Applications are responsible for taking adequate security measures when using
international domain names.

This class represents an Internet Protocol version 4 (IPv4) address.
Defined by
RFC 790: Assigned Numbers,

RFC 1918: Address Allocation for Private Internets,
and RFC 2365:
Administratively Scoped IP Multicast

 Textual representation of IP addresses

Textual representation of IPv4 address used as input to methods
takes one of the following forms:


d.d.d.d
d.d.d
d.d
d


 When four parts are specified, each is interpreted as a byte of
data and assigned, from left to right, to the four bytes of an IPv4
address.

 When a three part address is specified, the last part is
interpreted as a 16-bit quantity and placed in the right most two
bytes of the network address. This makes the three part address
format convenient for specifying Class B net- work addresses as
128.net.host.

 When a two part address is supplied, the last part is
interpreted as a 24-bit quantity and placed in the right most three
bytes of the network address. This makes the two part address
format convenient for specifying Class A network addresses as
net.host.

 When only one part is given, the value is stored directly in
the network address without any byte rearrangement.

 For methods that return a textual representation as output
value, the first form, i.e. a dotted-quad string, is used.

 The Scope of a Multicast Address

Historically the IPv4 TTL field in the IP header has doubled as a
multicast scope field: a TTL of 0 means node-local, 1 means
link-local, up through 32 means site-local, up through 64 means
region-local, up through 128 means continent-local, and up through
255 are global. However, the administrative scoping is preferred.
Please refer to
RFC 2365: Administratively Scoped IP Multicast

    In InetAddress and Inet6Address, it is used for internal
    representation; it has no functional role. Java will never
    return an IPv4-mapped address.  These classes can take an
    IPv4-mapped address as input, both in byte array and text
    representation. However, it will be converted into an IPv4
    address.

This class represents an Internet Protocol version 6 (IPv6) address.
Defined by
RFC 2373: IP Version 6 Addressing Architecture.

 Textual representation of IP addresses

Textual representation of IPv6 address used as input to methods
takes one of the following forms:


   The preferred form is x:x:x:x:x:x:x:x,
  where the 'x's are
  the hexadecimal values of the eight 16-bit pieces of the
  address. This is the full form.  For example,


  1080:0:0:0:8:800:200C:417A


   Note that it is not necessary to write the leading zeros in
  an individual field. However, there must be at least one numeral
  in every field, except as described below.

   Due to some methods of allocating certain styles of IPv6
  addresses, it will be common for addresses to contain long
  strings of zero bits. In order to make writing addresses
  containing zero bits easier, a special syntax is available to
  compress the zeros. The use of "::" indicates multiple groups
  of 16-bits of zeros. The "::" can only appear once in an address.
  The "::" can also be used to compress the leading and/or trailing
  zeros in an address. For example,


  1080::8:800:200C:417A


   An alternative form that is sometimes more convenient
  when dealing with a mixed environment of IPv4 and IPv6 nodes is
  x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values
  of the six high-order 16-bit pieces of the address, and the 'd's
  are the decimal values of the four low-order 8-bit pieces of the
  standard IPv4 representation address, for example,


  ::FFFF:129.144.52.38
  ::129.144.52.38


   where "::FFFF:d.d.d.d" and "::d.d.d.d" are, respectively, the
  general forms of an IPv4-mapped IPv6 address and an
  IPv4-compatible IPv6 address. Note that the IPv4 portion must be
  in the "d.d.d.d" form. The following forms are invalid:


  ::FFFF:d.d.d
  ::FFFF:d.d
  ::d.d.d
  ::d.d


   The following form:


  ::FFFF:d


   is valid, however it is an unconventional representation of
  the IPv4-compatible IPv6 address,


  ::255.255.0.d


   while "::d" corresponds to the general IPv6 address
  "0:0:0:0:0:0:0:d".


 For methods that return a textual representation as output
value, the full form is used. Inet6Address will return the full
form because it is unambiguous when used in combination with other
textual data.

 Special IPv6 address



IPv4-mapped address
        Of the form::ffff:w.x.y.z, this IPv6 address is used to
        represent an IPv4 address. It allows the native program to
        use the same address data structure and also the same
        socket when communicating with both IPv4 and IPv6 nodes.

        In InetAddress and Inet6Address, it is used for internal
        representation; it has no functional role. Java will never
        return an IPv4-mapped address.  These classes can take an
        IPv4-mapped address as input, both in byte array and text
        representation. However, it will be converted into an IPv4
        address.


Textual representation of IPv6 scoped addresses

 The textual representation of IPv6 addresses as described above can be
extended to specify IPv6 scoped addresses. This extension to the basic
addressing architecture is described in [draft-ietf-ipngwg-scoping-arch-04.txt].

 Because link-local and site-local addresses are non-global, it is possible
that different hosts may have the same destination address and may be
reachable through different interfaces on the same originating system. In
this case, the originating system is said to be connected to multiple zones
of the same scope. In order to disambiguate which is the intended destination
zone, it is possible to append a zone identifier (or scope_id) to an
IPv6 address.

 The general format for specifying the scope_id is the following:

IPv6-address%scope_id
 The IPv6-address is a literal IPv6 address as described above.
The scope_id refers to an interface on the local system, and it can be
specified in two ways.
As a numeric identifier. This must be a positive integer
that identifies the particular interface and scope as understood by the
system. Usually, the numeric values can be determined through administration
tools on the system. Each interface may have multiple values, one for each
scope. If the scope is unspecified, then the default value used is zero.
As a string. This must be the exact string that is returned by
NetworkInterface.getName() for the particular interface in
question. When an Inet6Address is created in this way, the numeric scope-id
is determined at the time the object is created by querying the relevant
NetworkInterface.

 Note also, that the numeric scope_id can be retrieved from
Inet6Address instances returned from the NetworkInterface class. This can be
used to find out the current scope ids configured on the system.

     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.

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.

There is a couple of
System Properties affecting how IPv4 and IPv6 addresses are used.

 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 vice versa.

 InetAddress Caching

The InetAddress class has a cache to store successful as well as
unsuccessful host name resolutions.

 By default, when a security manager is installed, in order to
protect against DNS spoofing attacks,
the result of positive host name resolutions are
cached forever. When a security manager is not installed, the default
behavior is to cache entries for a finite (implementation dependent)
period of time. The result of unsuccessful host
name resolution is cached for a very short period of time (10
seconds) to improve performance.

 If the default behavior is not desired, then 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
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. The default
setting is to cache for an implementation specific period of time.

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".

This class implements an IP Socket Address (IP address  port number)
It can also be a pair (hostname  port number), in which case an attempt
will be made to resolve the hostname. If resolution fails then the address
is said to be unresolved but can still be used on some circumstances
like connecting through a proxy.

It provides an immutable object used by sockets for binding, connecting, or
as returned values.

The wildcard is a special local IP address. It usually means "any"
and can only be used for bind operations.

This class represents a Network Interface address. In short it's an
IP address, a subnet mask and a broadcast address when the address is
an IPv4 one. An IP address and a network prefix length in the case
of IPv6 address.

A URL Connection to a Java ARchive (JAR) file or an entry in a JAR
file.

The syntax of a JAR URL is:



jar:<url>!/{entry}

for example:

jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class

Jar URLs should be used to refer to a JAR file or entries in
a JAR file. The example above is a JAR URL which refers to a JAR
entry. If the entry name is omitted, the URL refers to the whole
JAR file:

jar:http://www.foo.com/bar/baz.jar!/

Users should cast the generic URLConnection to a
JarURLConnection when they know that the URL they created is a JAR
URL, and they need JAR-specific functionality. For example:



URL url = new URL("jar:file:/home/duke/duke.jar!/");
JarURLConnection jarConnection = (JarURLConnection)url.openConnection();
Manifest manifest = jarConnection.getManifest();

JarURLConnection instances can only be used to read from JAR files.
It is not possible to get a OutputStream to modify or write
to the underlying JAR file using this class.
Examples:



A Jar entry
jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class

A Jar file
jar:http://www.foo.com/bar/baz.jar!/

A Jar directory
jar:http://www.foo.com/bar/baz.jar!/COM/foo/



!/ is referred to as the separator.

When constructing a JAR url via new URL(context, spec),
the following rules apply:



if there is no context URL and the specification passed to the
URL constructor doesn't contain a separator, the URL is considered
to refer to a JarFile.

if there is a context URL, the context URL is assumed to refer
to a JAR file or a Jar directory.

if the specification begins with a '/', the Jar directory is
ignored, and the spec is considered to be at the root of the Jar
file.

Examples:



context: jar:http://www.foo.com/bar/jar.jar!/,
spec:baz/entry.txt

url:jar:http://www.foo.com/bar/jar.jar!/baz/entry.txt

context: jar:http://www.foo.com/bar/jar.jar!/baz,
spec:entry.txt

url:jar:http://www.foo.com/bar/jar.jar!/baz/entry.txt

context: jar:http://www.foo.com/bar/jar.jar!/baz,
spec:/entry.txt

url:jar:http://www.foo.com/bar/jar.jar!/entry.txt

Thrown to indicate that a malformed URL has occurred. Either no
legal protocol could be found in a specification string or the
string could not be parsed.

The multicast datagram socket class is useful for sending
and receiving IP multicast packets.  A MulticastSocket is
a (UDP) DatagramSocket, with additional capabilities for
joining "groups" of other multicast hosts on the internet.

A multicast group is specified by a class D IP address
and by a standard UDP port number. Class D IP addresses
are in the range 224.0.0.0 to 239.255.255.255,
inclusive. The address 224.0.0.0 is reserved and should not be used.

One would join a multicast group by first creating a MulticastSocket
with the desired port, then invoking the
joinGroup(InetAddress groupAddr)
method:


// join a Multicast group and send the group salutations
...
String msg = "Hello";
InetAddress group = InetAddress.getByName("228.5.6.7");
MulticastSocket s = new MulticastSocket(6789);
s.joinGroup(group);
DatagramPacket hi = new DatagramPacket(msg.getBytes(), msg.length(),
                            group, 6789);
s.send(hi);
// get their responses!
byte[] buf = new byte[1000];
DatagramPacket recv = new DatagramPacket(buf, buf.length);
s.receive(recv);
...
// OK, I'm done talking - leave the group...
s.leaveGroup(group);

When one sends a message to a multicast group, all subscribing
recipients to that host and port receive the message (within the
time-to-live range of the packet, see below).  The socket needn't
be a member of the multicast group to send messages to it.

When a socket subscribes to a multicast group/port, it receives
datagrams sent by other hosts to the group/port, as do all other
members of the group and port.  A socket relinquishes membership
in a group by the leaveGroup(InetAddress addr) method.
Multiple MulticastSocket's may subscribe to a multicast group
and port concurrently, and they will all receive group datagrams.

Currently applets are not allowed to use multicast sockets.

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.*" and "*" signify a wildcard
 match, while "*foo" and "a*b" do not.

 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


   allowHttpTrace
   The ability to use the HTTP TRACE method in HttpURLConnection.
   Malicious code using HTTP TRACE could get access to security sensitive
   information in the HTTP headers (such as cookies) that it might not
   otherwise have access to.



   getCookieHandler
   The ability to get the cookie handler that processes highly
   security sensitive cookie information for an Http session.
   Malicious code can get a cookie handler to obtain access to
   highly security sensitive cookie information. Some web servers
   use cookies to save user private information such as access
   control information, or to track user browsing habit.



  getNetworkInformation
  The ability to retrieve all information about local network interfaces.
  Malicious code can read information about network hardware such as
  MAC addresses, which could be used to construct local IPv6 addresses.



   getProxySelector
   The ability to get the proxy selector used to make decisions
   on which proxies to use when making network connections.
   Malicious code can get a ProxySelector to discover proxy
   hosts and ports on internal networks, which could then become
   targets for attack.



   getResponseCache
   The ability to get the response cache that provides
   access to a local response cache.
   Malicious code getting access to the local response cache
   could access security sensitive information.



   requestPasswordAuthentication
   The ability
 to ask the authenticator registered with the system for
 a password
   Malicious code may steal this password.



   setCookieHandler
   The ability to set the cookie handler that processes highly
   security sensitive cookie information for an Http session.
   Malicious code can set a cookie handler to obtain access to
   highly security sensitive cookie information. Some web servers
   use cookies to save user private information such as access
   control information, or to track user browsing habit.



   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.



   setProxySelector
   The ability to set the proxy selector used to make decisions
   on which proxies to use when making network connections.
   Malicious code can set a ProxySelector that directs network
   traffic to an arbitrary network host.



   setResponseCache
   The ability to set the response cache that provides access to
   a local response cache.
   Malicious code getting access to the local response cache
   could access security sensitive information, or create false
   entries in the response cache.



   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.

This class represents a Network Interface made up of a name,
and a list of IP addresses assigned to this interface.
It is used to identify the local interface on which a multicast group
is joined.

Interfaces are normally known by names such as "le0".

Signals that an error occurred while attempting to connect a
socket to a remote address and port.  Typically, the remote
host cannot be reached because of an intervening firewall, or
if an intermediate router is down.

The class PasswordAuthentication is a data holder that is used by
Authenticator.  It is simply a repository for a user name and a password.

Signals that an ICMP Port Unreachable message has been
received on a connected datagram.

Thrown to indicate that there is an error in the underlying
protocol, such as a TCP error.

Represents a family of communication protocols.

This class represents a proxy setting, typically a type (http, socks) and
a socket address.
A Proxy is an immutable object.

Selects the proxy server to use, if any, when connecting to the
network resource referenced by a URL. A proxy selector is a
concrete sub-class of this class and is registered by invoking the
setDefault method. The
currently registered proxy selector can be retrieved by calling
getDefault method.

 When a proxy selector is registered, for instance, a subclass
of URLConnection class should call the select
method for each URL request so that the proxy selector can decide
if a direct, or proxied connection should be used. The select method returns an iterator over a collection with
the preferred connection approach.

 If a connection cannot be established to a proxy (PROXY or
SOCKS) servers then the caller should call the proxy selector's
connectFailed method to notify the proxy
selector that the proxy server is unavailable.

The default proxy selector does enforce a
set of System Properties
related to proxy settings.

Represents implementations of URLConnection caches. An instance of
such a class can be registered with the system by doing
ResponseCache.setDefault(ResponseCache), and the system will call
this object in order to:

   store resource data which has been retrieved from an
           external source into the cache
        try to fetch a requested resource that may have been
           stored in the cache


The ResponseCache implementation decides which resources
should be cached, and for how long they should be cached. If a
request resource cannot be retrieved from the cache, then the
protocol handlers will fetch the resource from its original
location.

The settings for URLConnection#useCaches controls whether the
protocol is allowed to use a cached response.

For more information on HTTP caching, see RFC 2616: Hypertext
Transfer Protocol -- HTTP/1.1

Represents a cache response originally retrieved through secure
means, such as TLS.

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.

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.

This class represents a Socket Address with no protocol attachment.
As an abstract class, it is meant to be subclassed with a specific,
protocol dependent, implementation.

It provides an immutable object used by sockets for binding, connecting, or
as returned values.

Thrown to indicate that there is an error creating or accessing a Socket.

The abstract class SocketImpl is a common superclass
of all classes that actually implement sockets. It is used to
create both client and server sockets.

A "plain" socket implements these methods exactly as
described, without attempting to go through a firewall or proxy.

This interface defines a factory for socket implementations. It
is used by the classes Socket and
ServerSocket to create actual socket
implementations.

A socket option associated with a socket.

 In the channels package, the NetworkChannel interface defines the setOption
and getOption
methods to set and query the channel's socket options.

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.

This class represents access to a network via sockets.
A SocketPermission consists of a
host specification and a set of "actions" specifying ways to
connect to that host. The host is specified as


   host = (hostname | IPv4address | iPv6reference) [:portrange]
   portrange = portnumber | -portnumber | portnumber-[portnumber]
The host is expressed as a DNS name, as a numerical IP address,
or as "localhost" (for the local machine).
The wildcard "*" may be included once in a DNS name host
specification. If it is included, it must be in the leftmost
position, as in "*.sun.com".

The format of the IPv6reference should follow that specified in RFC 2732: Format
for Literal IPv6 Addresses in URLs:


   ipv6reference = "[" IPv6address "]"
For example, you can construct a SocketPermission instance
as the following:


   String hostAddress = inetaddress.getHostAddress();
   if (inetaddress instanceof Inet6Address) {
       sp = new SocketPermission("["  hostAddress  "]:"  port, action);
   } else {
       sp = new SocketPermission(hostAddress  ":"  port, action);
   }
or


   String host = url.getHost();
   sp = new SocketPermission(host  ":"  port, action);

The full uncompressed form of
an IPv6 literal address is also valid.

The port or portrange is optional. A port specification of the
form "N-", where N is a port number, signifies all ports
numbered N and above, while a specification of the
form "-N" indicates all ports numbered N and below.
The special port value 0 refers to the entire ephemeral
port range. This is a fixed range of ports a system may use to
allocate dynamic ports from. The actual range may be system dependent.

The possible ways to connect to the host are


accept
connect
listen
resolve
The "listen" action is only meaningful when used with "localhost" and
means the ability to bind to a specified port.
The "resolve" action is implied when any of the other actions are present.
The action "resolve" refers to host/ip name service lookups.

The actions string is converted to lowercase before processing.
As an example of the creation and meaning of SocketPermissions,
note that if the following permission:



  p1 = new SocketPermission("puffin.eng.sun.com:7777", "connect,accept");

is granted to some code, it allows that code to connect to port 7777 on
puffin.eng.sun.com, and to accept connections on that port.

Similarly, if the following permission:



  p2 = new SocketPermission("localhost:1024-", "accept,connect,listen");

is granted to some code, it allows that code to
accept connections on, connect to, or listen on any port between
1024 and 65535 on the local host.

Note: Granting code permission to accept or make connections to remote
hosts may be dangerous because malevolent code can then more easily
transfer and share confidential data among parties who may not
otherwise have access to the data.

Signals that a timeout has occurred on a socket read or accept.

Defines the standard socket options.

 The name of each socket option defined by this
class is its field name.

 In this release, the socket options defined here are used by network channels in the channels package.

Thrown to indicate that the IP address of a host could not be determined.

Thrown to indicate that an unknown service exception has
occurred. Either the MIME type returned by a URL connection does
not make sense, or the application is attempting to write to a
read-only URL connection.

(1)

new URI(u.getScheme(),
        u.getSchemeSpecificPart(),
        u.getFragment())
.equals(u)

new URI(u.getScheme(),
        u.getUserInfo(), u.getAuthority(),
        u.getPath(), u.getQuery(),
        u.getFragment())
.equals(u)

new URI(u.getScheme(),
        u.getUserInfo(), u.getHost(), u.getPort(),
        u.getPath(), u.getQuery(),
        u.getFragment())
.equals(u)

Represents a Uniform Resource Identifier (URI) reference.

 Aside from some minor deviations noted below, 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. The Literal IPv6 address format
also supports scope_ids. The syntax and usage of scope_ids is described
here.
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


https://docs.oracle.com/javase/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


https://docs.oracle.com/javase/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:



   A character is encoded by replacing it
  with the sequence of escaped octets that represent that character in the
  UTF-8 character set.  The Euro currency symbol ('\u20AC'),
  for example, is encoded as "%E2%82%AC".  (Deviation from
  RFC 2396, which does not specify any particular character
  set.)

   An illegal character is quoted simply by
  encoding it.  The space character, for example, is quoted by replacing it
  with "%20".  UTF-8 contains US-ASCII, hence for US-ASCII
  characters this transformation has exactly the effect required by
  RFC 2396.


  A sequence of escaped octets is decoded by
  replacing it with the sequence of characters that it represents in the
  UTF-8 character set.  UTF-8 contains US-ASCII, hence decoding has the
  effect of de-quoting any quoted US-ASCII characters as well as that of
  decoding any encoded non-US-ASCII characters.  If a decoding error occurs
  when decoding the escaped octets then the erroneous octets are replaced by
  '\uFFFD', the Unicode replacement character.



These operations are exposed in the constructors and methods of this class
as follows:



   The single-argument
  constructor requires any illegal characters in its argument to be
  quoted and preserves any escaped octets and other characters that
  are present.

   The multi-argument constructors quote illegal characters as
  required by the components in which they appear.  The percent character
  ('%') is always quoted by these constructors.  Any other
  characters are preserved.

   The getRawUserInfo, getRawPath, getRawQuery, getRawFragment, getRawAuthority, and getRawSchemeSpecificPart methods return the
  values of their corresponding components in raw form, without interpreting
  any escaped octets.  The strings returned by these methods may contain
  both escaped octets and other characters, and will not contain any
  illegal characters.

   The getUserInfo, getPath, getQuery, getFragment, getAuthority, and getSchemeSpecificPart methods decode any escaped
  octets in their corresponding components.  The strings returned by these
  methods may contain both other characters and illegal characters,
  and will not contain any escaped octets.

   The toString method returns a URI string with
  all necessary quotation but which may contain other characters.


   The toASCIIString method returns a fully
  quoted and encoded URI string that does not contain any other
  characters.




 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.

Checked exception thrown to indicate that a string could not be parsed as a
URI reference.

http://www.example.com/docs/resource1.html

http://www.example.com:1080/docs/resource1.html

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

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

FAQ.html

http://java.sun.com/FAQ.html

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:

Types of URL

In general, a URL can be broken into several parts. Consider the
following example:


    http://www.example.com/docs/resource1.html

The URL above indicates that the protocol to use is
http (HyperText Transfer Protocol) and that the
information resides on a host machine named
www.example.com. The information on that host
machine is named /docs/resource1.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://www.example.com:1080/docs/resource1.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. The Literal IPv6 address format
also supports scope_ids. The syntax and usage of scope_ids is described
here.

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.

The URL class does not itself encode or decode any URL components
according to the escaping mechanism defined in RFC2396. It is the
responsibility of the caller to encode any fields, which need to be
escaped prior to calling URL, and also to decode any escaped fields,
that are returned from URL. Furthermore, because URL has no knowledge
of URL escaping, it does not recognise equivalence between the encoded
or decoded form of the same URL. For example, the two URLs:


   http://foo.com/hello world/ and http://foo.com/hello%20world
would be considered not equal to each other.

Note, the URI class does perform escaping of its
component fields in certain circumstances. The recommended way
to manage the encoding and decoding of URLs is to use URI,
and to convert between these two classes using toURI() and
URI.toURL().

The URLEncoder and URLDecoder classes can also be
used, but only for HTML form encoding, which is not the same
as the encoding scheme defined in RFC2396.

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.

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


The connection object is created by invoking the
    openConnection method on a URL.
The setup parameters and general request properties are manipulated.
The actual connection to the remote object is made, using the
   connect method.
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:

  setAllowUserInteraction
  setDoInput
  setDoOutput
  setIfModifiedSince
  setUseCaches


and the general request properties are modified using the method:

  setRequestProperty


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:

  getContent
  getHeaderField
  getInputStream
  getOutputStream


Certain header fields are accessed frequently. The methods:

  getContentEncoding
  getContentLength
  getContentType
  getDate
  getExpiration
  getLastModifed


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/rfc2616.txt

Invoking 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.

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

The 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:


The alphanumeric characters "a" through
    "z", "A" through
    "Z" and "0"
    through "9" remain the same.
The special characters ".",
    "-", "*", and
    "_" remain the same.
The plus sign "+" is converted into a
    space character "   " .
A sequence of the form "%xy" will be
    treated as representing a byte where xy is the two-digit
    hexadecimal representation of the 8 bits. Then, all substrings
    that contain one or more of these byte sequences consecutively
    will be replaced by the character(s) whose encoding would result
    in those consecutive bytes.
    The encoding scheme used to decode these characters may be specified,
    or if unspecified, the default encoding of the platform will be used.


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 IllegalArgumentException.
Which approach the decoder takes is left to the
implementation.

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:


The alphanumeric characters "a" through
    "z", "A" through
    "Z" and "0"
    through "9" remain the same.
The special characters ".",
    "-", "*", and
    "_" remain the same.
The space character "   " is
    converted into a plus sign "+".
All other characters are unsafe and are first converted into
    one or more bytes using some encoding scheme. Then each byte is
    represented by the 3-character string
    "%xy", where xy is the
    two-digit hexadecimal representation of the byte.
    The recommended encoding scheme to use is UTF-8. However,
    for compatibility reasons, if an encoding is not specified,
    then the default encoding of the platform is used.



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).

scheme : // authority [ / path ]

authority = [ userinfo @ ] hostrange [ : portrange ]
portrange = portnumber | -portnumber | portnumber-[portnumber] | *
hostrange = ([*.] dnsname) | IPv4address | IPv6address

    "POST,GET,DELETE"
    "GET:X-Foo-Request,X-Bar-Request"
    "POST,GET:Header1,Header2"

Represents permission to access a resource or set of resources defined by a
given url, and for a given set of user-settable request methods
and request headers. The name of the permission is the url string.
The actions string is a concatenation of the request methods and headers.
The range of method and header names is not restricted by this class.
The url
The url string has the following expected structure.


    scheme : // authority [ / path ]
scheme will typically be http or https, but is not restricted by this
class.
authority is specified as:


    authority = [ userinfo @ ] hostrange [ : portrange ]
    portrange = portnumber | -portnumber | portnumber-[portnumber] | *
    hostrange = ([*.] dnsname) | IPv4address | IPv6address
dnsname is a standard DNS host or domain name, ie. one or more labels
separated by ".". IPv4address is a standard literal IPv4 address and
IPv6address is as defined in
RFC 2732. Literal IPv6 addresses must however, be enclosed in '[]' characters.
The dnsname specification can be preceded by "*." which means
the name will match any hostname whose right-most domain labels are the same as
this name. For example, "*.oracle.com" matches "foo.bar.oracle.com"

portrange is used to specify a port number, or a bounded or unbounded range of ports
that this permission applies to. If portrange is absent or invalid, then a default
port number is assumed if the scheme is http (default 80) or https
(default 443). No default is assumed for other schemes. A wildcard may be specified
which means all ports.

userinfo is optional. A userinfo component if present, is ignored when
creating a URLPermission, and has no effect on any other methods defined by this class.

The path component comprises a sequence of path segments,
separated by '/' characters. path may also be empty. The path is specified
in a similar way to the path in FilePermission. There are
three different ways as the following examples show:

URL Examples
Example urlDescription
http://www.oracle.com/a/b/c.html
  A url which identifies a specific (single) resource

http://www.oracle.com/a/b/*
  The '*' character refers to all resources in the same "directory" - in
      other words all resources with the same number of path components, and
      which only differ in the final path component, represented by the '*'.


http://www.oracle.com/a/b/-
  The '-' character refers to all resources recursively below the
      preceding path (eg. http://www.oracle.com/a/b/c/d/e.html matches this
      example).




The '*' and '-' may only be specified in the final segment of a path and must be
the only character in that segment. Any query or fragment components of the
url are ignored when constructing URLPermissions.

As a special case, urls of the form, "scheme:*" are accepted to
mean any url of the given scheme.

The scheme and authority components of the url string are handled
without regard to case. This means equals(Object),
hashCode() and implies(Permission) are case insensitive with respect
to these components. If the authority contains a literal IP address,
then the address is normalized for comparison. The path component is case sensitive.
The actions string
The actions string of a URLPermission is a concatenation of the method list
and the request headers list. These are lists of the permitted request
methods and permitted request headers of the permission (respectively). The two lists
are separated by a colon ':' character and elements of each list are comma separated.
Some examples are:


        "POST,GET,DELETE"
        "GET:X-Foo-Request,X-Bar-Request"
        "POST,GET:Header1,Header2"
The first example specifies the methods: POST, GET and DELETE, but no request headers.
The second example specifies one request method and two headers. The third
example specifies two request methods, and two headers.

The colon separator need not be present if the request headers list is empty.
No white-space is permitted in the actions string. The action strings supplied to
the URLPermission constructors are case-insensitive and are normalized by converting
method names to upper-case and header names to the form defines in RFC2616 (lower case
with initial letter of each word capitalized). Either list can contain a wild-card '*'
character which signifies all request methods or headers respectively.

Note. Depending on the context of use, some request methods and headers may be permitted
at all times, and others may not be permitted at any time. For example, the
HTTP protocol handler might disallow certain headers such as Content-Length
from being set by application code, regardless of whether the security policy
in force, permits it.

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 or https.

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.

This interface defines a factory for URL stream
protocol handlers.

It is used by the URL class to create a
URLStreamHandler for a specific protocol.