org.odftoolkit.odfdom.dom.util
Class URITransformer

java.lang.Object
  org.odftoolkit.odfdom.dom.util.URITransformer

public class URITransformer
extends Object

Transformations for transporting URIs in URLs.

URIs, URLs, and URNs

A URI is a uniform resource identifier while a URL is a uniform resource locator. Hence every URL is a URI, abstractly speaking, but not every URI is a URL. This is because there is another subcategory of URIs, uniform resource names (URNs), which name resources but do not specify how to locate them. The mailto, news, and isbn URIs shown above are examples of URNs.

URI syntax and components

At the highest level a URI reference (hereinafter simply "URI") in string form has the syntax

[scheme:]scheme-specific-part[#fragment]

where square brackets [...] delineate optional components and the characters : and # stand for themselves.

An absolute URI specifies a scheme; a URI that is not absolute is said to be relative. URIs are also classified according to whether they are opaque or hierarchical.

An opaque URI is an absolute URI whose scheme-specific part does not begin with a slash character ('/'). Opaque URIs are not subject to further parsing. Some examples of opaque URIs are:

mailto:java-net@java.sun.com
news:comp.lang.java
urn:isbn:096139210x

A hierarchical URI is either an absolute URI whose scheme-specific part begins with a slash character, or a relative URI, that is, a URI that does not specify a scheme. Some examples of hierarchical URIs are:

http://java.sun.com/j2se/1.3/
docs/guide/collections/designfaq.html#28
../../../demo/jfc/SwingSet2/src/SwingSet2.java
file:///~/calendar

A hierarchical URI is subject to further parsing according to the syntax

[scheme:][//authority][path][?query][#fragment]

where the characters :, /, ?, and # stand for themselves. The scheme-specific part of a hierarchical URI consists of the characters between the scheme and fragment components.

The authority component of a hierarchical URI is, if specified, either server-based or registry-based. A server-based authority parses according to the familiar syntax

[user-info@]host[:port]

where the characters @ and : stand for themselves. Nearly all URI schemes currently in use are server-based. An authority component that does not parse in this way is considered to be registry-based.

The path component of a hierarchical URI is itself said to be absolute if it begins with a slash character ('/'); otherwise it is relative. The path of a hierarchical URI that is either absolute or specifies an authority is always absolute.

All told, then, a URI instance has the following nine components:

Component	Type
scheme	String
scheme-specific-part	String
authority	String
user-info	String
host	String
port	int
path	String
query	String
fragment	String

In a given instance any particular component is either undefined or defined with a distinct value. Undefined string components are represented by null, while undefined integer components are represented by -1. A string component may be defined to have the empty string as its value; this is not equivalent to that component being undefined.

Whether a particular component is or is not defined in an instance depends upon the type of the URI being represented. An absolute URI has a scheme component. An opaque URI has a scheme, a scheme-specific part, and possibly a fragment, but has no other components. A hierarchical URI always has a path (though it may be empty) and a scheme-specific-part (which at least contains the path), and may have any of the other components. If the authority component is present and is server-based then the host component will be defined and the user-information and port components may be defined. See RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax

Field Summary

protected static BitSet

safeCharacters Array containing the safe characters set for encoding.

Constructor Summary

URITransformer()

Method Summary

static String	decodePath(String path) Decode path component segments in URI.
static String	encodePath(String path) Encode path to be used as path component segments in URI.
static String	path2uri(String path) Extract URI from a path.
static String	uri2path(String uri) Embed URI into path.

Methods inherited from class java.lang.Object

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

Field Detail

safeCharacters

protected static BitSet safeCharacters

Array containing the safe characters set for encoding.

Only the following characters are not encoded:
A-Z a-z 0-9 : @ & $ - _ . + ! * ' ( ) ,

Constructor Detail

URITransformer

public URITransformer()

Method Detail

encodePath

public static String encodePath(String path)

Encode path to be used as path component segments in URI.

Creates a String that can be used as a sequence of one or more path components in an URI from a path that uses a slash character as a path separator and where the segements do not use any URI encoding rules.

The / characters (delimiting the individual path_segments) are left unchanged.

Parameters:

path - A path that is not using URI encoding rules.

Returns:

A path that is using URI encoding rules.

See Also:

decodePath(String)

decodePath

public static String decodePath(String path)

Decode path component segments in URI.

Creates a path that uses a slash character as a path separator and where the segments do not use any URI encoding from a String that is used as a sequence of one or more path components in an URI where the path segments do use URI encoding rules.

The / characters (delimiting the individual path_segments) are left unchanged.

Parameters:

path - A path that is using URI encoding rules.

Returns:

A path that is not using URI encoding rules.

See Also:

encodePath(String)

path2uri

public static String path2uri(String path)

Extract URI from a path.

Transforms a path that was created with the uri2path(String) method back to an URI.

This method does try to cope with an erroneous input parameter but the result returned in such a case is not guaranteed to be a valid URI.

Parameters:

path - the path that contains the URI information

Returns:

a String representing a URI

See Also:

uri2path(String)

uri2path

public static String uri2path(String uri)

Embed URI into path.

Opaque URIs

Opaque URIs are mapped to a path of the form </ scheme /==0/ opaque_part'>.

The mapping from opaque_part to opaque_part' works as follows:(*)

Octets from the set A-Z a-z 0-9 : @ & $ - _ . + ! * ' ( ) , are left unchanged.

Other octest are replaced with = followed by two hex digits that represent the octet's numerical value.

Hierarchical URIs without an authority component

Hierarchical URIs without an authority component are mapped to a path of the form </ scheme /==1 abs_path' [? query]>.

If abs_path is empty, it is left unchanged.

If abs_path is non-empty, it is decoded with the decodePath(String) method.

A non-empty path_segment is left unchanged.

Hierarchical URIs with an authority component

Hierarchical URIs with an authority component ? query]> are mapped to a path of the form </ scheme / authority' abs_path' [?query]>.

If authority is empty, it is mapped to ==2. This eliminates problems if the servlet container drops final slashes from paths or cannot handle empty segments within paths.

The mapping from abs_path to abs_path' works as follows:

If authority is non-empty, it is mapped as described for the opaque_part above.

The mapping from abs_path to abs_path' works as follows:

If abs_path is empty, it is left unchanged.

If abs_path is non-empty, it is decoded with the decodePath(String) method.

See Also:

path2uri(String)