Class URL

Package java.net

Previous

Java API

Index

Next

Class URL

Constructors , Methods

public  final  class  java.net.URL
    extends  java.lang.Object  
{
        // Constructors
    public URL(String  spec);	
    public URL(String  protocol, String  host,	
                    int  port, String  file);
    public URL(String  protocol, String  host, String  file);	
    public URL(URL  context, String  spec);	

        // Methods
    public boolean equals(Object  obj);	
    public final Object getContent();	
    public String getFile();	
    public String getHost();	
    public int getPort();	
    public String getProtocol();	
    public String getRef();	
    public int hashCode();	
    public URLConnection openConnection();	
    public final InputStream openStream();	
    public boolean sameFile(URL  other);	
    public static void	
          setURLStreamHandlerFactory(URLStreamHandlerFactory  fac);
    public String toExternalForm();	
    public String toString();	
}

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.

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 with a null first argument.

Parameter Description

spec the String to parse as a URL

Throw:
MalformedURLException
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 , is created for that protocol:
If the application has previously set up an instance of URL--Stream--Handler--Factory 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.
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.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)
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.

Parameter Description

protocol the name of the protocol
host the name of the host
port the port number
file the name of the information

Throws:
MalformedURLException
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 as outlined above in I--§4.8.2.

Parameter Description

protocol the protocol to use
host the host to connect to
file the name of the information

Throw:
MalformedURLException
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 as outlined above in I--§4.8.2. The stream protocol handler's parseURL method is called to parse the remaining fields of the specification that override any defaults set by the context argument.

Parameter Description

context: the context in which to parse the specification
spec a String representation of a URL

Throw:
MalformedURLException
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.
Return Value:
Returns true if the objects are the same; false otherwise.

Parameter Description

obj the URL to compare against

Overrides:
equals in class Object .

getContent

public final Object getContent() 
throws IOException 
Determines the contents of this URL. This method is a shorthand for
	openConnection().getContent() 
Return Value:
Returns the contents of this URL.
Throws:
IOException
if an I/O exception occurs.
See Also: getContent in class URLConnection .

getFile

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

getHost

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

getPort

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

getProtocol

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

getRef

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

hashCode

public int hashCode() 
Return Value:
Returns a hash code for this URL.
Overrides:
hashCode in class Object .

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 of the protocol handler for this URL.
Return Value:
Returns a URLConnection to the URL.
Throw:
IOException
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() 
Return Value:
Returns a stream for reading from the URL connection.
Throws:
IOException
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.
Return Value:
Returns true if they reference the same remote object; false otherwise.

Parameter Description

other the URL to compare against

setURLStreamHandlerFactory

public static void 
setURLStreamHandlerFactory(URLStreamHandlerFactory  fac) 
Sets an application's URLStreamHandlerFactory . This method can be called at most once by an application.
The URLStreamHandlerFactory instance is used to construct a stream protocol handler from a protocol name.

Parameter Description

fac the desired factory

Throw:
Error
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 of the stream protocol handler for this object.
Return Value:
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 and returns its value.
Return Value:
Returns a string representation of this object.
Overrides:
toString in class Object . (1)Step 2 is new in Java 1.1.

Parameter	Description
spec	the String to parse as a URL

Parameter	Description
protocol	the name of the protocol
host	the name of the host
port	the port number
file	the name of the information

Parameter	Description
context:	the context in which to parse the specification
spec	a String representation of a URL

Parameter	Description
other	the URL to compare against