java.net
Class URL

java.lang.Object
  |
  +--java.net.URL
All Implemented Interfaces:
Serializable

public final class URL
extends Object
implements Serializable

Untamed:

See Also:
Serialized Form

Field Summary
private  String authority
          The authority part of this URL.
(package private) static URLStreamHandlerFactory factory
          The URLStreamHandler factory.
private  String file
          The specified file name on that host.
(package private)  URLStreamHandler handler
          The URLStreamHandler for this URL.
(package private) static Hashtable handlers
          A table of protocol handlers.
private  int hashCode
           
private  String host
          The host name to connect to.
(package private)  InetAddress hostAddress
          The host's IP address, used in equals and hashCode.
private  String path
          The path part of this URL.
private  int port
          The protocol port to connect to.
private  String protocol
          The protocol to use (ftp, http, nntp, ...
private static String protocolPathProp
          The property which specifies the package prefix list to be scanned for protocol handlers.
private  String query
          The query part of this URL.
private  String ref
          # reference.
(package private) static long serialVersionUID
           
private static NetPermission specifyHandlerPerm
           
private static Object streamHandlerLock
           
private  String userInfo
          The userinfo part of this URL.
 
Constructor Summary
  URL(String spec)
          Enabled: Creates a URL object from the String representation.
private URL(String protocol, String host, int port, Parts parts, URLStreamHandler handler)
          No validation of the inputs is performed by this constructor.
  URL(String protocol, String host, int port, String file)
          Enabled: Creates a URL object from the specified protocol, host, port number, and file.
  URL(String protocol, String host, int port, String file, URLStreamHandler handler)
          Enabled: Creates a URL object from the specified protocol, host, port number, file, and handler.
  URL(String protocol, String host, String file)
          Enabled: Creates a URL from the specified protocol name, host name, and file name.
(package private) URL(String protocol, String opaquePart, String authority, String userInfo, String host, int port, String path, String query, String ref, URLStreamHandler handler)
          A package private constructor that takes all URL components.
  URL(URL context, String spec)
          Enabled: Creates a URL by parsing the given spec within a specified context.
  URL(URL context, String spec, URLStreamHandler handler)
          Enabled: Creates a URL by parsing the given spec with the specified handler within a specified context.
 
Method Summary
 void __printOn(TextWriter out)
          Added: E URIs have angle brackets around them
private  void checkSpecifyHandler(SecurityManager sm)
           
 boolean equals(Object obj)
          Suppressed: Compares this URL for equality with another object.
 URL get(String suffix)
          Added: "implements" org.erights.e.elib.serial.Loader#get, but only if the body of this URL ends in a "/".
 String getAuthority()
          Enabled: Gets the authority part of this URL.
 String getBody()
          Added: Everything after 'protocol:'.
 Object getContent()
          Enabled: Gets the contents of this URL.
 Object getContent(Class[] classes)
          Enabled: Gets the contents of this URL.
 BigInteger getCryptoHash()
          Added: A SHA hash of the binary content of the URL's contents.
 int getDefaultPort()
          Enabled: Gets the default port number of the protocol associated with this URL.
 String getFile()
          Enabled: Gets the file name of this URL.
 String getHost()
          Enabled: Gets the host name of this URL, if applicable.
 String getPath()
          Enabled: Gets the path part of this URL.
 int getPort()
          Enabled: Gets the port number of this URL.
 String getProtocol()
          Enabled: Gets the protocol name of this URL.
 String getQuery()
          Enabled: Gets the query part of this URL.
 String getRef()
          Enabled: Gets the anchor (also known as the "reference") of this URL.
 String getText()
          Added: Gets the contents of the url as String, normalizing newlines into '\n's.
 Twine getTwine()
          Added: Gets the contents of the url as Twine (a text string that remembers where it came from), normalizing newlines into '\n's.
(package private) static URLStreamHandler getURLStreamHandler(String protocol)
          Returns the Stream Handler.
 String getUserInfo()
          Enabled: Gets the userInfo part of this URL.
 int hashCode()
          Suppressed: Creates an integer suitable for hash table indexing.
private  boolean isValidProtocol(String protocol)
           
 void iterate(AssocFunc func)
          Added: Enumerates lineNumber => String (text line) associations.
 void iterate(AssocFunc func, boolean isLocated)
          Added: Enumerates lineNumber => String/Twine (text line) associations.
 URLConnection openConnection()
          Enabled: Returns a URLConnection object that represents a connection to the remote object referred to by the URL.
 InputStream openStream()
          Enabled: Opens a connection to this URL and returns an InputStream for reading from that connection.
 Object[] optUncall(Object obj)
          Added: "implements" org.erights.e.elib.serial.Loader#optUncall, but only if the body of this URL ends in a "/".
private  void readObject(ObjectInputStream s)
          readObject is called to restore the state of the URL from the stream.
 boolean sameFile(URL other)
          Enabled: Compares two URLs, excluding the fragment component.
protected  void set(String protocol, String host, int port, String file, String ref)
          Sets the fields of the URL.
protected  void set(String protocol, String host, int port, String authority, String userInfo, String path, String query, String ref)
          Sets the specified 8 fields of the URL.
static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
          Enabled: Sets an application's URLStreamHandlerFactory.
 BufferedReader textReader()
          Added: Open 'self' for reading text, decoding UTF-8 and turning platform newlines into '\n's
 String toExternalForm()
          Enabled: Constructs a string representation of this URL.
 String toString()
          Suppressed: Constructs a string representation of this URL.
private  void writeObject(ObjectOutputStream s)
          WriteObject is called to save the state of the URL to an ObjectOutputStream.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

static final long serialVersionUID

protocolPathProp

private static final String protocolPathProp
The property which specifies the package prefix list to be scanned for protocol handlers. The value of this property (if any) should be a vertical bar delimited list of package names to search through for a protocol handler to load. The policy of this class is that all protocol handlers will be in a class called .Handler, and each package in the list is examined in turn for a matching handler. If none are found (or the property is not specified), the default package prefix, sun.net.www.protocol, is used. The search proceeds from the first package in the list to the last and stops when a match is found.


protocol

private String protocol
The protocol to use (ftp, http, nntp, ... etc.) .


host

private String host
The host name to connect to.


port

private int port
The protocol port to connect to.


file

private String file
The specified file name on that host. file is defined as path[?query]


query

private transient String query
The query part of this URL.


authority

private String authority
The authority part of this URL.


path

private transient String path
The path part of this URL.


userInfo

private transient String userInfo
The userinfo part of this URL.


ref

private String ref
# reference.


hostAddress

transient InetAddress hostAddress
The host's IP address, used in equals and hashCode. Computed on demand. An uninitialized or unknown hostAddress is null.


handler

transient URLStreamHandler handler
The URLStreamHandler for this URL.


hashCode

private int hashCode

specifyHandlerPerm

private static NetPermission specifyHandlerPerm

factory

static URLStreamHandlerFactory factory
The URLStreamHandler factory.


handlers

static Hashtable handlers
A table of protocol handlers.


streamHandlerLock

private static Object streamHandlerLock
Constructor Detail

URL

public URL(String protocol,
           String host,
           int port,
           String file)
    throws MalformedURLException
Enabled: Creates a URL object from the specified protocol, host, port number, and file.

host can be expressed as a host name or a literal IP address. If IPv6 literal address is used, it should be enclosed in square brackets ('[' and ']'), as specified by RFC 2732; However, the literal IPv6 address format defined in RFC 2373: IP Version 6 Addressing Architecture is also accepted.

Specifying a port number of -1 indicates that the URL should use the default port for the protocol.

If this is the first URL object being created with the specified protocol, a stream protocol handler object, an instance of class URLStreamHandler, is created for that protocol:

  1. If the application has previously set up an instance of URLStreamHandlerFactory as the stream handler factory, then the createURLStreamHandler method of that instance is called with the protocol string as an argument to create the stream protocol handler.
  2. If no URLStreamHandlerFactory has yet been set up, or if the factory's createURLStreamHandler method returns null, then the constructor finds the value of the system property:
             java.protocol.handler.pkgs
         
    If the value of that system property is not null, it is interpreted as a list of packages separated by a vertical slash character '|'. The constructor tries to load the class named:
             <package>.<protocol>.Handler
         
    where <package> is replaced by the name of the package and <protocol> is replaced by the name of the protocol. If this class does not exist, or if the class exists but it is not a subclass of URLStreamHandler, then the next package in the list is tried.
  3. If the previous step fails to find a protocol handler, then the constructor tries to load from a system default package.
             <system default package>.<protocol>.Handler
         
    If this class does not exist, or if the class exists but it is not a subclass of URLStreamHandler, then a MalformedURLException is thrown.

No validation of the inputs is performed by this constructor.

Parameters:
protocol - the name of the protocol to use.
host - the name of the host.
port - the port number on the host.
file - the file on the host
See Also:
java.lang.System#getProperty(java.lang.String), java.net.URL#setURLStreamHandlerFactory( java.net.URLStreamHandlerFactory), java.net.URLStreamHandler, java.net.URLStreamHandlerFactory#createURLStreamHandler( java.lang.String)

URL

public URL(String protocol,
           String host,
           String file)
    throws MalformedURLException
Enabled: Creates a URL from the specified protocol name, host name, and file name. The default port for the specified protocol is used.

This method is equivalent to calling the four-argument constructor with the arguments being protocol, host, -1, and file. No validation of the inputs is performed by this constructor.

Parameters:
protocol - the name of the protocol to use.
host - the name of the host.
file - the file on the host.
See Also:
java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)

URL

public URL(String protocol,
           String host,
           int port,
           String file,
           URLStreamHandler handler)
    throws MalformedURLException
Enabled: Creates a URL object from the specified protocol, host, port number, file, and handler. Specifying a port number of -1 indicates that the URL should use the default port for the protocol. Specifying a handler of null indicates that the URL should use a default stream handler for the protocol, as outlined for: java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)

If the handler is not null and there is a security manager, the security manager's checkPermission method is called with a NetPermission("specifyStreamHandler") permission. This may result in a SecurityException. No validation of the inputs is performed by this constructor.

Parameters:
protocol - the name of the protocol to use.
host - the name of the host.
port - the port number on the host.
file - the file on the host
handler - the stream handler for the URL.
See Also:
java.lang.System#getProperty(java.lang.String), java.net.URL#setURLStreamHandlerFactory( java.net.URLStreamHandlerFactory), java.net.URLStreamHandler, java.net.URLStreamHandlerFactory#createURLStreamHandler( java.lang.String), SecurityManager.checkPermission(java.security.Permission), java.net.NetPermission

URL

private URL(String protocol,
            String host,
            int port,
            Parts parts,
            URLStreamHandler handler)
     throws MalformedURLException
No validation of the inputs is performed by this constructor.


URL

URL(String protocol,
    String opaquePart,
    String authority,
    String userInfo,
    String host,
    int port,
    String path,
    String query,
    String ref,
    URLStreamHandler handler)
throws MalformedURLException
A package private constructor that takes all URL components. No validation of the inputs is performed by this constructor.

Parameters:
protocol - Protocol name
opaquePart -
authority -
userInfo - User name and authorization information
host - Host name
port - Port number
path - Path
query - Query
ref - Fragment
Since:
1.4

URL

public URL(String spec)
    throws MalformedURLException
Enabled: Creates a URL object from the String representation.

This constructor is equivalent to a call to the two-argument constructor with a null first argument.

Parameters:
spec - the String to parse as a URL.
See Also:
java.net.URL#URL(java.net.URL, java.lang.String)

URL

public URL(URL context,
           String spec)
    throws MalformedURLException
Enabled: Creates a URL by parsing the given spec within a specified context. The new URL is created from the given context URL and the spec argument as described in RFC2396 "Uniform Resource Identifiers : Generic * Syntax" :
          <scheme>://<authority><path>?<query>#<fragment>
 
The reference is parsed into the scheme, authority, path, query and fragment parts. If the path component is empty and the scheme, authority, and query components are undefined, then the new URL is a reference to the current document. Otherwise, the fragment and query parts present in the spec are used in the new URL.

If the scheme component is defined in the given spec and does not match the scheme of the context, then the new URL is created as an absolute URL based on the spec alone. Otherwise the scheme component is inherited from the context URL.

If the authority component is present in the spec then the spec is treated as absolute and the spec authority and path will replace the context authority and path. If the authority component is absent in the spec then the authority of the new URL will be inherited from the context.

If the spec's path component begins with a slash character "/" then the path is treated as absolute and the spec path replaces the context path.

Otherwise, the path is treated as a relative path and is appended to the context path, as described in RFC2396. Also, in this case, the path is canonicalized through the removal of directory changes made by occurences of ".." and ".".

For a more detailed description of URL parsing, refer to RFC2396.

Parameters:
context - the context in which to parse the specification.
spec - the String to parse as a URL.
See Also:
java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String), java.net.URLStreamHandler, java.net.URLStreamHandler#parseURL(java.net.URL, java.lang.String, int, int)

URL

public URL(URL context,
           String spec,
           URLStreamHandler handler)
    throws MalformedURLException
Enabled: Creates a URL by parsing the given spec with the specified handler within a specified context. If the handler is null, the parsing occurs as with the two argument constructor.

Parameters:
context - the context in which to parse the specification.
spec - the String to parse as a URL.
handler - the stream handler for the URL.
See Also:
java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String), java.net.URLStreamHandler, java.net.URLStreamHandler#parseURL(java.net.URL, java.lang.String, int, int)
Method Detail

isValidProtocol

private boolean isValidProtocol(String protocol)

checkSpecifyHandler

private void checkSpecifyHandler(SecurityManager sm)

set

protected void set(String protocol,
                   String host,
                   int port,
                   String file,
                   String ref)
Sets the fields of the URL. This is not a public method so that only URLStreamHandlers can modify URL fields. URLs are otherwise constant.

Parameters:
protocol - the name of the protocol to use
host - the name of the host
port - the port number on the host
file - the file on the host
ref - the internal reference in the URL

set

protected void set(String protocol,
                   String host,
                   int port,
                   String authority,
                   String userInfo,
                   String path,
                   String query,
                   String ref)
Sets the specified 8 fields of the URL. This is not a public method so that only URLStreamHandlers can modify URL fields. URLs are otherwise constant.

Parameters:
protocol - the name of the protocol to use
host - the name of the host
port - the port number on the host
authority - the authority part for the url
userInfo - the username and password
path - the file on the host
ref - the internal reference in the URL
query - the query part of this URL
Since:
1.3

getQuery

public String getQuery()
Enabled: Gets the query part of this URL.

Returns:
the query part of this URL, or null if one does not exist
Since:
1.3

getPath

public String getPath()
Enabled: Gets the path part of this URL.

Returns:
the path part of this URL, or an empty string if one does not exist
Since:
1.3

getUserInfo

public String getUserInfo()
Enabled: Gets the userInfo part of this URL.

Returns:
the userInfo part of this URL, or null if one does not exist

getAuthority

public String getAuthority()
Enabled: Gets the authority part of this URL.

Returns:
the authority part of this URL
Since:
1.3

getPort

public int getPort()
Enabled: Gets the port number of this URL.

Returns:
the port number, or -1 if the port is not set

getDefaultPort

public int getDefaultPort()
Enabled: Gets the default port number of the protocol associated with this URL. If the URL scheme or the URLStreamHandler for the URL do not define a default port number, then -1 is returned.

Returns:
the port number

getProtocol

public String getProtocol()
Enabled: Gets the protocol name of this URL.

Returns:
the protocol of this URL.

getHost

public String getHost()
Enabled: Gets the host name of this URL, if applicable. The format of the host conforms to RFC 2732, i.e. for a literal IPv6 address, this method will return the IPv6 address enclosed in square brackets ('[' and ']').

Returns:
the host name of this URL.

getFile

public String getFile()
Enabled: 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.

Returns:
the file name of this URL, or an empty string if one does not exist

getRef

public String getRef()
Enabled: Gets the anchor (also known as the "reference") of this URL.

Returns:
the anchor (also known as the "reference") of this URL, or null if one does not exist

equals

public boolean equals(Object obj)
Suppressed: Compares this URL for equality with another object.

If the given object is not a URL then this method immediately returns false.

Two URL objects are equal if they have the same protocol, reference equivalent hosts, have the same port number on the host, and the same file and fragment of the file.

Two hosts are considered equivalent if both host names can be resolved into the same IP addresses; else if either host name can't be resolved, the host names must be equal without regard to case; or both host names equal to null.

Since hosts comparison requires name resolution, this operation is a blocking operation.

Note: The defined behavior for equals is known to be inconsistent with virtual hosting in HTTP.

Overrides:
equals in class Object
Parameters:
obj - the URL to compare against.
Returns:
true if the objects are the same; false otherwise.
See Also:
Object.hashCode(), java.util.Hashtable

hashCode

public int hashCode()
Suppressed: Creates an integer suitable for hash table indexing.

The hash code is based upon all the URL components relevant for URL comparison. As such, this operation is a blocking operation.

Overrides:
hashCode in class Object
Returns:
a hash code for this URL.
See Also:
java.lang.Object#equals(java.lang.Object), java.util.Hashtable

sameFile

public boolean sameFile(URL other)
Enabled: Compares two URLs, excluding the fragment component.

Returns true if this URL and the other argument are equal without taking the fragment component into consideration.

Parameters:
other - the URL to compare against.
Returns:
true if they reference the same remote object; false otherwise.

toString

public String toString()
Suppressed: Constructs a string representation of this URL. The string is created by calling the toExternalForm method of the stream protocol handler for this object.

Overrides:
toString in class Object
Returns:
a string representation of this object.
See Also:
java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String), java.net.URLStreamHandler#toExternalForm(java.net.URL)

toExternalForm

public String toExternalForm()
Enabled: Constructs a string representation of this URL. The string is created by calling the toExternalForm method of the stream protocol handler for this object.

Returns:
a string representation of this object.
See Also:
java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String), java.net.URLStreamHandler#toExternalForm(java.net.URL)

openConnection

public URLConnection openConnection()
                             throws IOException
Enabled: Returns a URLConnection object that represents a connection to the remote object referred to by the URL.

A new connection is opened every time by calling the openConnection method of the protocol handler for this URL.

If for the URL's protocol (such as HTTP or JAR), there exists a public, specialized URLConnection subclass belonging to one of the following packages or one of their subpackages: java.lang, java.io, java.util, java.net, the connection returned will be of that subclass. For example, for HTTP an HttpURLConnection will be returned, and for JAR a JarURLConnection will be returned.

Returns:
a URLConnection to the URL.
IOException
See Also:
java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String), java.net.URLConnection, java.net.URLStreamHandler#openConnection(java.net.URL)

openStream

public final InputStream openStream()
                             throws IOException
Enabled: Opens a connection to this URL and returns an InputStream for reading from that connection. This method is a shorthand for:
     openConnection().getInputStream()
 

Returns:
an input stream for reading from the URL connection.
IOException
See Also:
java.net.URL#openConnection(), java.net.URLConnection#getInputStream()

getContent

public final Object getContent()
                        throws IOException
Enabled: Gets the contents of this URL. This method is a shorthand for:
     openConnection().getContent()
 

Returns:
the contents of this URL.
IOException
See Also:
java.net.URLConnection#getContent()

getContent

public final Object getContent(Class[] classes)
                        throws IOException
Enabled: Gets the contents of this URL. This method is a shorthand for:
     openConnection().getContent(Class[])
 

Parameters:
classes - an array of Java types
Returns:
the content object of this URL that is the first match of the types specified in the classes array. null if none of the requested types are supported.
IOException
Since:
1.3
See Also:
java.net.URLConnection#getContent(Class[])

setURLStreamHandlerFactory

public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
Enabled: Sets an application's URLStreamHandlerFactory. This method can be called at most once in a given Java Virtual Machine.

The URLStreamHandlerFactory instance is used to construct a stream protocol handler from a protocol name.

If there is a security manager, this method first calls the security manager's checkSetFactory method to ensure the operation is allowed. This could result in a SecurityException.

Parameters:
fac - the desired factory.
See Also:
java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String), java.net.URLStreamHandlerFactory, SecurityManager.checkSetFactory()

getURLStreamHandler

static URLStreamHandler getURLStreamHandler(String protocol)
Returns the Stream Handler.

Parameters:
protocol - the protocol to use

writeObject

private void writeObject(ObjectOutputStream s)
                  throws IOException
WriteObject is called to save the state of the URL to an ObjectOutputStream. The handler is not saved since it is specific to this system.

IOException

readObject

private void readObject(ObjectInputStream s)
                 throws IOException,
                        ClassNotFoundException
readObject is called to restore the state of the URL from the stream. It reads the components of the URL and finds the local stream handler.

IOException
ClassNotFoundException

get

public URL get(String suffix)
Added: "implements" org.erights.e.elib.serial.Loader#get, but only if the body of this URL ends in a "/".

Parameters:
suffix -
Returns:

__printOn

public void __printOn(TextWriter out)
               throws IOException
Added: E URIs have angle brackets around them

IOException

iterate

public void iterate(AssocFunc func,
                    boolean isLocated)
             throws IOException
Added: Enumerates lineNumber => String/Twine (text line) associations.

Each text line ends with a "\n".

IOException

iterate

public void iterate(AssocFunc func)
             throws IOException
Added: Enumerates lineNumber => String (text line) associations.

Each text line ends with a "\n". isLocated defaults to false.

IOException

optUncall

public Object[] optUncall(Object obj)
Added: "implements" org.erights.e.elib.serial.Loader#optUncall, but only if the body of this URL ends in a "/".

Parameters:
obj -
Returns:

textReader

public BufferedReader textReader()
                          throws IOException
Added: Open 'self' for reading text, decoding UTF-8 and turning platform newlines into '\n's

IOException

getText

public String getText()
               throws IOException
Added: Gets the contents of the url as String, normalizing newlines into '\n's.

IOException

getTwine

public Twine getTwine()
               throws IOException
Added: Gets the contents of the url as Twine (a text string that remembers where it came from), normalizing newlines into '\n's.

IOException

getCryptoHash

public BigInteger getCryptoHash()
                         throws NoSuchAlgorithmException,
                                IOException
Added: A SHA hash of the binary content of the URL's contents.

NoSuchAlgorithmException
IOException

getBody

public String getBody()
Added: Everything after 'protocol:'.

Returns:


comments?