com.xmlmind.util
Class URIComponent

java.lang.Object
  com.xmlmind.util.URIComponent

public final class URIComponent
extends java.lang.Object

A collection of low-level utility functions (static methods) related to URI components (Strings, not java.net.URI).

Refer to the documentation of URI for the definitions of quote, encode and decode.

Method Summary

static java.lang.String	decode(java.lang.String s) Equivalent to decode(s, "UTF-8").
static java.lang.String	decode(java.lang.String s, java.lang.String charset) Decodes all %HH sequences.
static java.lang.String	encode(java.lang.String s) Equivalent to encode(s, "UTF-8").
static java.lang.String	encode(java.lang.String s, java.lang.String charset) Encodes non-ASCII characters, space characters (according to java.lang.Character.isSpaceChar) and control characters (according to java.lang.Character.isISOControl) as %XX bytes.
static java.lang.String	getBaseName(java.lang.String path) Same as getRawBaseName(java.lang.String) except that the returned value is decoded using decode(java.lang.String).
static java.lang.String	getExtension(java.lang.String path) Same as getRawExtension(java.lang.String) except that the returned value is decoded using decode(java.lang.String).
static java.lang.String	getFragment(java.lang.String location) Same as getRawFragment(java.lang.String) except that the returned value is decoded using decode(java.lang.String).
static java.lang.String	getRawBaseName(java.lang.String path) Returns the base name of specified path.
static java.lang.String	getRawExtension(java.lang.String path) Returns the extension of specified path.
static java.lang.String	getRawFragment(java.lang.String location) Returns the fragment component (not including the '#' delimiter) of specified location if any; null otherwise.
static java.lang.String	getRawParentPath(java.lang.String path) Equivalent to getRawParentPath(path, true).
static java.lang.String	getRawParentPath(java.lang.String path, boolean trailingSlash) Returns the parent of specified path.
static java.lang.String	getRawRelativePath(java.lang.String path, java.lang.String basePath) Returns first path as a path relative to the second path.
static java.lang.String	joinQuotedComponents(java.lang.String scheme, java.lang.String userName, java.lang.String userPassword, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment) Joins specified URI components, without attempting to quote them.
static java.lang.String	quoteFragment(java.lang.String fragment) Quotes specified fragment (that is, escapes ``special'' characters).
static java.lang.String	quoteFullPath(java.lang.String path) Quotes specified path (that is, escapes ``special'' characters).
static void	quoteFullPath(java.lang.String path, java.lang.StringBuilder buffer) Similar tp quoteFullPath(String) but appends quoted path to specified buffer.
static java.lang.String	quotePath(java.lang.String path) Quotes specified path (that is, escapes ``special'' characters).
static java.lang.String	quoteQuery(java.lang.String query) Quotes specified query (that is, escapes ``special'' characters).
static java.lang.String	quoteUserInfo(java.lang.String userInfo) Quotes specified user info (that is, escapes ``special'' characters).
static java.lang.String	setExtension(java.lang.String path, java.lang.String extension) Same as setRawExtension(java.lang.String, java.lang.String) except that extension is quoted using quotePath(java.lang.String).
static java.lang.String	setFragment(java.lang.String location, java.lang.String fragment) Same as setRawFragment(java.lang.String, java.lang.String) except that fragment is quoted using quoteFragment(java.lang.String).
static java.lang.String	setRawExtension(java.lang.String path, java.lang.String extension) Changes the extension of specified path to specified extension.
static java.lang.String	setRawFragment(java.lang.String location, java.lang.String fragment) Changes the fragment component of specified location to specified fragment.
static java.lang.String	truncatePath(java.lang.String path, int maxLength) Truncates specified path to get something short enough to be displayed in the "Recently Opened Files" part of a File menu.

Methods inherited from class java.lang.Object

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

Method Detail

getRawParentPath

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

Equivalent to getRawParentPath(path, true).

getRawParentPath

public static java.lang.String getRawParentPath(java.lang.String path,
                                                boolean trailingSlash)

Returns the parent of specified path. To make it simple, the substring before last '/'.

Examples:

• Returns null for "/".
• Returns null for "foo".
• Returns "/" for "/foo".
• Returns "/foo" (or "/foo/") for "/foo/bar".
• Returns "/foo" (or "/foo/") for "/foo/bar/".

Parameters:

path - relative or absolute URI path

trailingSlash - if true, returned path ends with a trailing '/' character

Returns:

parent of specified path or null for '/' or if specified path does not contain the '/' character

getBaseName

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

Same as getRawBaseName(java.lang.String) except that the returned value is decoded using decode(java.lang.String).

getRawBaseName

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

Returns the base name of specified path. To make it simple, the substring after last '/'.

Examples:

• Returns the empty string for "/".
• Returns "foo" for "foo".
• Returns "bar" for "/foo/bar".
• Returns "bar" for "/foo/bar/".

Parameters:

path - relative or absolute URI path

Returns:

base name of specified path

getExtension

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

Same as getRawExtension(java.lang.String) except that the returned value is decoded using decode(java.lang.String).

getRawExtension

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

Returns the extension of specified path. To make it simple, the substring after last '.', not including last '.'.

• Returns null for "/tmp/test".
• Returns the empty string for "/tmp/test.".
• Returns null for "~/.profile".
• Returns "gz" for "/tmp/test.tar.gz".

Parameters:

path - relative or absolute URI path possibly having an extension

Returns:

extension if any; null otherwise

setExtension

public static java.lang.String setExtension(java.lang.String path,
                                            java.lang.String extension)

Same as setRawExtension(java.lang.String, java.lang.String) except that extension is quoted using quotePath(java.lang.String).

setRawExtension

public static java.lang.String setRawExtension(java.lang.String path,
                                               java.lang.String extension)

Changes the extension of specified path to specified extension. See getRawExtension(java.lang.String) for a description of the extension of a path.

Parameters:

path - relative or absolute URI path

extension - new extension. Assumed to have been quoted using quotePath(java.lang.String). May be null which means: remove the extension.

Returns:

a path identical to path except that its extension has been changed or removed.

Returns same path if specified path ends with '/'.

getFragment

public static java.lang.String getFragment(java.lang.String location)

Same as getRawFragment(java.lang.String) except that the returned value is decoded using decode(java.lang.String).

getRawFragment

public static java.lang.String getRawFragment(java.lang.String location)

Returns the fragment component (not including the '#' delimiter) of specified location if any; null otherwise.

setFragment

public static java.lang.String setFragment(java.lang.String location,
                                           java.lang.String fragment)

Same as setRawFragment(java.lang.String, java.lang.String) except that fragment is quoted using quoteFragment(java.lang.String).

setRawFragment

public static java.lang.String setRawFragment(java.lang.String location,
                                              java.lang.String fragment)

Changes the fragment component of specified location to specified fragment.

Parameters:

location - relative or absolute location

fragment - new fragment. Assumed to have been quoted using quoteFragment(java.lang.String). May be null which means: remove the fragment.

Returns:

a location identical to location except that its fragment has been changed or removed

getRawRelativePath

public static java.lang.String getRawRelativePath(java.lang.String path,
                                                  java.lang.String basePath)

Returns first path as a path relative to the second path.

The returned result resolved against the second path gives back first path. This means that trailing slashes "/" are significant.

Examples:

• Returns "gee" for "gee" relative to "/foo/bar/wiz".
• Returns "/foo/bar/gee" for "/foo/bar/gee" relative to "wiz".
• Returns "foo/bar/gee" for "/foo/bar/gee" relative to "/".
• Returns "bar/gee" for "/foo/bar/gee" relative to "/foo/bar".
• Returns "gee" for "/foo/bar/gee" relative to "/foo/bar/wiz".
• Returns "../gee" for "/foo/bar/gee" relative to "/foo/bar/wiz/".
• Returns "gee/" for "/foo/bar/gee/" relative to "/foo/bar/wiz".
• Returns "../gee/" for "/foo/bar/gee/" relative to "/foo/bar/wiz/".
• Returns "/" for "/" relative to "/".
• Returns "gee" for "/foo/bar/gee" relative to "/foo/bar/gee".

Parameters:

path - an absolute URI path

basePath - another absolute URI path

Returns:

first path as a path relative to the second path. Returns first path as is, if the relative path cannot be computed.

truncatePath

public static java.lang.String truncatePath(java.lang.String path,
                                            int maxLength)

Truncates specified path to get something short enough to be displayed in the "Recently Opened Files" part of a File menu. Example: returns "/home/john/.../report1.xml" for "/home/john/docs/report1/report1.xml".

Parameters:

path - relative or absolute URI path to be truncated

maxLength - maximum length for truncated (this is just a hint); typically 40

Returns:

truncated path

joinQuotedComponents

public static java.lang.String joinQuotedComponents(java.lang.String scheme,
                                                    java.lang.String userName,
                                                    java.lang.String userPassword,
                                                    java.lang.String host,
                                                    int port,
                                                    java.lang.String path,
                                                    java.lang.String query,
                                                    java.lang.String fragment)

Joins specified URI components, without attempting to quote them. Pass null or -1 for missing components.

Parameters:

scheme - scheme or null

userName - properly quoted user name or null

userPassword - properly quoted password or null

host - host or null

port - port or -1

path - properly quoted path or null

query - properly quoted query (without '?') or null

fragment - properly quoted fragment (without '#') or null

Returns:

URI spec

quoteUserInfo

public static java.lang.String quoteUserInfo(java.lang.String userInfo)

Quotes specified user info (that is, escapes ``special'' characters).

Use this function separately on the user name and on the user password. That is, do not use it on "name:password".

Like all quote functions, the returned string may contain characters beloging to the other category.

quotePath

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

Quotes specified path (that is, escapes ``special'' characters).

Use this function separately on each path segment. That is, do not use it on something like "foo/bar/gee".

Like all quote functions, the returned string may contain characters beloging to the other category.

See Also:

quoteFullPath(String), quoteFullPath(String, StringBuilder)

quoteFullPath

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

Quotes specified path (that is, escapes ``special'' characters). Unlike quotePath(java.lang.String) which only works for path segments, this method can be used to quote a relative or absolute path.

Like all quote functions, the returned string may contain characters beloging to the other category.

quoteFullPath

public static void quoteFullPath(java.lang.String path,
                                 java.lang.StringBuilder buffer)

Similar tp quoteFullPath(String) but appends quoted path to specified buffer.

quoteQuery

public static java.lang.String quoteQuery(java.lang.String query)

Quotes specified query (that is, escapes ``special'' characters).

Like all quote functions, the returned string may contain characters beloging to the other category.

quoteFragment

public static java.lang.String quoteFragment(java.lang.String fragment)

Quotes specified fragment (that is, escapes ``special'' characters).

Returned string contains only ASCII characters.

Like all quote functions, the returned string may contain characters beloging to the other category.

decode

public static java.lang.String decode(java.lang.String s)

Equivalent to decode(s, "UTF-8").

decode

public static java.lang.String decode(java.lang.String s,
                                      java.lang.String charset)

Decodes all %HH sequences.

This function should be used on individual components. For example, it can be used on "foo" and on "bar" and not on "/foo/bar" as a whole.

encode(String, String) and decode(String, String) are not inverse operations:

• encode encodes only spaces and accented characters (to make it simple).
• decode replaces all %HH sequences by the corresponding characters.

Parameters:

s - string to be decoded

charset - the encoding used for characters in the other category. A superset of US-ASCII. Examples: "ISO-8859-1" (eacute is represented as "%E9"), "UTF-8" (eacute is represented as "%C3%A9").

For interoperability with URI, charset is required to be "UTF-8".

Returns:

the decoded string or null if charset is an unsupported encoding

encode

public static java.lang.String encode(java.lang.String s)

Equivalent to encode(s, "UTF-8").

encode

public static java.lang.String encode(java.lang.String s,
                                      java.lang.String charset)

Encodes non-ASCII characters, space characters (according to java.lang.Character.isSpaceChar) and control characters (according to java.lang.Character.isISOControl) as %XX bytes. That is, escapes characters which are unambiguously illegal according to RFC2396.

encode(String, String) and decode(String, String) are not inverse operations:

• encode encodes only spaces and accented characters (to make it simple).
• decode replaces all %HH sequences by the corresponding characters.

Parameters:

s - string to be encode

charset - the encoding used for the aforementioned ``illegal'' characters. A superset of US-ASCII.

For interoperability with URI, charset is required to be "UTF-8".

Returns:

the encoded string or null if charset is an unsupported encoding