com.xmlmind.util
Class URIComponent

java.lang.Object
  extended by 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:

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:

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 '.'.

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:

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:

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:

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