URI (eXo PLF:: WS :: Commons Utils 2.5.1-RC09 API)

java.lang.Object
- org.exoplatform.common.http.client.URI

```
public class URI
extends Object
```
This class represents a generic URI, as defined in RFC-2396. This is similar to java.net.URL, with the following enhancements:
- it doesn't require a URLStreamhandler to exist for the scheme; this allows this class to be used to hold any URI, construct absolute URIs from relative ones, etc.
- it handles escapes correctly
- equals() works correctly
- relative URIs are correctly constructed
- it has methods for accessing various fields such as userinfo, fragment, params, etc.
- it handles less common forms of resources such as the "*" used in http URLs.
The elements are always stored in escaped form.
While RFC-2396 distinguishes between just two forms of URI's, those that follow the generic syntax and those that don't, this class knows about a third form, named semi-generic, used by quite a few popular schemes. Semi-generic syntax treats the path part as opaque, i.e. has the form <scheme>://<authority>/<opaque> . Relative URI's of this type are only resolved as far as absolute paths - relative paths do not exist.
Ideally, java.net.URL should subclass URI.
Since:

V0.3-1

Version:

0.3-3 06/05/2001

Author:

Ronald Tschal�r

See Also:

rfc-2396

Field Summary

Fields
Modifier and Type	Field and Description
`protected static BitSet`	`alphanumChar`
`protected static Hashtable`	`defaultPorts`
`static boolean`	`ENABLE_BACKWARDS_COMPATIBILITY` If true, then the parser will resolve certain URI's in backwards compatible (but technically incorrect) manner.
`static BitSet`	`escpdFragChar` list of characters which must not be escaped when escaping a fragment identifier
`static BitSet`	`escpdPathChar` list of characters which must not be escaped when escaping a path
`static BitSet`	`escpdQueryChar` list of characters which must not be escaped when escaping a query string
`protected String`	`fragment`
`protected static int`	`GENERIC`
`protected String`	`host`
`protected static BitSet`	`hostChar`
`protected static BitSet`	`markChar`
`protected String`	`opaque`
`protected static int`	`OPAQUE`
`protected static BitSet`	`opaqueChar`
`protected String`	`path`
`protected static BitSet`	`pcharChar`
`protected int`	`port`
`protected String`	`query`
`protected static BitSet`	`reg_nameChar`
`protected static BitSet`	`reservedChar`
`static BitSet`	`resvdHostChar` list of characters which must not be unescaped when unescaping a host
`static BitSet`	`resvdPathChar` list of characters which must not be unescaped when unescaping a path
`static BitSet`	`resvdQueryChar` list of characters which must not be unescaped when unescaping a query string
`static BitSet`	`resvdSchemeChar` list of characters which must not be unescaped when unescaping a scheme
`static BitSet`	`resvdUIChar` list of characters which must not be unescaped when unescaping a userinfo
`protected String`	`scheme`
`protected static BitSet`	`schemeChar`
`protected static int`	`SEMI_GENERIC`
`protected int`	`type`
`protected static BitSet`	`unreservedChar`
`protected static BitSet`	`uricChar`
`protected URL`	`url`
`protected String`	`userinfo`
`protected static BitSet`	`userinfoChar`
`protected static Hashtable`	`usesGenericSyntax`
`protected static Hashtable`	`usesSemiGenericSyntax`

Constructor Summary

Constructors
Constructor and Description
`URI(String uri)` Constructs a URI from the given string representation.
`URI(String scheme, String opaque)` Constructs an opaque URI from the given parts.
`URI(String scheme, String host, int port, String path)` Constructs a URI from the given parts.
`URI(String scheme, String host, String path)` Constructs a URI from the given parts, using the default port for this scheme (if known).
`URI(String scheme, String userinfo, String host, int port, String path, String query, String fragment)` Constructs a URI from the given parts.
`URI(URI base, String rel_uri)` Constructs a URI from the given string representation, relative to the given base URI.
`URI(URL url)` Construct a URI from the given URL.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static String`	`canonicalizePath(String path)` Remove all "/../" and "/./" from path, where possible.
`static int`	`defaultPort(String protocol)` Return the default port used by a given protocol.
`boolean`	`equals(Object other)`
`static char[]`	`escape(char[] elem, BitSet allowed_char, boolean utf8)` Escape any character not in the given character class.
`static String`	`escape(String elem, BitSet allowed_char, boolean utf8)` Escape any character not in the given character class.
`String`	`getFragment()`
`String`	`getHost()`
`String`	`getOpaque()`
`String`	`getPath()`
`String`	`getPathAndQuery()`
`int`	`getPort()`
`String`	`getQueryString()`
`String`	`getScheme()`
`String`	`getUserinfo()`
`int`	`hashCode()` The hash code is calculated over scheme, host, path, and query.
`boolean`	`isGenericURI()` Does the scheme specific part of this URI use the generic-URI syntax?
`boolean`	`isSemiGenericURI()` Does the scheme specific part of this URI use the semi-generic-URI syntax?
`static void`	`main(String[] args)` Run test set.
`String`	`toExternalForm()`
`String`	`toString()` Return the URI as string.
`URL`	`toURL()` Will try to create a java.net.URL object from this URI.
`static String`	`unescape(String str, BitSet reserved)` Unescape escaped characters (i.e.
`static boolean`	`usesGenericSyntax(String scheme)`
`static boolean`	`usesSemiGenericSyntax(String scheme)`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - ENABLE_BACKWARDS_COMPATIBILITY
```
public static final boolean ENABLE_BACKWARDS_COMPATIBILITY
```
    If true, then the parser will resolve certain URI's in backwards compatible (but technically incorrect) manner. Example:
```
 base   = http://a/b/c/d;p?q
 rel    = http:g
 result = http:g      (correct)
 result = http://a/b/c/g (backwards compatible)
 
```
    See rfc-2396, section 5.2, step 3, second paragraph.
    See Also:
    
    Constant Field Values
  - defaultPorts
```
protected static final Hashtable defaultPorts
```
  - usesGenericSyntax
```
protected static final Hashtable usesGenericSyntax
```
  - usesSemiGenericSyntax
```
protected static final Hashtable usesSemiGenericSyntax
```
  - alphanumChar
```
protected static final BitSet alphanumChar
```
  - markChar
```
protected static final BitSet markChar
```
  - reservedChar
```
protected static final BitSet reservedChar
```
  - unreservedChar
```
protected static final BitSet unreservedChar
```
  - uricChar
```
protected static final BitSet uricChar
```
  - pcharChar
```
protected static final BitSet pcharChar
```
  - userinfoChar
```
protected static final BitSet userinfoChar
```
  - schemeChar
```
protected static final BitSet schemeChar
```
  - hostChar
```
protected static final BitSet hostChar
```
  - opaqueChar
```
protected static final BitSet opaqueChar
```
  - reg_nameChar
```
protected static final BitSet reg_nameChar
```
  - resvdSchemeChar
```
public static final BitSet resvdSchemeChar
```
    list of characters which must not be unescaped when unescaping a scheme
  - resvdUIChar
```
public static final BitSet resvdUIChar
```
    list of characters which must not be unescaped when unescaping a userinfo
  - resvdHostChar
```
public static final BitSet resvdHostChar
```
    list of characters which must not be unescaped when unescaping a host
  - resvdPathChar
```
public static final BitSet resvdPathChar
```
    list of characters which must not be unescaped when unescaping a path
  - resvdQueryChar
```
public static final BitSet resvdQueryChar
```
    list of characters which must not be unescaped when unescaping a query string
  - escpdPathChar
```
public static final BitSet escpdPathChar
```
    list of characters which must not be escaped when escaping a path
  - escpdQueryChar
```
public static final BitSet escpdQueryChar
```
    list of characters which must not be escaped when escaping a query string
  - escpdFragChar
```
public static final BitSet escpdFragChar
```
    list of characters which must not be escaped when escaping a fragment identifier
  - OPAQUE
```
protected static final int OPAQUE
```
    See Also:
    
    Constant Field Values
  - SEMI_GENERIC
```
protected static final int SEMI_GENERIC
```
    See Also:
    
    Constant Field Values
  - GENERIC
```
protected static final int GENERIC
```
    See Also:
    
    Constant Field Values
  - type
```
protected int type
```
  - scheme
```
protected String scheme
```
  - opaque
```
protected String opaque
```
  - userinfo
```
protected String userinfo
```
  - host
```
protected String host
```
  - port
```
protected int port
```
  - path
```
protected String path
```
  - query
```
protected String query
```
  - fragment
```
protected String fragment
```
  - url
```
protected URL url
```
- Constructor Detail
  - URI
```
public URI(String uri)
    throws ParseException
```
    Constructs a URI from the given string representation. The string must be an absolute URI.
    
    Parameters:
    
    uri - a String containing an absolute URI
    
    Throws:
    
    ParseException - if no scheme can be found or a specified port cannot be parsed as a number
  - URI
```
public URI(URI base,
           String rel_uri)
    throws ParseException
```
    Constructs a URI from the given string representation, relative to the given base URI.
    
    Parameters:
    
    base - the base URI, relative to which rel_uri is to be parsed
    
    rel_uri - a String containing a relative or absolute URI
    
    Throws:
    
    ParseException - if base is null and rel_uri is not an absolute URI, or if base is not null and the scheme is not known to use the generic syntax, or if a given port cannot be parsed as a number
  - URI
```
public URI(URL url)
    throws ParseException
```
    Construct a URI from the given URL.
    
    Parameters:
    
    url - the URL
    
    Throws:
    
    ParseException - if url.toExternalForm() generates an invalid string representation
  - URI
```
public URI(String scheme,
           String host,
           String path)
    throws ParseException
```
    Constructs a URI from the given parts, using the default port for this scheme (if known). The parts must be in unescaped form.
    
    Parameters:
    
    scheme - the scheme (sometimes known as protocol)
    
    host - the host
    
    path - the path part
    
    Throws:
    
    ParseException - if scheme is null
  - URI
```
public URI(String scheme,
           String host,
           int port,
           String path)
    throws ParseException
```
    Constructs a URI from the given parts. The parts must be in unescaped form.
    
    Parameters:
    
    scheme - the scheme (sometimes known as protocol)
    
    host - the host
    
    port - the port
    
    path - the path part
    
    Throws:
    
    ParseException - if scheme is null
  - URI
```
public URI(String scheme,
           String userinfo,
           String host,
           int port,
           String path,
           String query,
           String fragment)
    throws ParseException
```
    Constructs a URI from the given parts. Any part except for the the scheme may be null. The parts must be in unescaped form.
    
    Parameters:
    
    scheme - the scheme (sometimes known as protocol)
    
    userinfo - the userinfo
    
    host - the host
    
    port - the port
    
    path - the path part
    
    query - the query string
    
    fragment - the fragment identifier
    
    Throws:
    
    ParseException - if scheme is null
  - URI
```
public URI(String scheme,
           String opaque)
    throws ParseException
```
    Constructs an opaque URI from the given parts.
    
    Parameters:
    
    scheme - the scheme (sometimes known as protocol)
    
    opaque - the opaque part
    
    Throws:
    
    ParseException - if scheme is null
- Method Detail
  - canonicalizePath
```
public static String canonicalizePath(String path)
```
    Remove all "/../" and "/./" from path, where possible. Leading "/../"'s are not removed.
    
    Parameters:
    
    path - the path to canonicalize
    
    Returns:
    
    the canonicalized path
  - usesGenericSyntax
```
public static boolean usesGenericSyntax(String scheme)
```
    Returns:
    
    true if the scheme should be parsed according to the generic-URI syntax
  - usesSemiGenericSyntax
```
public static boolean usesSemiGenericSyntax(String scheme)
```
    Returns:
    
    true if the scheme should be parsed according to a semi-generic-URI syntax <scheme>://<hostport>/<opaque>
  - defaultPort
```
public static final int defaultPort(String protocol)
```
    Return the default port used by a given protocol.
    
    Parameters:
    
    protocol - the protocol
    
    Returns:
    
    the port number, or 0 if unknown
  - getScheme
```
public String getScheme()
```
    Returns:
    
    the scheme (often also referred to as protocol)
  - getOpaque
```
public String getOpaque()
```
    Returns:
    
    the opaque part, or null if this URI is generic
  - getHost
```
public String getHost()
```
    Returns:
    
    the host
  - getPort
```
public int getPort()
```
    Returns:
    
    the port, or -1 if it's the default port, or 0 if unknown
  - getUserinfo
```
public String getUserinfo()
```
    Returns:
    
    the user info
  - getPath
```
public String getPath()
```
    Returns:
    
    the path
  - getQueryString
```
public String getQueryString()
```
    Returns:
    
    the query string
  - getPathAndQuery
```
public String getPathAndQuery()
```
    Returns:
    
    the path and query
  - getFragment
```
public String getFragment()
```
    Returns:
    
    the fragment
  - isGenericURI
```
public boolean isGenericURI()
```
    Does the scheme specific part of this URI use the generic-URI syntax?
    In general URI are split into two categories: opaque-URI and generic-URI. The generic-URI syntax is the syntax most are familiar with from URLs such as ftp- and http-URLs, which is roughly:
```
 generic-URI = scheme ":" [ "//" server ] [ "/" ] [ path_segments ] [ "?" query ]
 
```
    (see RFC-2396 for exact syntax). Only URLs using the generic-URI syntax can be used to create and resolve relative URIs.
    Whether a given scheme is parsed according to the generic-URI syntax or wether it is treated as opaque is determined by an internal table of URI schemes.
    See Also:
    
    rfc-2396
  - isSemiGenericURI
```
public boolean isSemiGenericURI()
```
    Does the scheme specific part of this URI use the semi-generic-URI syntax?
    Many schemes which don't follow the full generic syntax actually follow a reduced form where the path part is treated is opaque. This is used for example by ldap, smtp, pop, etc, and is roughly
```
 generic-URI = scheme ":" [ "//" server ] [ "/" [ opaque_path ] ]
 
```
    I.e. parsing is identical to the generic-syntax, except that the path part is not further parsed. URLs using the semi-generic-URI syntax can be used to create and resolve relative URIs with the restriction that all paths are treated as absolute.
    Whether a given scheme is parsed according to the semi-generic-URI syntax is determined by an internal table of URI schemes.
    See Also:
    
    isGenericURI()
  - toURL
```
public URL toURL()
          throws MalformedURLException
```
    Will try to create a java.net.URL object from this URI.
    
    Returns:
    
    the URL
    
    Throws:
    
    MalformedURLException - if no handler is available for the scheme
  - toExternalForm
```
public String toExternalForm()
```
    Returns:
    
    a string representation of this URI suitable for use in links, headers, etc.
  - toString
```
public String toString()
```
    Return the URI as string. This differs from toExternalForm() in that all elements are unescaped before assembly. This is not suitable for passing to other apps or in header fields and such, and is usually not what you want.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    the URI as a string
    
    See Also:
    
    toExternalForm()
  - equals
```
public boolean equals(Object other)
```
    Overrides:
    
    equals in class Object
    
    Returns:
    
    true if other is either a URI or URL and it matches the current URI
  - hashCode
```
public int hashCode()
```
    The hash code is calculated over scheme, host, path, and query.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hash code
  - escape
```
public static String escape(String elem,
                            BitSet allowed_char,
                            boolean utf8)
```
    Escape any character not in the given character class. Characters greater 255 are always escaped according to ??? .
    
    Parameters:
    
    elem - the string to escape
    
    allowed_char - the BitSet of all allowed characters
    
    utf8 - if true, will first UTF-8 encode unallowed characters
    
    Returns:
    
    the string with all characters not in allowed_char escaped
  - escape
```
public static char[] escape(char[] elem,
                            BitSet allowed_char,
                            boolean utf8)
```
    Escape any character not in the given character class. Characters greater 255 are always escaped according to ??? .
    
    Parameters:
    
    elem - the array of characters to escape
    
    allowed_char - the BitSet of all allowed characters
    
    utf8 - if true, will first UTF-8 encode unallowed characters
    
    Returns:
    
    the elem array with all characters not in allowed_char escaped
  - unescape
```
public static final String unescape(String str,
                                    BitSet reserved)
                             throws ParseException
```
    Unescape escaped characters (i.e. %xx) except reserved ones.
    
    Parameters:
    
    str - the string to unescape
    
    reserved - the characters which may not be unescaped, or null
    
    Returns:
    
    the unescaped string
    
    Throws:
    
    ParseException - if the two digits following a `%' are not a valid hex number
  - main
```
public static void main(String[] args)
                 throws Exception
```
    Run test set.
    
    Throws:
    
    Exception - if any test fails

Class URI

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ENABLE_BACKWARDS_COMPATIBILITY

defaultPorts

usesGenericSyntax

usesSemiGenericSyntax

alphanumChar

markChar

reservedChar

unreservedChar

uricChar

pcharChar

userinfoChar

schemeChar

hostChar

opaqueChar

reg_nameChar

resvdSchemeChar

resvdUIChar

resvdHostChar

resvdPathChar

resvdQueryChar

escpdPathChar

escpdQueryChar

escpdFragChar

OPAQUE

SEMI_GENERIC

GENERIC

type

scheme

opaque

userinfo

host

port

path

query

fragment

url

Constructor Detail

URI

URI

URI

URI

URI

URI

URI

Method Detail

canonicalizePath

usesGenericSyntax

usesSemiGenericSyntax

defaultPort

getScheme

getOpaque

getHost

getPort

getUserinfo

getPath

getQueryString

getPathAndQuery

getFragment

isGenericURI

isSemiGenericURI

toURL

toExternalForm

toString

equals

hashCode

escape

escape

unescape

main