URI (The Grinder Documentation)

java.lang.Object
- HTTPClient.URI

```
public class URI
extends java.lang.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

Author:

Ronald Tschalär

See Also:
rfc-2396

Field Summary

Fields
Modifier and Type	Field and Description
`protected static java.util.BitSet`	`alphanumChar`
`protected static java.util.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 java.util.BitSet`	`escpdFragChar` list of characters which must not be escaped when escaping a fragment identifier
`static java.util.BitSet`	`escpdPathChar` list of characters which must not be escaped when escaping a path
`static java.util.BitSet`	`escpdQueryChar` list of characters which must not be escaped when escaping a query string
`protected java.lang.String`	`fragment`
`protected static int`	`GENERIC`
`protected java.lang.String`	`host`
`protected static java.util.BitSet`	`hostChar`
`protected static java.util.BitSet`	`markChar`
`protected java.lang.String`	`opaque`
`protected static int`	`OPAQUE`
`protected static java.util.BitSet`	`opaqueChar`
`protected java.lang.String`	`path`
`protected static java.util.BitSet`	`pcharChar`
`protected int`	`port`
`protected java.lang.String`	`query`
`protected static java.util.BitSet`	`reg_nameChar`
`protected static java.util.BitSet`	`reservedChar`
`static java.util.BitSet`	`resvdHostChar` list of characters which must not be unescaped when unescaping a host
`static java.util.BitSet`	`resvdPathChar` list of characters which must not be unescaped when unescaping a path
`static java.util.BitSet`	`resvdQueryChar` list of characters which must not be unescaped when unescaping a query string
`static java.util.BitSet`	`resvdSchemeChar` list of characters which must not be unescaped when unescaping a scheme
`static java.util.BitSet`	`resvdUIChar` list of characters which must not be unescaped when unescaping a userinfo
`protected java.lang.String`	`scheme`
`protected static java.util.BitSet`	`schemeChar`
`protected static int`	`SEMI_GENERIC`
`protected int`	`type`
`protected static java.util.BitSet`	`unreservedChar`
`protected static java.util.BitSet`	`uricChar`
`protected java.net.URL`	`url`
`protected java.lang.String`	`userinfo`
`protected static java.util.BitSet`	`userinfoChar`
`protected static java.util.Hashtable`	`usesGenericSyntax`
`protected static java.util.Hashtable`	`usesSemiGenericSyntax`

Constructor Summary

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

Method Summary

Methods
Modifier and Type	Method and Description
`static java.lang.String`	`canonicalizePath(java.lang.String path)` Remove all "/../" and "/./" from path, where possible.
`static int`	`defaultPort(java.lang.String protocol)` Return the default port used by a given protocol.
`boolean`	`equals(java.lang.Object other)`
`static char[]`	`escape(char[] elem, java.util.BitSet allowed_char, boolean utf8)` Escape any character not in the given character class.
`static java.lang.String`	`escape(java.lang.String elem, java.util.BitSet allowed_char, boolean utf8)` Escape any character not in the given character class.
`java.lang.String`	`getFragment()`
`java.lang.String`	`getHost()`
`java.lang.String`	`getOpaque()`
`java.lang.String`	`getPath()`
`java.lang.String`	`getPathAndQuery()`
`int`	`getPort()`
`java.lang.String`	`getQueryString()`
`java.lang.String`	`getScheme()`
`java.lang.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(java.lang.String[] args)` Run test set.
`java.lang.String`	`toExternalForm()`
`java.lang.String`	`toString()` Return the URI as string.
`java.net.URL`	`toURL()` Will try to create a java.net.URL object from this URI.
`static java.lang.String`	`unescape(java.lang.String str, java.util.BitSet reserved)` Unescape escaped characters (i.e.
`static boolean`	`usesGenericSyntax(java.lang.String scheme)`
`static boolean`	`usesSemiGenericSyntax(java.lang.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 java.util.Hashtable defaultPorts
```
  - usesGenericSyntax
```
protected static final java.util.Hashtable usesGenericSyntax
```
  - usesSemiGenericSyntax
```
protected static final java.util.Hashtable usesSemiGenericSyntax
```
  - alphanumChar
```
protected static final java.util.BitSet alphanumChar
```
  - markChar
```
protected static final java.util.BitSet markChar
```
  - reservedChar
```
protected static final java.util.BitSet reservedChar
```
  - unreservedChar
```
protected static final java.util.BitSet unreservedChar
```
  - uricChar
```
protected static final java.util.BitSet uricChar
```
  - pcharChar
```
protected static final java.util.BitSet pcharChar
```
  - userinfoChar
```
protected static final java.util.BitSet userinfoChar
```
  - schemeChar
```
protected static final java.util.BitSet schemeChar
```
  - hostChar
```
protected static final java.util.BitSet hostChar
```
  - opaqueChar
```
protected static final java.util.BitSet opaqueChar
```
  - reg_nameChar
```
protected static final java.util.BitSet reg_nameChar
```
  - resvdSchemeChar
```
public static final java.util.BitSet resvdSchemeChar
```
    list of characters which must not be unescaped when unescaping a scheme
  - resvdUIChar
```
public static final java.util.BitSet resvdUIChar
```
    list of characters which must not be unescaped when unescaping a userinfo
  - resvdHostChar
```
public static final java.util.BitSet resvdHostChar
```
    list of characters which must not be unescaped when unescaping a host
  - resvdPathChar
```
public static final java.util.BitSet resvdPathChar
```
    list of characters which must not be unescaped when unescaping a path
  - resvdQueryChar
```
public static final java.util.BitSet resvdQueryChar
```
    list of characters which must not be unescaped when unescaping a query string
  - escpdPathChar
```
public static final java.util.BitSet escpdPathChar
```
    list of characters which must not be escaped when escaping a path
  - escpdQueryChar
```
public static final java.util.BitSet escpdQueryChar
```
    list of characters which must not be escaped when escaping a query string
  - escpdFragChar
```
public static final java.util.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 java.lang.String scheme
```
  - opaque
```
protected java.lang.String opaque
```
  - userinfo
```
protected java.lang.String userinfo
```
  - host
```
protected java.lang.String host
```
  - port
```
protected int port
```
  - path
```
protected java.lang.String path
```
  - query
```
protected java.lang.String query
```
  - fragment
```
protected java.lang.String fragment
```
  - url
```
protected java.net.URL url
```
- Constructor Detail
  - URI
```
public URI(java.lang.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,
   java.lang.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(java.net.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(java.lang.String scheme,
   java.lang.String host,
   java.lang.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(java.lang.String scheme,
   java.lang.String host,
   int port,
   java.lang.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(java.lang.String scheme,
   java.lang.String userinfo,
   java.lang.String host,
   int port,
   java.lang.String path,
   java.lang.String query,
   java.lang.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(java.lang.String scheme,
   java.lang.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 java.lang.String canonicalizePath(java.lang.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(java.lang.String scheme)
```
    Returns:
    true if the scheme should be parsed according to the generic-URI syntax
  - usesSemiGenericSyntax
```
public static boolean usesSemiGenericSyntax(java.lang.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(java.lang.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 java.lang.String getScheme()
```
    Returns:
    the scheme (often also referred to as protocol)
  - getOpaque
```
public java.lang.String getOpaque()
```
    Returns:
    the opaque part, or null if this URI is generic
  - getHost
```
public java.lang.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 java.lang.String getUserinfo()
```
    Returns:
    the user info
  - getPath
```
public java.lang.String getPath()
```
    Returns:
    the path
  - getQueryString
```
public java.lang.String getQueryString()
```
    Returns:
    the query string
  - getPathAndQuery
```
public java.lang.String getPathAndQuery()
```
    Returns:
    the path and query
  - getFragment
```
public java.lang.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 java.net.URL toURL()
                   throws java.net.MalformedURLException
```
    Will try to create a java.net.URL object from this URI.
    
    Returns:
    the URL
    
    Throws:
    
    java.net.MalformedURLException - if no handler is available for the scheme
  - toExternalForm
```
public java.lang.String toExternalForm()
```
    Returns:
    a string representation of this URI suitable for use in links, headers, etc.
  - toString
```
public java.lang.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 java.lang.Object
    
    Returns:
    the URI as a string
    See Also:
    toExternalForm()
  - equals
```
public boolean equals(java.lang.Object other)
```
    Overrides:
    
    equals in class java.lang.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 java.lang.Object
    
    Returns:
    the hash code
  - escape
```
public static java.lang.String escape(java.lang.String elem,
                      java.util.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,
            java.util.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 java.lang.String unescape(java.lang.String str,
                        java.util.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(java.lang.String[] args)
                 throws java.lang.Exception
```
    Run test set.
    
    Throws:
    
    java.lang.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