Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009. All Rights Reserved.