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: