Packages  This Package  Prev  Next  Index  

§4.8 Class URL

public  final  class  java.net.URL
    extends  java.lang.Object  (I-§1.12)
{
        // Constructors
    public URL(String  spec);	§4.8.1
    public URL(String  protocol, String  host,	§4.8.2
                    int  port, String  file);
    public URL(String  protocol, String  host, String  file);	§4.8.3
    public URL(URL  context, String  spec);	§4.8.4

        // Methods
    public boolean equals(Object  obj);	§4.8.5
    public final Object getContent();	§4.8.6
    public String getFile();	§4.8.7
    public String getHost();	§4.8.8
    public int getPort();	§4.8.9
    public String getProtocol();	§4.8.10
    public String getRef();	§4.8.11
    public int hashCode();	§4.8.12
    public URLConnection openConnection();	§4.8.13
    public final InputStream openStream();	§4.8.14
    public boolean sameFile(URL  other);	§4.8.15
    public static void	§4.8.16
          setURLStreamHandlerFactory(URLStreamHandlerFactory  fac);
    public String toExternalForm();	§4.8.17
    public String toString();	§4.8.18
}
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 format can be found at:

In general, an URL can be broken into several parts. The above URL indicates that the protocol to use is http ("HyperText Transport Protocol"), that the information resides on a host whose name is www.ncsa.uiuc.edu. The information on that host machine is named demoweb/url--primer.html. The exact meaning of is name on the host machine is both protocol- and host-dependent. The information could reside in a file or could be generated on- the-fly.

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

A URL may have appended to it an "anchor", which is indicated by the sharp sign character "#" followed by more characters. For example

This 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 "myinfo" 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 URL

contained within it a reference to the URL "FAQ.html", it would be a shorthand for

The relative URL need not specify all the components of a URL. Missing components are inherited from the fully specified URL.


Constructors

URL

public URL(String spec) throws MalformedURLException
Creates a URL object from the String representation.
This constructor is equivalent to a call to the two-argument constructor (I-§4.8.4) with a null first argument.

Parameters:
spec - the String to parse as a URL
Throws
MalformedURLException (I-§4.15)
If the string specifies an unknown protocol.

URL

public URL(String protocol, String host, int port,
String file)
throws MalformedURLException
Creates a URL object from the specified protocol, host, port number, and file.
If this is the first URL object being created with the specified protocol, a stream protocol handler object, an instance of class URL-Stream-Handler (I-§4.11), is created for that protocol:

  1. If the application has previously set up an instance of URL--Stream--Handler--Factory as the stream handler factory (I-§4.8.16), then the createURLStreamHandler (I-§4.14.1) method of that instance is called with the protocol string as an argument to create the stream protocol handler.
  1. 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 (I-§1.18.9)
    java.handler.protol.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 exists, or if it the class exists but it is not a subclass of URL-Stream-Handler, then the next package in the list is tried.1
  2. If the previous step fails to find a protocol handler, then the constructor tries to load the class named
    sun.net.www.protocol.<protocol>.Handler
    If this class does not exist, or if t the class exists but it is not a subclass of URL-Stream-Handler, then a MalformedURLException is thrown.
    Parameters:
    protocol - the name of the protocol
    host - the name of the host
    port - the port number
    file - the name of the information
    Throws
    MalformedURLException (I-§4.15)
    if an unknown protocol is specified.

URL

public URL(String protocol, String host, String file) throws MalformedURLException
Creates an absolute URL from the specified protocol name, host name, and file name. The default port for the specified protocol is used.
The constructor searches for an appropriate URLStreamHandler (I-§4.11) as outlined above in I--§4.8.2.

Parameters:
protocol - the protocol to use
host - the host to connect to
file - the name of the information
Throws
MalformedURLException (I-§4.15)
if an unknown protocol is specified.

URL

public URL(URL context, String spec) throws MalformedURLException
Creates a URL by parsing the String specification within a specified context: If the context argument is not null and the spec argument is a partial URL specification, then any of the strings missing components are inherited from the context argument.
The specification given by the String argument is parsed to determine if it specifies a protocol. If the String contains an ASCII colon ':' character before the first occurrence of of an ASCII slash character '/', then the characters before the colon comprise the protocol.
  • If the context argument isn't null, then the protocol is copied from the context argument.
  • If the context argument is null, then a MalformedURLException is thrown.
  • If the context argument is null, or specifies a different protocol than the specification argument, the context argument is ignored.
  • If the context argument isn't null and specifies the same protocol as the specification, the host, port number, and file are copied from the context argument into the newly created URL.
  • The constructor then searches for an appropriate stream protocol handler of type URLStreamHandler (I-§4.11) as outlined above in I--§4.8.2. The stream protocol handler's parseURL method (I-§4.11.3) is called to parse the remaining fields of the specification that override any defaults set by the context argument.
    
    
    Parameters:
    context: - the context in which to parse the specification
    spec - a String representation of a URL
    Throws
    MalformedURLException (I-§4.15)
    If no protocol is specified, or an unknown protocol is found.

    Methods

    equals

    public boolean equals(Object obj)
    The result is true if and only if the argument is not null and is a URL object that represents the same URL as this object. Two URL objects are equal if they have the same protocol, reference the same host, the same port number on the host, and the same information on the host.
    Parameters:
    obj - the URL to compare against
    Returns:
    true if the objects are the same; false otherwise.
    Overrides:
    equals in class Object (I-§1.12.3).

    getContent

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

    getFile

    public String getFile()
    Returns:
    the information field of this URL.

    getHost

    public String getHost()
    Returns:
    the host name field of this URL.

    getPort

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

    getProtocol

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

    getRef

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

    hashCode

    public int hashCode()
    Returns:
    a hash code for this URL.
    Overrides:
    hashCode in class Object (I-§1.12.6).

    openConnection

    public URLConnection openConnection() throws IOException
    Creates (if not already in existence) a URLConnection object that represents a connection to the remote object referred to by the URL.
    The connection is opened by calling the openConnection method (I-§4.11.2) of the protocol handler (I-§4.8.2) for this URL.
    
    
    Returns:
    a URLConnection (I-§4.9) to the URL.
    Throws
    IOException (I-§2.29)
    If an I/O exception occurs.

    openStream

    public final InputStream openStream() throws IOException
    Opens a connection to this URL and return a stream for reading from that connection. This method is a shorthand for

    sameFile

    public boolean sameFile(URL other)
    Returns true if the this URL and the other argument both refer to the same resource; the two URLs might not both contain the same anchor.
    Parameters:
    other - the URL to compare against
    Returns:
    true if they reference the same remote object; false otherwise.

    setURLStreamHandlerFactory

    public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
    Sets an application's URLStreamHandlerFactory (I-§4.14). This method can be called at most once by an application.
    
    
    
    The URLStreamHandlerFactory instance is used to construct a stream protocol handler (I-§4.8.2) from a protocol name.
    
    
    Parameters:
    fac - the desired factory
    Throws
    Error (I-§1.48)
    If the application has already set a factory.

    toExternalForm

    public String toExternalForm()
    Constructs a string representation of this URL. The string is created by calling the toExternalForm method (I-§4.11.5) of the stream protocol handler (I-§4.8.2) for this object.
    
    
    Returns:
    a string representation of this object.

    toString

    public String toString()
    Creates a string representation of this object. This method calls the to-External-Form method (I-§4.8.17) and returns its value.
    
    
    Returns:
    a string representation of this object.
    Overrides:
    toString in class Object (I-§1.12.9).

    1 Step 2 is new in Java 1.1.

    Packages  This Package  Prev  Next  Index
    Java API Document (HTML generated by dkramer on April 22, 1996)
    Copyright © 1996 Sun Microsystems, Inc. All rights reserved
    Please send any comments or corrections to doug.kramer@sun.com