org.wymiwyg.commons.util

Class URI

java.lang.Object

org.wymiwyg.commons.util.URI

All Implemented Interfaces:

Serializable

public class URI
extends Object
implements Serializable

A class to represent a Uniform Resource Identifier (URI). This class is designed to handle the parsing of URIs and provide access to the various components (scheme, host, port, userinfo, path, query string and fragment) that may constitute a URI.

Parsing of a URI specification is done according to the URI syntax described in RFC 2396 . Every URI consists of a scheme, followed by a colon (':'), followed by a scheme-specific part. For URIs that follow the "generic URI" syntax, the scheme- specific part begins with two slashes ("//") and may be followed by an authority segment (comprised of user information, host, and port), path segment, query segment and fragment. Note that RFC 2396 no longer specifies the use of the parameters segment and excludes the "user:password" syntax as part of the authority segment. If "user:password" appears in a URI, the entire user/password string is stored as userinfo.

For URIs that do not follow the "generic URI" syntax (e.g. mailto), the entire scheme-specific part is treated as the "path" portion of the URI.

Note that, unlike the java.net.URL class, this class does not provide any built-in network access functionality nor does it provide any scheme-specific functionality (for example, it does not know a default port for a specific scheme). Rather, it only knows the grammar and basic set of operations that can be applied to a URI.

Version:

$Id: URI.java,v 1.2 2004/07/06 05:20:50 rebach Exp $

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	ABSOLUTE
static int	GRANDPARENT
static int	NETWORK
static int	PARENT
static int	RELATIVE
static int	SAMEDOCUMENT

Constructor Summary

Constructors

Constructor and Description
URI() Construct a new and uninitialized URI.
URI(String p_uriSpec) Construct a new URI from a URI specification string.
URI(String p_scheme, String p_schemeSpecificPart) Construct a new URI that does not follow the generic URI syntax.
URI(String p_scheme, String p_userinfo, String p_host, int p_port, String p_path, String p_queryString, String p_fragment) Construct a new URI that follows the generic URI syntax from its component parts.
URI(String p_scheme, String p_host, String p_path, String p_queryString, String p_fragment) Construct a new URI that follows the generic URI syntax from its component parts.
URI(URI p_other) Construct a new URI from another URI.
URI(URI p_base, String p_uriSpec) Construct a new URI from a base URI and a URI specification string.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(Object p_test) Determines if the passed-in Object is equivalent to this URI.
static String	flags2str(int f)
String	getFragment() Get the fragment for this URI.
String	getHost() Get the host for this URI.
String	getPath() Get the path for this URI.
String	getPath(boolean p_includeQueryString, boolean p_includeFragment) Get the path for this URI (optionally with the query string and fragment).
int	getPort() Get the port for this URI.
String	getQueryString() Get the query string for this URI.
String	getScheme() Get the scheme for this URI.
String	getSchemeSpecificPart() Get the scheme-specific part for this URI (everything following the scheme and the first colon).
String	getURIString() Get the URI as a string specification.
String	getUserinfo() Get the userinfo for this URI.
int	hashCode()
static boolean	isConformantSchemeName(String p_scheme) Determine whether a scheme conforms to the rules for a scheme name.
boolean	isGenericURI() Get the indicator as to whether this URI uses the "generic URI" syntax.
boolean	isNormalFormC()
static boolean	isWellFormedAddress(String p_address) Determine whether a string is syntactically capable of representing a valid IPv4 address or the domain name of a network host.
String	relativize(String abs, int flags)
void	setFragment(String p_fragment) Set the fragment for this URI.
static int	str2flags(String pv)
String	toString() produce a human-consumable string for the URI

Methods inherited from class java.lang.Object

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

Field Detail

SAMEDOCUMENT

public static final int SAMEDOCUMENT

See Also:

Constant Field Values

NETWORK

public static final int NETWORK

See Also:

Constant Field Values

ABSOLUTE

public static final int ABSOLUTE

See Also:

Constant Field Values

RELATIVE

public static final int RELATIVE

See Also:

Constant Field Values

PARENT

public static final int PARENT

See Also:

Constant Field Values

GRANDPARENT

public static final int GRANDPARENT

See Also:

Constant Field Values

Constructor Detail

URI

public URI()

Construct a new and uninitialized URI.

URI

public URI(URI p_other)

Construct a new URI from another URI. All fields for this URI are set equal to the fields of the URI passed in.

Parameters:

p_other - the URI to copy (cannot be null)

URI

public URI(String p_uriSpec)
    throws MalformedURIException

Construct a new URI from a URI specification string. If the specification follows the "generic URI" syntax, (two slashes following the first colon), the specification will be parsed accordingly - setting the scheme, userinfo, host,port, path, query string and fragment fields as necessary. If the specification does not follow the "generic URI" syntax, the specification is parsed into a scheme and scheme-specific part (stored as the path) only.

Parameters:

p_uriSpec - the URI specification string (cannot be null or empty)

Throws:

MalformedURIException - if p_uriSpec violates any syntax rules

URI

public URI(URI p_base,
   String p_uriSpec)
    throws MalformedURIException

Construct a new URI from a base URI and a URI specification string. The URI specification string may be a relative URI.

Parameters:

p_base - the base URI (cannot be null if p_uriSpec is null or empty)

p_uriSpec - the URI specification string (cannot be null or empty if p_base is null)

Throws:

MalformedURIException - if p_uriSpec violates any syntax rules

URI

public URI(String p_scheme,
   String p_schemeSpecificPart)
    throws MalformedURIException

Construct a new URI that does not follow the generic URI syntax. Only the scheme and scheme-specific part (stored as the path) are initialized.

Parameters:

p_scheme - the URI scheme (cannot be null or empty)

p_schemeSpecificPart - the scheme-specific part (cannot be null or empty)

Throws:

MalformedURIException - if p_scheme violates any syntax rules

URI

public URI(String p_scheme,
   String p_host,
   String p_path,
   String p_queryString,
   String p_fragment)
    throws MalformedURIException

Construct a new URI that follows the generic URI syntax from its component parts. Each component is validated for syntax and some basic semantic checks are performed as well. See the individual setter methods for specifics.

Parameters:

p_scheme - the URI scheme (cannot be null or empty)

p_host - the hostname or IPv4 address for the URI

p_path - the URI path - if the path contains '?' or '#', then the query string and/or fragment will be set from the path; however, if the query and fragment are specified both in the path and as separate parameters, an exception is thrown

p_queryString - the URI query string (cannot be specified if path is null)

p_fragment - the URI fragment (cannot be specified if path is null)

Throws:

MalformedURIException - if any of the parameters violates syntax rules or semantic rules

URI

public URI(String p_scheme,
   String p_userinfo,
   String p_host,
   int p_port,
   String p_path,
   String p_queryString,
   String p_fragment)
    throws MalformedURIException

Construct a new URI that follows the generic URI syntax from its component parts. Each component is validated for syntax and some basic semantic checks are performed as well. See the individual setter methods for specifics.

Parameters:

p_scheme - the URI scheme (cannot be null or empty)

p_userinfo - the URI userinfo (cannot be specified if host is null)

p_host - the hostname or IPv4 address for the URI

p_port - the URI port (may be -1 for "unspecified"; cannot be specified if host is null)

p_path - the URI path - if the path contains '?' or '#', then the query string and/or fragment will be set from the path; however, if the query and fragment are specified both in the path and as separate parameters, an exception is thrown

p_queryString - the URI query string (cannot be specified if path is null)

p_fragment - the URI fragment (cannot be specified if path is null)

Throws:

MalformedURIException - if any of the parameters violates syntax rules or semantic rules

Method Detail

getScheme

public String getScheme()

Get the scheme for this URI.

Returns:

the scheme for this URI

getSchemeSpecificPart

public String getSchemeSpecificPart()

Get the scheme-specific part for this URI (everything following the scheme and the first colon). See RFC 2396 Section 5.2 for spec.

Returns:

the scheme-specific part for this URI

getUserinfo

public String getUserinfo()

Get the userinfo for this URI.

Returns:

the userinfo for this URI (null if not specified).

getHost

public String getHost()

Get the host for this URI.

Returns:

the host for this URI (null if not specified).

getPort

public int getPort()

Get the port for this URI.

Returns:

the port for this URI (-1 if not specified).

getPath

public String getPath(boolean p_includeQueryString,
             boolean p_includeFragment)

Get the path for this URI (optionally with the query string and fragment).

Parameters:

p_includeQueryString - if true (and query string is not null), then a "?" followed by the query string will be appended

p_includeFragment - if true (and fragment is not null), then a "#" followed by the fragment will be appended

Returns:

the path for this URI possibly including the query string and fragment

getPath

public String getPath()

Get the path for this URI. Note that the value returned is the path only and does not include the query string or fragment.

Returns:

the path for this URI.

getQueryString

public String getQueryString()

Get the query string for this URI.

Returns:

the query string for this URI. Null is returned if there was no "?" in the URI spec, empty string if there was a "?" but no query string following it.

getFragment

public String getFragment()

Get the fragment for this URI.

Returns:

the fragment for this URI. Null is returned if there was no "#" in the URI spec, empty string if there was a "#" but no fragment following it.

setFragment

public void setFragment(String p_fragment)
                 throws MalformedURIException

Set the fragment for this URI. A non-null value is valid only if this is a URI conforming to the generic URI syntax and the path value is not null.

Parameters:

p_fragment - the fragment for this URI

Throws:

MalformedURIException - if p_fragment is not null and this URI does not conform to the generic URI syntax or if the path is null

equals

public boolean equals(Object p_test)

Determines if the passed-in Object is equivalent to this URI.

Overrides:

equals in class Object

Parameters:

p_test - the Object to test for equality.

Returns:

true if p_test is a URI with all values equal to this URI, false otherwise

toString

public String toString()

produce a human-consumable string for the URI

Overrides:

toString in class Object

getURIString

public String getURIString()

Get the URI as a string specification. See RFC 2396 Section 5.2.

Returns:

the URI string specification

hashCode

public int hashCode()

Overrides:

hashCode in class Object

isGenericURI

public boolean isGenericURI()

Get the indicator as to whether this URI uses the "generic URI" syntax.

Returns:

true if this URI uses the "generic URI" syntax, false otherwise

isConformantSchemeName

public static boolean isConformantSchemeName(String p_scheme)

Determine whether a scheme conforms to the rules for a scheme name. A scheme is conformant if it starts with an alphanumeric, and contains only alphanumerics, '+','-' and '.'.

Returns:

true if the scheme is conformant, false otherwise

isWellFormedAddress

public static boolean isWellFormedAddress(String p_address)

Determine whether a string is syntactically capable of representing a valid IPv4 address or the domain name of a network host. A valid IPv4 address consists of four decimal digit groups separated by a '.'. A hostname consists of domain labels (each of which must begin and end with an alphanumeric but may contain '-') separated & by a '.'. See RFC 2396 Section 3.2.2.

Returns:

true if the string is a syntactically valid IPv4 address or hostname

isNormalFormC

public boolean isNormalFormC()

relativize

public String relativize(String abs,
                int flags)
                  throws MalformedURIException

Throws:

MalformedURIException

flags2str

public static String flags2str(int f)

str2flags

public static int str2flags(String pv)