Chapter 15
The java.net Package

URLStreamHandler

Name

URLStreamHandler

Synopsis

Class Name:

java.net.URLStreamHandler

Superclass:

java.lang.Object

Immediate Subclasses:

None

Interfaces Implemented:

None

Availability:

JDK 1.0 or later

The URLStreamHandler class is an abstract class that defines methods that encapsulate protocol-specific behavior. A stream handler protocol knows how to establish a connection for a particular protocol and how to parse the protocol-specific portion of a URL. An application does not normally create a URLStreamHandler directly; the appropriate subclass of URLStreamHandler is created by a URLStreamHandlerFactory.

The main purpose of a subclass of URLStreamHandler is to create a URLConnection object for a given URL. The URLStreamHandler object creates an object of the appropriate subclass of URLConnection for the protocol type specified by the URL. In order for a URL object to handle a protocol type such as http, ftp, or nntp, it needs an object of the appropriate subclass of URLStreamHandler to handle the protocol-specific details.

Class Summary

public abstract class java.net.URLStreamHandler extends java.lang.Object {
  // Protected Instance Methods
  protected abstract URLConnection openConnection(URL u) 
  protected void parseURL(URL u, String spec, int start, int limit);
  protected void setURL(URL u, String protocol, String host, 
                        int port, String file, String ref);
  protected String toExternalForm(URL u);
}

Protected Instance Methods

openConnection

 protected abstract URLConnection openConnection(URL u) throws IOException

Parameters

u: The URL being connected to.

Returns

The URLConnection object for the given URL.

Throws

IOException: If any kind of I/O error occurs.

Description

This method handles the protocol-specific details of establishing a connection to a remote resource specified by the URL. The connection should be handled just up to the point where the resource data can be downloaded. A ContentHandler then takes care of downloading the data and creating an appropriate object.

A subclass of URLStreamHandler must implement this method.

parseURL

protected void parseURL(URL u, String spec, int start, int limit)

Parameters

u

A reference to a URL object that receives the results of parsing.

spec

The string representation of a URL to be parsed.

start

The offset at which to begin parsing the protocol-specific portion of the URL.

limit

The offset of the last character that is to be parsed.

Description

This method parses the string representation of a URL into a URL object.

Some parts of the URL object may already be specified if spec specifies a relative URL. However, values for those parts in spec can override the inherited context.

The method only parses the protocol-specific portion of the URL. In other words, start should specify the character immediately after the first colon (:), which marks the termination of the protocol type, and limit should either be the last character in the string or the first pound sign (#), which marks the beginning of a protocol-independent anchor. Rather than return a result, the method calls the set() method of the specified URL object to set its fields to the appropriate values.

The implementation of the parseURL() method in URLStreamHandler parses the string representation as if it were an http specification. A subclass that implements a protocol stream handler for a different protocol must override this method to properly parse the URL.

setURL

 protected void setURL(URL u, String protocol, String host, int port, String file, String ref)

Parameters

u

A reference to a URL object to be modified.

protocol

A protocol.

host

A hostname.

port

A port number.

file

A filename.

ref

A reference.

Description

This method sets the protocol, hostname, port number, filename, and reference of the given URL to the specified values by calling the set() method of the URL. Only subclasses of URLStreamHandler are allowed to call the set() method of a URL object.

toExternalForm

protected String toExternalForm(URL u)

Parameters

u: The URL object to convert to a string representation.

Returns

A string representation of the given URL.

Description

This method unparses a URL object and returns a string representation of the URL.

The implementation of the toExternalForm() method in URLStreamHandler returns a string representation that is appropriate for an http specification. A subclass that implements a protocol stream handler for a different protocol must override this method to create a correct string representation.

Inherited Methods

Method	Inherited From	Method	Inherited From
`clone()`	`Object`	`equals(Object)`	`Object`
`finalize()`	`Object`	`getClass()`	`Object`
`hashCode()`	`Object`	`notify()`	`Object`
`notifyAll()`	`Object`	`toString()`	`Object`
`wait()`	`Object`	`wait(long)`	`Object`
`wait(long, int)`	`Object`