HTTPClient
Class URI

java.lang.Object
HTTPClient.URI

public class URI

extends java.lang.Object

This class represents a generic URI, as defined in RFC-2396. This is similar to java.net.URL, with the following enhancements:

• it doesn't require a URLStreamhandler to exist for the scheme; this allows this class to be used to hold any URI, construct absolute URIs from relative ones, etc.
• it handles escapes correctly
• equals() works correctly
• relative URIs are correctly constructed
• it has methods for accessing various fields such as userinfo, fragment, params, etc.
• it handles less common forms of resources such as the "*" used in http URLs.

The elements are always stored in escaped form.

While RFC-2396 distinguishes between just two forms of URI's, those that follow the generic syntax and those that don't, this class knows about a third form, named semi-generic, used by quite a few popular schemes. Semi-generic syntax treats the path part as opaque, i.e. has the form <scheme>://<authority>/<opaque> . Relative URI's of this type are only resolved as far as absolute paths - relative paths do not exist.

Ideally, java.net.URL should subclass URI.

Since:

V0.3-1

See Also:

rfc-2396

Field Summary

protected static java.util.BitSet	alphanumChar
protected static java.util.Hashtable	defaultPorts
static boolean	ENABLE_BACKWARDS_COMPATIBILITY If true, then the parser will resolve certain URI's in backwards compatible (but technically incorrect) manner.
static java.util.BitSet	escpdFragChar list of characters which must not be escaped when escaping a fragment identifier
static java.util.BitSet	escpdPathChar list of characters which must not be escaped when escaping a path
static java.util.BitSet	escpdQueryChar list of characters which must not be escaped when escaping a query string
protected java.lang.String	fragment
protected static int	GENERIC
protected java.lang.String	host
protected static java.util.BitSet	hostChar
protected static java.util.BitSet	markChar
protected java.lang.String	opaque
protected static int	OPAQUE
protected static java.util.BitSet	opaqueChar
protected java.lang.String	path
protected static java.util.BitSet	pcharChar
protected int	port
protected java.lang.String	query
protected static java.util.BitSet	reg_nameChar
protected static java.util.BitSet	reservedChar
static java.util.BitSet	resvdHostChar list of characters which must not be unescaped when unescaping a host
static java.util.BitSet	resvdPathChar list of characters which must not be unescaped when unescaping a path
static java.util.BitSet	resvdQueryChar list of characters which must not be unescaped when unescaping a query string
static java.util.BitSet	resvdSchemeChar list of characters which must not be unescaped when unescaping a scheme
static java.util.BitSet	resvdUIChar list of characters which must not be unescaped when unescaping a userinfo
protected java.lang.String	scheme
protected static java.util.BitSet	schemeChar
protected static int	SEMI_GENERIC
protected int	type
protected static java.util.BitSet	unreservedChar
protected static java.util.BitSet	uricChar
protected java.net.URL	url
protected java.lang.String	userinfo
protected static java.util.BitSet	userinfoChar
protected static java.util.Hashtable	usesGenericSyntax
protected static java.util.Hashtable	usesSemiGenericSyntax

Constructor Summary

URI(java.lang.String uri)
Constructs a URI from the given string representation.

URI(java.lang.String scheme, java.lang.String opaque)
Constructs an opaque URI from the given parts.

URI(java.lang.String scheme, java.lang.String host, int port, java.lang.String path)
Constructs a URI from the given parts.

URI(java.lang.String scheme, java.lang.String host, java.lang.String path)
Constructs a URI from the given parts, using the default port for this scheme (if known).

URI(java.lang.String scheme, java.lang.String userinfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment)
Constructs a URI from the given parts.

URI(URI base, java.lang.String rel_uri)
Constructs a URI from the given string representation, relative to the given base URI.

URI(java.net.URL url)
Construct a URI from the given URL.

Method Summary

static java.lang.String	canonicalizePath(java.lang.String path) Remove all "/../" and "/./" from path, where possible.
static int	defaultPort(java.lang.String protocol) Return the default port used by a given protocol.
boolean	equals(java.lang.Object other)
static char[]	escape(char[] elem, java.util.BitSet allowed_char, boolean utf8) Escape any character not in the given character class.
static java.lang.String	escape(java.lang.String elem, java.util.BitSet allowed_char, boolean utf8) Escape any character not in the given character class.
java.lang.String	getFragment()
java.lang.String	getHost()
java.lang.String	getOpaque()
java.lang.String	getPath()
java.lang.String	getPathAndQuery()
int	getPort()
java.lang.String	getQueryString()
java.lang.String	getScheme()
java.lang.String	getUserinfo()
int	hashCode() The hash code is calculated over scheme, host, path, and query.
boolean	isGenericURI() Does the scheme specific part of this URI use the generic-URI syntax?
boolean	isSemiGenericURI() Does the scheme specific part of this URI use the semi-generic-URI syntax?
static void	main(java.lang.String[] args) Run test set.
java.lang.String	toExternalForm()
java.lang.String	toString() Return the URI as string.
java.net.URL	toURL() Will try to create a java.net.URL object from this URI.
static java.lang.String	unescape(java.lang.String str, java.util.BitSet reserved) Unescape escaped characters (i.e.
static boolean	usesGenericSyntax(java.lang.String scheme)
static boolean	usesSemiGenericSyntax(java.lang.String scheme)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ENABLE_BACKWARDS_COMPATIBILITY

public static final boolean ENABLE_BACKWARDS_COMPATIBILITY

If true, then the parser will resolve certain URI's in backwards compatible (but technically incorrect) manner. Example:

 base   = http://a/b/c/d;p?q
 rel    = http:g
 result = http:g                (correct)
 result = http://a/b/c/g        (backwards compatible)

See rfc-2396, section 5.2, step 3, second paragraph.

See Also:

Constant Field Values

defaultPorts

protected static final java.util.Hashtable defaultPorts

usesGenericSyntax

protected static final java.util.Hashtable usesGenericSyntax

usesSemiGenericSyntax

protected static final java.util.Hashtable usesSemiGenericSyntax

alphanumChar

protected static final java.util.BitSet alphanumChar

markChar

protected static final java.util.BitSet markChar

reservedChar

protected static final java.util.BitSet reservedChar

unreservedChar

protected static final java.util.BitSet unreservedChar

uricChar

protected static final java.util.BitSet uricChar

pcharChar

protected static final java.util.BitSet pcharChar

userinfoChar

protected static final java.util.BitSet userinfoChar

schemeChar

protected static final java.util.BitSet schemeChar

hostChar

protected static final java.util.BitSet hostChar

opaqueChar

protected static final java.util.BitSet opaqueChar

reg_nameChar

protected static final java.util.BitSet reg_nameChar

resvdSchemeChar

public static final java.util.BitSet resvdSchemeChar

list of characters which must not be unescaped when unescaping a scheme

resvdUIChar

public static final java.util.BitSet resvdUIChar

list of characters which must not be unescaped when unescaping a userinfo

resvdHostChar

public static final java.util.BitSet resvdHostChar

list of characters which must not be unescaped when unescaping a host

resvdPathChar

public static final java.util.BitSet resvdPathChar

list of characters which must not be unescaped when unescaping a path

resvdQueryChar

public static final java.util.BitSet resvdQueryChar

list of characters which must not be unescaped when unescaping a query string

escpdPathChar

public static final java.util.BitSet escpdPathChar

list of characters which must not be escaped when escaping a path

escpdQueryChar

public static final java.util.BitSet escpdQueryChar

list of characters which must not be escaped when escaping a query string

escpdFragChar

public static final java.util.BitSet escpdFragChar

list of characters which must not be escaped when escaping a fragment identifier

OPAQUE

protected static final int OPAQUE

See Also:

Constant Field Values

SEMI_GENERIC

protected static final int SEMI_GENERIC

See Also:

Constant Field Values

GENERIC

protected static final int GENERIC

See Also:

Constant Field Values

type

protected int type

scheme

protected java.lang.String scheme

opaque

protected java.lang.String opaque

userinfo

protected java.lang.String userinfo

host

protected java.lang.String host

port

protected int port

path

protected java.lang.String path

query

protected java.lang.String query

fragment

protected java.lang.String fragment

url

protected java.net.URL url

Constructor Detail

URI

public URI(java.lang.String uri)
    throws ParseException

Constructs a URI from the given string representation. The string must be an absolute URI.

Parameters:

uri - a String containing an absolute URI

Throws:

ParseException - if no scheme can be found or a specified port cannot be parsed as a number

URI

public URI(URI base,
           java.lang.String rel_uri)
    throws ParseException

Constructs a URI from the given string representation, relative to the given base URI.

Parameters:

base - the base URI, relative to which rel_uri is to be parsed

rel_uri - a String containing a relative or absolute URI

Throws:

ParseException - if base is null and rel_uri is not an absolute URI, or if base is not null and the scheme is not known to use the generic syntax, or if a given port cannot be parsed as a number

URI

public URI(java.net.URL url)
    throws ParseException

Construct a URI from the given URL.

Parameters:

url - the URL

Throws:

ParseException - if url.toExternalForm() generates an invalid string representation

URI

public URI(java.lang.String scheme,
           java.lang.String host,
           java.lang.String path)
    throws ParseException

Constructs a URI from the given parts, using the default port for this scheme (if known). The parts must be in unescaped form.

Parameters:

scheme - the scheme (sometimes known as protocol)

host - the host

path - the path part

Throws:

ParseException - if scheme is null

URI

public URI(java.lang.String scheme,
           java.lang.String host,
           int port,
           java.lang.String path)
    throws ParseException

Constructs a URI from the given parts. The parts must be in unescaped form.

Parameters:

scheme - the scheme (sometimes known as protocol)

host - the host

port - the port

path - the path part

Throws:

ParseException - if scheme is null

URI

public URI(java.lang.String scheme,
           java.lang.String userinfo,
           java.lang.String host,
           int port,
           java.lang.String path,
           java.lang.String query,
           java.lang.String fragment)
    throws ParseException

Constructs a URI from the given parts. Any part except for the the scheme may be null. The parts must be in unescaped form.

Parameters:

scheme - the scheme (sometimes known as protocol)

userinfo - the userinfo

host - the host

port - the port

path - the path part

query - the query string

fragment - the fragment identifier

Throws:

ParseException - if scheme is null

URI

public URI(java.lang.String scheme,
           java.lang.String opaque)
    throws ParseException

Constructs an opaque URI from the given parts.

Parameters:

scheme - the scheme (sometimes known as protocol)

opaque - the opaque part

Throws:

ParseException - if scheme is null

Method Detail

canonicalizePath

public static java.lang.String canonicalizePath(java.lang.String path)

Remove all "/../" and "/./" from path, where possible. Leading "/../"'s are not removed.

Parameters:

path - the path to canonicalize

Returns:

the canonicalized path

usesGenericSyntax

public static boolean usesGenericSyntax(java.lang.String scheme)

Returns:

true if the scheme should be parsed according to the generic-URI syntax

usesSemiGenericSyntax

public static boolean usesSemiGenericSyntax(java.lang.String scheme)

Returns:

true if the scheme should be parsed according to a semi-generic-URI syntax <scheme&tgt;://<hostport>/<opaque>

defaultPort

public static final int defaultPort(java.lang.String protocol)

Return the default port used by a given protocol.

Parameters:

protocol - the protocol

Returns:

the port number, or 0 if unknown

getScheme

public java.lang.String getScheme()

Returns:

the scheme (often also referred to as protocol)

getOpaque

public java.lang.String getOpaque()

Returns:

the opaque part, or null if this URI is generic

getHost

public java.lang.String getHost()

Returns:

the host

getPort

public int getPort()

Returns:

the port, or -1 if it's the default port, or 0 if unknown

getUserinfo

public java.lang.String getUserinfo()

Returns:

the user info

getPath

public java.lang.String getPath()

Returns:

the path

getQueryString

public java.lang.String getQueryString()

Returns:

the query string

getPathAndQuery

public java.lang.String getPathAndQuery()

Returns:

the path and query

getFragment

public java.lang.String getFragment()

Returns:

the fragment

isGenericURI

public boolean isGenericURI()

Does the scheme specific part of this URI use the generic-URI syntax?

In general URI are split into two categories: opaque-URI and generic-URI. The generic-URI syntax is the syntax most are familiar with from URLs such as ftp- and http-URLs, which is roughly:

 generic-URI = scheme ":" [ "//" server ] [ "/" ] [ path_segments ] [ "?" query ]
 

(see RFC-2396 for exact syntax). Only URLs using the generic-URI syntax can be used to create and resolve relative URIs.

Whether a given scheme is parsed according to the generic-URI syntax or wether it is treated as opaque is determined by an internal table of URI schemes.

See Also:

rfc-2396

isSemiGenericURI

public boolean isSemiGenericURI()

Does the scheme specific part of this URI use the semi-generic-URI syntax?

Many schemes which don't follow the full generic syntax actually follow a reduced form where the path part is treated is opaque. This is used for example by ldap, smtp, pop, etc, and is roughly

 generic-URI = scheme ":" [ "//" server ] [ "/" [ opaque_path ] ]
 

I.e. parsing is identical to the generic-syntax, except that the path part is not further parsed. URLs using the semi-generic-URI syntax can be used to create and resolve relative URIs with the restriction that all paths are treated as absolute.

Whether a given scheme is parsed according to the semi-generic-URI syntax is determined by an internal table of URI schemes.

See Also:

isGenericURI()

toURL

public java.net.URL toURL()
                   throws java.net.MalformedURLException

Will try to create a java.net.URL object from this URI.

Returns:

the URL

Throws:

java.net.MalformedURLException - if no handler is available for the scheme

toExternalForm

public java.lang.String toExternalForm()

Returns:

a string representation of this URI suitable for use in links, headers, etc.

toString

public java.lang.String toString()

Return the URI as string. This differs from toExternalForm() in that all elements are unescaped before assembly. This is not suitable for passing to other apps or in header fields and such, and is usually not what you want.

Returns:

the URI as a string

See Also:

toExternalForm()

equals

public boolean equals(java.lang.Object other)

Returns:

true if other is either a URI or URL and it matches the current URI

hashCode

public int hashCode()

The hash code is calculated over scheme, host, path, and query.

Returns:

the hash code

escape

public static java.lang.String escape(java.lang.String elem,
                                      java.util.BitSet allowed_char,
                                      boolean utf8)

Escape any character not in the given character class. Characters greater 255 are always escaped according to ??? .

Parameters:

elem - the string to escape

allowed_char - the BitSet of all allowed characters

utf8 - if true, will first UTF-8 encode unallowed characters

Returns:

the string with all characters not in allowed_char escaped

escape

public static char[] escape(char[] elem,
                            java.util.BitSet allowed_char,
                            boolean utf8)

Escape any character not in the given character class. Characters greater 255 are always escaped according to ??? .

Parameters:

elem - the array of characters to escape

allowed_char - the BitSet of all allowed characters

utf8 - if true, will first UTF-8 encode unallowed characters

Returns:

the elem array with all characters not in allowed_char escaped

unescape

public static final java.lang.String unescape(java.lang.String str,
                                              java.util.BitSet reserved)
                                       throws ParseException

Unescape escaped characters (i.e. %xx) except reserved ones.

Parameters:

str - the string to unescape

reserved - the characters which may not be unescaped, or null

Returns:

the unescaped string

Throws:

ParseException - if the two digits following a `%' are not a valid hex number

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Run test set.

Throws:

java.lang.Exception - if any test fails