## HTTPClient
Class URI

    java.lang.Object
      HTTPClient.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
See Also:
  rfc-2396

Field Summary
`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
`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
`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&tgt;://<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.

  Returns:
    the URI as a string
  See Also:
    `toExternalForm()`

### equals

    public boolean equals(Object other)

  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.

  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