net.jini.url.httpmd

Class Handler

java.lang.Object

java.net.URLStreamHandler

net.jini.url.httpmd.Handler

public class Handler
extends URLStreamHandler

A stream handler for URLs with the HTTPMD protocol. HTTPMD URLs provide a way to insure the integrity of data retrieved from an HTTP URL. The HTTPMD URL includes a message digest for the data to be retrieved from the URL. The URL input stream insures that the data has the correct message digest when the end of file for the stream is reached. If the data has the wrong message digest, a WrongMessageDigestException is thrown.

HTTPMD URLs may be used to guarantee the integrity of a downloaded object's codebase if used when specifying the URLs for the JAR files containing the object's classes. Because HTTPMD URLs specify a message digest for a single item, they should not be used for directories of classes.

HTTPMD URLs have a syntax similar to that of HTTP URLs, but include a message digest as the last parameter stored in the last segment of the path. The parameter is introduced by the ';' character, and includes the name of the message digest algorithm, a '=', the message digest, and an optional comment introduced by the ',' character. In addition, a comment by itself may be specified in a relative HTTPMD URL. Comments are ignored when using equals to compare HTTPMD URLs. The comment specified in the context URL is ignored when parsing a relative HTTPMD URL. Adding a comment to an HTTPMD URL is useful in cases where the URL is required to have a particular suffix, for example the ".jar" file extension. A comment-only relative HTTPMD URL is useful when specifying the URL of the containing document from within the contents of the document, where the message digest cannot be specified because it is not yet known.

The message digest algorithm is case-insensitive, and may include ASCII letters and numbers, as well as the following characters:

 - _ . ~ * ' ( ) : @ & + $ ,
 

The value specifies the name of the MessageDigest algorithm to use. For the URL syntax to be valid, the value must be the name of a MessageDigest algorithm as determined by calling MessageDigest.getInstance(String).

The message digest is represented as a positive hexadecimal integer, using digits, and the letters 'a' through 'f', in either lowercase or uppercase.

The characters following the ',' comment character may include ASCII letters and numbers, as well as the following characters:

 - _ . ~ * ' ( ) : @ & = + $ ,
 

Here are some examples of HTTPMD URLs:

• An absolute URL:
  httpmd://www.sun.com/index.html;md5=7be207c7111e459eeea1c9b3d04f1667
• A relative URL:
  index.html;sha=99f6837808c0a79398bf69d83cfb1b82d20cf0cf,Comment
• A comment-only relative URL:
  ,.jar

Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

HttpmdUtil

Implementation Specifics:

This implementation of HTTPMD URLs uses the Logger named net.jini.url.httpmd to log information at the following logging levels:

net.jini.url.httpmd

Level	Description
FAILED	URL input stream detects an incorrect message digest

See the LogManager class for one way to use the FAILED logging level in standard logging configuration files.

Constructor Summary

Constructors

Constructor and Description
Handler() Creates a URL stream handler for HTTPMD URLs.

Method Summary

Modifier and Type	Method and Description
protected int	getDefaultPort() Returns the default port for a URL parsed by this handler, which is 80.
protected int	hashCode(URL u) Computes the hash code for the specified URL.
protected boolean	hostsEqual(URL u1, URL u2) The default superclass implementation performs dns lookup to determine if hosts are equal, this allows two URL's with different hashCode's to be equal, breaking the hashCode equals contract.
protected URLConnection	openConnection(URL u) Creates a HTTP URL connection for an HTTPMD URL.
protected void	parseURL(URL url, String spec, int start, int limit) Parses the string representation of an HTTPMD URL object.
protected boolean	sameFile(URL u1, URL u2) Compares two HTTPMD URLs to see if they refer to the same file.

Methods inherited from class java.net.URLStreamHandler

equals, getHostAddress, openConnection, setURL, setURL, toExternalForm

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Handler

public Handler()

Creates a URL stream handler for HTTPMD URLs.

Method Detail

getDefaultPort

protected int getDefaultPort()

Returns the default port for a URL parsed by this handler, which is 80.

Overrides:

getDefaultPort in class URLStreamHandler

Returns:

the default port for a URL parsed by this handler

openConnection

protected URLConnection openConnection(URL u)
                                throws IOException

Creates a HTTP URL connection for an HTTPMD URL.

Specified by:

openConnection in class URLStreamHandler

Throws:

IOException

parseURL

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

Parses the string representation of an HTTPMD URL object.

Overrides:

parseURL in class URLStreamHandler

Throws:

IllegalArgumentException - if the URL is malformed

hostsEqual

protected boolean hostsEqual(URL u1,
                             URL u2)

The default superclass implementation performs dns lookup to determine if hosts are equal, this allows two URL's with different hashCode's to be equal, breaking the hashCode equals contract. It also causes a test failure in the jtreg test suite. *** Start test: Mon Jan 23 08:11:26 EST 2012 [jtreg] Test 9: TestEqual: httpmd://foo:88/bar/baz;p1=v1;md5=abcd?q#r, httpmd://alpha:88/bar/baz;p1=v1;md5=abcd?q#r [jtreg] FAIL: Should be: false [jtreg] Result: true URL.implies(URL url) is better suited to perform this function, why it was originally implemented in equals is unknown.

Overrides:

hostsEqual in class URLStreamHandler

sameFile

protected boolean sameFile(URL u1,
                           URL u2)

Compares two HTTPMD URLs to see if they refer to the same file. Performs case-insensitive comparison of the protocols and of the message digest parameters (ignoring the comment), calls hostsEqual to compare the hosts, compares the ports, with -1 matching the default HTTP port (80), and performs case-sensitive comparison on the remaining portions.

Overrides:

sameFile in class URLStreamHandler

hashCode

protected int hashCode(URL u)

Computes the hash code for the specified URL. This method ignores the comment portion of the message digest parameter, and ignores the case of characters in the message digest and algorithm.

Overrides:

hashCode in class URLStreamHandler