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:

http://www.ncsa.uiuc.edu/demoweb/url-primer.html

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:

http://www.ncsa.uiuc.edu:8080/demoweb/url-primer.html

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

http://local/demo/information#myinfo

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

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

contained within it a reference to the 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. Missing components are inherited from the fully specified URL.

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:

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.

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.¹
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 spec argument does not specify a 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 spec argument does specify a protocol:

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.

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

	openConnection().getContent()

Returns:

the contents of this URL.

Throws

IOException (I-§2.29)

if an I/O exception occurs.

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

	openConnection().getInputStream()

Returns:

a stream for reading from the URL connection.

Throws

IOException (I-§2.29)

If an I/O exception occurs.

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

¹ Step 2 is new in Java 1.1.

Packages  This Package  Prev  Next  Index