URI (HttpClient 3.1 API)
Keywords: org.apache.commons.httpclient.URI class

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.apache.commons.httpclient
Class URI

    java.lang.Object
      org.apache.commons.httpclient.URI

All Implemented Interfaces:
  Serializable, Cloneable, Comparable

Direct Known Subclasses:
  HttpURL, URIUtil.Coder

    public class URI

extends Object
implements Cloneable, Comparable, Serializable

The interface for the URI(Uniform Resource Identifiers) version of RFC 2396. This class has the purpose of supportting of parsing a URI reference to extend any specific protocols, the character encoding of the protocol to be transported and the charset of the document.

A URI is always in an "escaped" form, since escaping or unescaping a completed URI might change its semantics.

Implementers should be careful not to escape or unescape the same string more than once, since unescaping an already unescaped string might lead to misinterpreting a percent data character as another escaped character, or vice versa in the case of escaping an already escaped string.

In order to avoid these problems, data types used as follows:

>        URI character sequence: char
>        octet sequence: byte
>        original character sequence: String

So, a URI is a sequence of characters as an array of a char type, which is not always represented as a sequence of octets as an array of byte.

URI Syntactic Components

>      - In general, written as follows:
>        Absolute URI = <scheme>:<scheme-specific-part>
>        Generic URI = <scheme>://<authority><path>?<query>

>      - Syntax
>        absoluteURI   = scheme ":" ( hier_part | opaque_part )
>        hier_part     = ( net_path | abs_path ) [ "?" query ]
>        net_path      = "//" authority [ abs_path ]
>        abs_path      = "/"  path_segments

The following examples illustrate URI that are in common use.

     ftp://ftp.is.co.za/rfc/rfc1808.txt
        -- ftp scheme for File Transfer Protocol services
     gopher://spinaltap.micro.umn.edu/00/Weather/California/Los%20Angeles
        -- gopher scheme for Gopher and Gopher+ Protocol services
     http://www.math.uio.no/faq/compression-faq/part1.html
        -- http scheme for Hypertext Transfer Protocol services
     mailto:mduerst@ifi.unizh.ch
        -- mailto scheme for electronic mail addresses
     news:comp.infosystems.www.servers.unix
        -- news scheme for USENET news groups and articles
     telnet://melvyl.ucop.edu/
        -- telnet scheme for interactive services via the TELNET Protocol

Please, notice that there are many modifications from URL(RFC 1738) and relative URL(RFC 1808).

The expressions for a URI

     For escaped URI forms
      - URI(char[]) // constructor
      - char[] getRawXxx() // method
      - String getEscapedXxx() // method
      - String toString() // method

     For unescaped URI forms
      - URI(String) // constructor
      - String getXXX() // method

Version:
  $Revision: 564973 $ $Date: 2002/03/14 15:14:01
Author:
  Sung-Gu, Mike Bowler
See Also:
  Serialized Form

Nested Class Summary
`static class` | `URI.DefaultCharsetChanged` The charset-changed normal operation to represent to be required to alert to user the fact the default charset is changed.
`static class` | `URI.LocaleToCharsetMap` A mapping to determine the (somewhat arbitrarily) preferred charset for a given locale.

Field Summary
`protected char[]` | `_authority` The authority.
`protected char[]` | `_fragment` The fragment.
`protected char[]` | `_host` The host.
`protected boolean` | `_is_abs_path`
`protected boolean` | `_is_hier_part`
`protected boolean` | `_is_hostname`
`protected boolean` | `_is_IPv4address`
`protected boolean` | `_is_IPv6reference`
`protected boolean` | `_is_net_path`
`protected boolean` | `_is_opaque_part`
`protected boolean` | `_is_reg_name`
`protected boolean` | `_is_rel_path`
`protected boolean` | `_is_server`
`protected char[]` | `_opaque` The opaque.
`protected char[]` | `_path` The path.
`protected int` | `_port` The port.
`protected char[]` | `_query` The query.
`protected char[]` | `_scheme` The scheme.
`protected char[]` | `_uri` This Uniform Resource Identifier (URI).
`protected char[]` | `_userinfo` The userinfo.
`protected static BitSet` | `abs_path` URI absolute path.
`protected static BitSet` | `absoluteURI` BitSet for absoluteURI.
`static BitSet` | `allowed_abs_path` Those characters that are allowed for the abs_path.
`static BitSet` | `allowed_authority` Those characters that are allowed for the authority component.
`static BitSet` | `allowed_fragment` Those characters that are allowed for the fragment component.
`static BitSet` | `allowed_host` Those characters that are allowed for the host component.
`static BitSet` | `allowed_IPv6reference` Those characters that are allowed for the IPv6reference component.
`static BitSet` | `allowed_opaque_part` Those characters that are allowed for the opaque_part.
`static BitSet` | `allowed_query` Those characters that are allowed for the query component.
`static BitSet` | `allowed_reg_name` Those characters that are allowed for the reg_name.
`static BitSet` | `allowed_rel_path` Those characters that are allowed for the rel_path.
`static BitSet` | `allowed_userinfo` Those characters that are allowed for the userinfo component.
`static BitSet` | `allowed_within_authority` Those characters that are allowed for the authority component.
`static BitSet` | `allowed_within_path` Those characters that are allowed within the path.
`static BitSet` | `allowed_within_query` Those characters that are allowed within the query component.
`static BitSet` | `allowed_within_userinfo` Those characters that are allowed for within the userinfo component.
`protected static BitSet` | `alpha` BitSet for alpha.
`protected static BitSet` | `alphanum` BitSet for alphanum (join of alpha & digit).
`protected static BitSet` | `authority` BitSet for authority.
`static BitSet` | `control` BitSet for control.
`protected static String` | `defaultDocumentCharset` The default charset of the document.
`protected static String` | `defaultDocumentCharsetByLocale`
`protected static String` | `defaultDocumentCharsetByPlatform`
`protected static String` | `defaultProtocolCharset` The default charset of the protocol.
`static BitSet` | `delims` BitSet for delims.
`protected static BitSet` | `digit` BitSet for digit.
`static BitSet` | `disallowed_opaque_part` Disallowed opaque_part before escaping.
`static BitSet` | `disallowed_rel_path` Disallowed rel_path before escaping.
`protected static BitSet` | `domainlabel` BitSet for domainlabel.
`protected static BitSet` | `escaped` BitSet for escaped.
`protected static BitSet` | `fragment` BitSet for fragment (alias for uric).
`protected int` | `hash` Cache the hash code for this URI.
`protected static BitSet` | `hex` BitSet for hex.
`protected static BitSet` | `hier_part` BitSet for hier_part.
`protected static BitSet` | `host` BitSet for host.
`protected static BitSet` | `hostname` BitSet for hostname.
`protected static BitSet` | `hostport` BitSet for hostport.
`protected static BitSet` | `IPv4address` Bitset that combines digit and dot fo IPv$address.
`protected static BitSet` | `IPv6address` RFC 2373.
`protected static BitSet` | `IPv6reference` RFC 2732, 2373.
`protected static BitSet` | `mark` BitSet for mark.
`protected static BitSet` | `net_path` BitSet for net_path.
`protected static BitSet` | `opaque_part` URI bitset that combines uric_no_slash and uric.
`protected static BitSet` | `param` BitSet for param (alias for pchar).
`protected static BitSet` | `path` URI bitset that combines absolute path and opaque part.
`protected static BitSet` | `path_segments` BitSet for path segments.
`protected static BitSet` | `pchar` BitSet for pchar.
`protected static BitSet` | `percent` The percent "%" character always has the reserved purpose of being the escape indicator, it must be escaped as "%25" in order to be used as data within a URI.
`protected static BitSet` | `port` Port, a logical alias for digit.
`protected String` | `protocolCharset` The charset of the protocol used by this URI instance.
`protected static BitSet` | `query` BitSet for query (alias for uric).
`protected static BitSet` | `reg_name` BitSet for reg_name.
`protected static BitSet` | `rel_path` BitSet for rel_path.
`protected static BitSet` | `rel_segment` BitSet for rel_segment.
`protected static BitSet` | `relativeURI` BitSet for relativeURI.
`protected static BitSet` | `reserved` BitSet for reserved.
`protected static char[]` | `rootPath` The root path.
`protected static BitSet` | `scheme` BitSet for scheme.
`protected static BitSet` | `segment` BitSet for segment.
`protected static BitSet` | `server` Bitset for server.
`static BitSet` | `space` BitSet for space.
`protected static BitSet` | `toplabel` BitSet for toplabel.
`protected static BitSet` | `unreserved` Data characters that are allowed in a URI but do not have a reserved purpose are called unreserved.
`static BitSet` | `unwise` BitSet for unwise.
`protected static BitSet` | `URI_reference` BitSet for URI-reference.
`protected static BitSet` | `uric` BitSet for uric.
`protected static BitSet` | `uric_no_slash` URI bitset for encoding typical non-slash characters.
`protected static BitSet` | `userinfo` Bitset for userinfo.
`static BitSet` | `within_userinfo` BitSet for within the userinfo component like user and password.

Constructor Summary
`protected` | `URI()` Create an instance as an internal use
`` | `URI(char[] escaped)` Deprecated. Use #URI(String, boolean)
`` | `URI(char[] escaped, String charset)` Deprecated. Use #URI(String, boolean, String)
`` | `URI(String original)` Deprecated. Use #URI(String, boolean)
`` | `URI(String s, boolean escaped)` Construct a URI from a string with the given charset.
`` | `URI(String s, boolean escaped, String charset)` Construct a URI from a string with the given charset.
`` | `URI(String original, String charset)` Deprecated. Use #URI(String, boolean, String)
`` | `URI(String scheme, String schemeSpecificPart, String fragment)` Construct a general URI from the given components.
`` | `URI(String scheme, String userinfo, String host, int port)` Construct a general URI from the given components.
`` | `URI(String scheme, String userinfo, String host, int port, String path)` Construct a general URI from the given components.
`` | `URI(String scheme, String userinfo, String host, int port, String path, String query)` Construct a general URI from the given components.
`` | `URI(String scheme, String userinfo, String host, int port, String path, String query, String fragment)` Construct a general URI from the given components.
`` | `URI(String scheme, String host, String path, String fragment)` Construct a general URI from the given components.
`` | `URI(String scheme, String authority, String path, String query, String fragment)` Construct a general URI from the given components.
`` | `URI(URI base, String relative)` Deprecated. Use #URI(URI, String, boolean)
`` | `URI(URI base, String relative, boolean escaped)` Construct a general URI with the given relative URI string.
`` | `URI(URI base, URI relative)` Construct a general URI with the given relative URI.

Method Summary
`Object` | `clone()` Create and return a copy of this object, the URI-reference containing the userinfo component.
`int` | `compareTo(Object obj)` Compare this URI to another object.
`protected static String` | `decode(char[] component, String charset)` Decodes URI encoded string.
`protected static String` | `decode(String component, String charset)` Decodes URI encoded string.
`protected static char[]` | `encode(String original, BitSet allowed, String charset)` Encodes URI string.
`protected boolean` | `equals(char[] first, char[] second)` Test if the first array is equal to the second array.
`boolean` | `equals(Object obj)` Test an object if this URI is equal to another.
`String` | `getAboveHierPath()` Get the level above the this hierarchy level.
`String` | `getAuthority()` Get the authority.
`String` | `getCurrentHierPath()` Get the current hierarchy level.
`static String` | `getDefaultDocumentCharset()` Get the recommended default charset of the document.
`static String` | `getDefaultDocumentCharsetByLocale()` Get the default charset of the document by locale.
`static String` | `getDefaultDocumentCharsetByPlatform()` Get the default charset of the document by platform.
`static String` | `getDefaultProtocolCharset()` Get the default charset of the protocol.
`String` | `getEscapedAboveHierPath()` Get the level above the this hierarchy level.
`String` | `getEscapedAuthority()` Get the escaped authority.
`String` | `getEscapedCurrentHierPath()` Get the escaped current hierarchy level.
`String` | `getEscapedFragment()` Get the escaped fragment.
`String` | `getEscapedName()` Get the escaped basename of the path.
`String` | `getEscapedPath()` Get the escaped path.
`String` | `getEscapedPathQuery()` Get the escaped query.
`String` | `getEscapedQuery()` Get the escaped query.
`String` | `getEscapedURI()` It can be gotten the URI character sequence.
`String` | `getEscapedURIReference()` Get the escaped URI reference string.
`String` | `getEscapedUserinfo()` Get the escaped userinfo.
`String` | `getFragment()` Get the fragment.
`String` | `getHost()` Get the host.
`String` | `getName()` Get the basename of the path.
`String` | `getPath()` Get the path.
`String` | `getPathQuery()` Get the path and query.
`int` | `getPort()` Get the port.
`String` | `getProtocolCharset()` Get the protocol charset used by this current URI instance.
`String` | `getQuery()` Get the query.
`char[]` | `getRawAboveHierPath()` Get the level above the this hierarchy level.
`char[]` | `getRawAuthority()` Get the raw-escaped authority.
`char[]` | `getRawCurrentHierPath()` Get the raw-escaped current hierarchy level.
`protected char[]` | `getRawCurrentHierPath(char[] path)` Get the raw-escaped current hierarchy level in the given path.
`char[]` | `getRawFragment()` Get the raw-escaped fragment.
`char[]` | `getRawHost()` Get the host.
`char[]` | `getRawName()` Get the raw-escaped basename of the path.
`char[]` | `getRawPath()` Get the raw-escaped path.
`char[]` | `getRawPathQuery()` Get the raw-escaped path and query.
`char[]` | `getRawQuery()` Get the raw-escaped query.
`char[]` | `getRawScheme()` Get the scheme.
`char[]` | `getRawURI()` It can be gotten the URI character sequence.
`char[]` | `getRawURIReference()` Get the URI reference character sequence.
`char[]` | `getRawUserinfo()` Get the raw-escaped userinfo.
`String` | `getScheme()` Get the scheme.
`String` | `getURI()` It can be gotten the URI character sequence.
`String` | `getURIReference()` Get the original URI reference string.
`String` | `getUserinfo()` Get the userinfo.
`boolean` | `hasAuthority()` Tell whether or not this URI has authority.
`boolean` | `hasFragment()` Tell whether or not this URI has fragment.
`int` | `hashCode()` Return a hash code for this URI.
`boolean` | `hasQuery()` Tell whether or not this URI has query.
`boolean` | `hasUserinfo()` Tell whether or not this URI has userinfo.
`protected int` | `indexFirstOf(char[] s, char delim)` Get the earlier index that to be searched for the first occurrance in one of any of the given array.
`protected int` | `indexFirstOf(char[] s, char delim, int offset)` Get the earlier index that to be searched for the first occurrance in one of any of the given array.
`protected int` | `indexFirstOf(String s, String delims)` Get the earlier index that to be searched for the first occurrance in one of any of the given string.
`protected int` | `indexFirstOf(String s, String delims, int offset)` Get the earlier index that to be searched for the first occurrance in one of any of the given string.
`boolean` | `isAbsoluteURI()` Tell whether or not this URI is absolute.
`boolean` | `isAbsPath()` Tell whether or not the relativeURI or hier_part of this URI is abs_path.
`boolean` | `isHierPart()` Tell whether or not the absoluteURI of this URI is hier_part.
`boolean` | `isHostname()` Tell whether or not the host part of this URI is hostname.
`boolean` | `isIPv4address()` Tell whether or not the host part of this URI is IPv4address.
`boolean` | `isIPv6reference()` Tell whether or not the host part of this URI is IPv6reference.
`boolean` | `isNetPath()` Tell whether or not the relativeURI or heir_part of this URI is net_path.
`boolean` | `isOpaquePart()` Tell whether or not the absoluteURI of this URI is opaque_part.
`boolean` | `isRegName()` Tell whether or not the authority component of this URI is reg_name.
`boolean` | `isRelativeURI()` Tell whether or not this URI is relative.
`boolean` | `isRelPath()` Tell whether or not the relativeURI of this URI is rel_path.
`boolean` | `isServer()` Tell whether or not the authority component of this URI is server.
`void` | `normalize()` Normalizes the path part of this URI.
`protected char[]` | `normalize(char[] path)` Normalize the given hier path part.
`protected void` | `parseAuthority(String original, boolean escaped)` Parse the authority component.
`protected void` | `parseUriReference(String original, boolean escaped)` In order to avoid any possilbity of conflict with non-ASCII characters, Parse a URI reference as a `String` with the character encoding of the local system or the document.
`protected boolean` | `prevalidate(String component, BitSet disallowed)` Pre-validate the unescaped URI string within a specific component.
`protected char[]` | `removeFragmentIdentifier(char[] component)` Remove the fragment identifier of the given component.
`protected char[]` | `resolvePath(char[] basePath, char[] relPath)` Resolve the base and relative path.
`static void` | `setDefaultDocumentCharset(String charset)` Set the default charset of the document.
`static void` | `setDefaultProtocolCharset(String charset)` Set the default charset of the protocol.
`void` | `setEscapedAuthority(String escapedAuthority)` Set the authority.
`void` | `setEscapedFragment(String escapedFragment)` Set the escaped fragment string.
`void` | `setEscapedPath(String escapedPath)` Set the escaped path.
`void` | `setEscapedQuery(String escapedQuery)` Set the escaped query string.
`void` | `setFragment(String fragment)` Set the fragment.
`void` | `setPath(String path)` Set the path.
`void` | `setQuery(String query)` Set the query.
`void` | `setRawAuthority(char[] escapedAuthority)` Set the authority.
`void` | `setRawFragment(char[] escapedFragment)` Set the raw-escaped fragment.
`void` | `setRawPath(char[] escapedPath)` Set the raw-escaped path.
`void` | `setRawQuery(char[] escapedQuery)` Set the raw-escaped query.
`protected void` | `setURI()` Once it's parsed successfully, set this URI.
`String` | `toString()` Get the escaped URI string.
`protected boolean` | `validate(char[] component, BitSet generous)` Validate the URI characters within a specific component.
`protected boolean` | `validate(char[] component, int soffset, int eoffset, BitSet generous)` Validate the URI characters within a specific component.

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

Field Detail

### hash

    protected int hash

  Cache the hash code for this URI.

### _uri

    protected char[] _uri

  This Uniform Resource Identifier (URI). The URI is always in an "escaped" form, since escaping or unescaping a completed URI might change its semantics.

### protocolCharset

    protected String protocolCharset

  The charset of the protocol used by this URI instance.

### defaultProtocolCharset

    protected static String defaultProtocolCharset

  The default charset of the protocol. RFC 2277, 2396

### defaultDocumentCharset

    protected static String defaultDocumentCharset

  The default charset of the document. RFC 2277, 2396 The platform's charset is used for the document by default.

### defaultDocumentCharsetByLocale

    protected static String defaultDocumentCharsetByLocale

### defaultDocumentCharsetByPlatform

    protected static String defaultDocumentCharsetByPlatform

### _scheme

    protected char[] _scheme

  The scheme.

### _opaque

    protected char[] _opaque

  The opaque.

### _authority

    protected char[] _authority

  The authority.

### _userinfo

    protected char[] _userinfo

  The userinfo.

### _host

    protected char[] _host

  The host.

### _port

    protected int _port

  The port.

### _path

    protected char[] _path

  The path.

### _query

    protected char[] _query

  The query.

### _fragment

    protected char[] _fragment

  The fragment.

### rootPath

    protected static final char[] rootPath

  The root path.

### percent

    protected static final BitSet percent

  The percent "%" character always has the reserved purpose of being the escape indicator, it must be escaped as "%25" in order to be used as data within a URI.

### digit

    protected static final BitSet digit

  BitSet for digit.

  >      digit    = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
  >                 "8" | "9"

### alpha

    protected static final BitSet alpha

  BitSet for alpha.

  >      alpha         = lowalpha | upalpha

### alphanum

    protected static final BitSet alphanum

  BitSet for alphanum (join of alpha & digit).

  >       alphanum      = alpha | digit

### hex

    protected static final BitSet hex

  BitSet for hex.

  >      hex           = digit | "A" | "B" | "C" | "D" | "E" | "F" |
  >                              "a" | "b" | "c" | "d" | "e" | "f"

### escaped

    protected static final BitSet escaped

  BitSet for escaped.

  >      escaped       = "%" hex hex

### mark

    protected static final BitSet mark

  BitSet for mark.

  >      mark          = "-" | "_" | "." | "!" | "~" | "*" | "'" |
  >                      "(" | ")"

### unreserved

    protected static final BitSet unreserved

  Data characters that are allowed in a URI but do not have a reserved purpose are called unreserved.

  >      unreserved    = alphanum | mark

### reserved

    protected static final BitSet reserved

  BitSet for reserved.

  >      reserved      = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
  >                      "$" | ","

### uric

    protected static final BitSet uric

  BitSet for uric.

  >      uric          = reserved | unreserved | escaped

### fragment

    protected static final BitSet fragment

  BitSet for fragment (alias for uric).

  >      fragment      = *uric

### query

    protected static final BitSet query

  BitSet for query (alias for uric).

  >      query         = *uric

### pchar

    protected static final BitSet pchar

  BitSet for pchar.

  >      pchar         = unreserved | escaped |
  >                      ":" | "@" | "&" | "=" | "+" | "$" | ","

### param

    protected static final BitSet param

  BitSet for param (alias for pchar).

  >      param         = *pchar

### segment

    protected static final BitSet segment

  BitSet for segment.

  >      segment       = *pchar *( ";" param )

### path_segments

    protected static final BitSet path_segments

  BitSet for path segments.

  >      path_segments = segment *( "/" segment )

### abs_path

    protected static final BitSet abs_path

  URI absolute path.

  >      abs_path      = "/"  path_segments

### uric_no_slash

    protected static final BitSet uric_no_slash

  URI bitset for encoding typical non-slash characters.

  >      uric_no_slash = unreserved | escaped | ";" | "?" | ":" | "@" |
  >                      "&" | "=" | "+" | "$" | ","

### opaque_part

    protected static final BitSet opaque_part

  URI bitset that combines uric_no_slash and uric.

  >      opaque_part   = uric_no_slash *uric

### path

    protected static final BitSet path

  URI bitset that combines absolute path and opaque part.

  >      path          = [ abs_path | opaque_part ]

### port

    protected static final BitSet port

  Port, a logical alias for digit.

### IPv4address

    protected static final BitSet IPv4address

  Bitset that combines digit and dot fo IPv$address.

  >      IPv4address   = 1*digit "." 1*digit "." 1*digit "." 1*digit

### IPv6address

    protected static final BitSet IPv6address

  RFC 2373.

  >      IPv6address = hexpart [ ":" IPv4address ]

### IPv6reference

    protected static final BitSet IPv6reference

  RFC 2732, 2373.

  >      IPv6reference   = "[" IPv6address "]"

### toplabel

    protected static final BitSet toplabel

  BitSet for toplabel.

  >      toplabel      = alpha | alpha *( alphanum | "-" ) alphanum

### domainlabel

    protected static final BitSet domainlabel

  BitSet for domainlabel.

  >      domainlabel   = alphanum | alphanum *( alphanum | "-" ) alphanum

### hostname

    protected static final BitSet hostname

  BitSet for hostname.

  >      hostname      = *( domainlabel "." ) toplabel [ "." ]

### host

    protected static final BitSet host

  BitSet for host.

  >      host          = hostname | IPv4address | IPv6reference

### hostport

    protected static final BitSet hostport

  BitSet for hostport.

  >      hostport      = host [ ":" port ]

### userinfo

    protected static final BitSet userinfo

  Bitset for userinfo.

  >      userinfo      = *( unreserved | escaped |
  >                         ";" | ":" | "&" | "=" | "+" | "$" | "," )

### within_userinfo

    public static final BitSet within_userinfo

  BitSet for within the userinfo component like user and password.

### server

    protected static final BitSet server

  Bitset for server.

  >      server        = [ [ userinfo "@" ] hostport ]

### reg_name

    protected static final BitSet reg_name

  BitSet for reg_name.

  >      reg_name      = 1*( unreserved | escaped | "$" | "," |
  >                          ";" | ":" | "@" | "&" | "=" | "+" )

### authority

    protected static final BitSet authority

  BitSet for authority.

  >      authority     = server | reg_name

### scheme

    protected static final BitSet scheme

  BitSet for scheme.

  >      scheme        = alpha *( alpha | digit | "+" | "-" | "." )

### rel_segment

    protected static final BitSet rel_segment

  BitSet for rel_segment.

  >      rel_segment   = 1*( unreserved | escaped |
  >                          ";" | "@" | "&" | "=" | "+" | "$" | "," )

### rel_path

    protected static final BitSet rel_path

  BitSet for rel_path.

  >      rel_path      = rel_segment [ abs_path ]

### net_path

    protected static final BitSet net_path

  BitSet for net_path.

  >      net_path      = "//" authority [ abs_path ]

### hier_part

    protected static final BitSet hier_part

  BitSet for hier_part.

  >      hier_part     = ( net_path | abs_path ) [ "?" query ]

### relativeURI

    protected static final BitSet relativeURI

  BitSet for relativeURI.

  >      relativeURI   = ( net_path | abs_path | rel_path ) [ "?" query ]

### absoluteURI

    protected static final BitSet absoluteURI

  BitSet for absoluteURI.

  >      absoluteURI   = scheme ":" ( hier_part | opaque_part )

### URI_reference

    protected static final BitSet URI_reference

  BitSet for URI-reference.

  >      URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]

### control

    public static final BitSet control

  BitSet for control.

### space

    public static final BitSet space

  BitSet for space.

### delims

    public static final BitSet delims

  BitSet for delims.

### unwise

    public static final BitSet unwise

  BitSet for unwise.

### disallowed_rel_path

    public static final BitSet disallowed_rel_path

  Disallowed rel_path before escaping.

### disallowed_opaque_part

    public static final BitSet disallowed_opaque_part

  Disallowed opaque_part before escaping.

### allowed_authority

    public static final BitSet allowed_authority

  Those characters that are allowed for the authority component.

### allowed_opaque_part

    public static final BitSet allowed_opaque_part

  Those characters that are allowed for the opaque_part.

### allowed_reg_name

    public static final BitSet allowed_reg_name

  Those characters that are allowed for the reg_name.

### allowed_userinfo

    public static final BitSet allowed_userinfo

  Those characters that are allowed for the userinfo component.

### allowed_within_userinfo

    public static final BitSet allowed_within_userinfo

  Those characters that are allowed for within the userinfo component.

### allowed_IPv6reference

    public static final BitSet allowed_IPv6reference

  Those characters that are allowed for the IPv6reference component. The characters '[', ']' in IPv6reference should be excluded.

### allowed_host

    public static final BitSet allowed_host

  Those characters that are allowed for the host component. The characters '[', ']' in IPv6reference should be excluded.

### allowed_within_authority

    public static final BitSet allowed_within_authority

  Those characters that are allowed for the authority component.

### allowed_abs_path

    public static final BitSet allowed_abs_path

  Those characters that are allowed for the abs_path.

### allowed_rel_path

    public static final BitSet allowed_rel_path

  Those characters that are allowed for the rel_path.

### allowed_within_path

    public static final BitSet allowed_within_path

  Those characters that are allowed within the path.

### allowed_query

    public static final BitSet allowed_query

  Those characters that are allowed for the query component.

### allowed_within_query

    public static final BitSet allowed_within_query

  Those characters that are allowed within the query component.

### allowed_fragment

    public static final BitSet allowed_fragment

  Those characters that are allowed for the fragment component.

### _is_hier_part

    protected boolean _is_hier_part

### _is_opaque_part

    protected boolean _is_opaque_part

### _is_net_path

    protected boolean _is_net_path

### _is_abs_path

    protected boolean _is_abs_path

### _is_rel_path

    protected boolean _is_rel_path

### _is_reg_name

    protected boolean _is_reg_name

### _is_server

    protected boolean _is_server

### _is_hostname

    protected boolean _is_hostname

### _is_IPv4address

    protected boolean _is_IPv4address

### _is_IPv6reference

    protected boolean _is_IPv6reference

Constructor Detail

### URI

    protected URI()

  Create an instance as an internal use

### URI

    public URI(String s,
               boolean escaped,
               String charset)
        throws URIException,
               NullPointerException

  Construct a URI from a string with the given charset. The input string can be either in escaped or unescaped form.

  Parameters:
    `s` - URI character sequence
    `escaped` - `true` if URI character sequence is in escaped form. `false` otherwise.
    `charset` - the charset string to do escape encoding, if required
  Throws:
    `URIException` - If the URI cannot be created.
    `NullPointerException` - if input string is `null`
  Since:
    3.0
  See Also:
    `getProtocolCharset()`

### URI

    public URI(String s,
               boolean escaped)
        throws URIException,
               NullPointerException

  Construct a URI from a string with the given charset. The input string can be either in escaped or unescaped form.

  Parameters:
    `s` - URI character sequence
    `escaped` - `true` if URI character sequence is in escaped form. `false` otherwise.
  Throws:
    `URIException` - If the URI cannot be created.
    `NullPointerException` - if input string is `null`
  Since:
    3.0
  See Also:
    `getProtocolCharset()`

### URI

    public URI(char[] escaped,
               String charset)
        throws URIException,
               NullPointerException

  Deprecated. Use #URI(String, boolean, String)

  Construct a URI as an escaped form of a character array with the given charset.

  Parameters:
    `escaped` - the URI character sequence
    `charset` - the charset string to do escape encoding
  Throws:
    `URIException` - If the URI cannot be created.
    `NullPointerException` - if `escaped` is `null`
  See Also:
    `getProtocolCharset()`

### URI

    public URI(char[] escaped)
        throws URIException,
               NullPointerException

  Deprecated. Use #URI(String, boolean)

  Construct a URI as an escaped form of a character array. An URI can be placed within double-quotes or angle brackets like "http://test.com/" and <http://test.com/>

  Parameters:
    `escaped` - the URI character sequence
  Throws:
    `URIException` - If the URI cannot be created.
    `NullPointerException` - if `escaped` is `null`
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(String original,
               String charset)
        throws URIException

  Deprecated. Use #URI(String, boolean, String)

  Construct a URI from the given string with the given charset.

  Parameters:
    `original` - the string to be represented to URI character sequence It is one of absoluteURI and relativeURI.
    `charset` - the charset string to do escape encoding
  Throws:
    `URIException` - If the URI cannot be created.
  See Also:
    `getProtocolCharset()`

### URI

    public URI(String original)
        throws URIException

  Deprecated. Use #URI(String, boolean)

  Construct a URI from the given string.

  >        URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]

  An URI can be placed within double-quotes or angle brackets like "http://test.com/" and <http://test.com/>

  Parameters:
    `original` - the string to be represented to URI character sequence It is one of absoluteURI and relativeURI.
  Throws:
    `URIException` - If the URI cannot be created.
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(String scheme,
               String schemeSpecificPart,
               String fragment)
        throws URIException

  Construct a general URI from the given components.

  >        URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]
  >        absoluteURI   = scheme ":" ( hier_part | opaque_part )
  >        opaque_part   = uric_no_slash *uric

  It's for absolute URI = <scheme>:<scheme-specific-part># <fragment>.

  Parameters:
    `scheme` - the scheme string
    `schemeSpecificPart` - scheme_specific_part
    `fragment` - the fragment string
  Throws:
    `URIException` - If the URI cannot be created.
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(String scheme,
               String authority,
               String path,
               String query,
               String fragment)
        throws URIException

  Construct a general URI from the given components.

  >        URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]
  >        absoluteURI   = scheme ":" ( hier_part | opaque_part )
  >        relativeURI   = ( net_path | abs_path | rel_path ) [ "?" query ]
  >        hier_part     = ( net_path | abs_path ) [ "?" query ]

  It's for absolute URI = <scheme>:<path>?<query>#< fragment> and relative URI = <path>?<query>#<fragment >.

  Parameters:
    `scheme` - the scheme string
    `authority` - the authority string
    `path` - the path string
    `query` - the query string
    `fragment` - the fragment string
  Throws:
    `URIException` - If the new URI cannot be created.
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(String scheme,
               String userinfo,
               String host,
               int port)
        throws URIException

  Construct a general URI from the given components.

  Parameters:
    `scheme` - the scheme string
    `userinfo` - the userinfo string
    `host` - the host string
    `port` - the port number
  Throws:
    `URIException` - If the new URI cannot be created.
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(String scheme,
               String userinfo,
               String host,
               int port,
               String path)
        throws URIException

  Construct a general URI from the given components.

  Parameters:
    `scheme` - the scheme string
    `userinfo` - the userinfo string
    `host` - the host string
    `port` - the port number
    `path` - the path string
  Throws:
    `URIException` - If the new URI cannot be created.
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(String scheme,
               String userinfo,
               String host,
               int port,
               String path,
               String query)
        throws URIException

  Construct a general URI from the given components.

  Parameters:
    `scheme` - the scheme string
    `userinfo` - the userinfo string
    `host` - the host string
    `port` - the port number
    `path` - the path string
    `query` - the query string
  Throws:
    `URIException` - If the new URI cannot be created.
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(String scheme,
               String userinfo,
               String host,
               int port,
               String path,
               String query,
               String fragment)
        throws URIException

  Construct a general URI from the given components.

  Parameters:
    `scheme` - the scheme string
    `userinfo` - the userinfo string
    `host` - the host string
    `port` - the port number
    `path` - the path string
    `query` - the query string
    `fragment` - the fragment string
  Throws:
    `URIException` - If the new URI cannot be created.
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(String scheme,
               String host,
               String path,
               String fragment)
        throws URIException

  Construct a general URI from the given components.

  Parameters:
    `scheme` - the scheme string
    `host` - the host string
    `path` - the path string
    `fragment` - the fragment string
  Throws:
    `URIException` - If the new URI cannot be created.
  See Also:
    `getDefaultProtocolCharset()`

### URI

    public URI(URI base,
               String relative)
        throws URIException

  Deprecated. Use #URI(URI, String, boolean)

  Construct a general URI with the given relative URI string.

  Parameters:
    `base` - the base URI
    `relative` - the relative URI string
  Throws:
    `URIException` - If the new URI cannot be created.

### URI

    public URI(URI base,
               String relative,
               boolean escaped)
        throws URIException

  Construct a general URI with the given relative URI string.

  Parameters:
    `base` - the base URI
    `relative` - the relative URI string
    `escaped` - `true` if URI character sequence is in escaped form. `false` otherwise.
  Throws:
    `URIException` - If the new URI cannot be created.
  Since:
    3.0

### URI

    public URI(URI base,
               URI relative)
        throws URIException

  Construct a general URI with the given relative URI.

  >        URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]
  >        relativeURI   = ( net_path | abs_path | rel_path ) [ "?" query ]

  Resolving Relative References to Absolute Form. Examples of Resolving Relative URI References Within an object with a well-defined base URI of

  >        http://a/b/c/d;p?q

  the relative URI would be resolved as follows: Normal Examples

  >        g:h           =  g:h
  >        g             =  http://a/b/c/g
  >        ./g           =  http://a/b/c/g
  >        g/            =  http://a/b/c/g/
  >        /g            =  http://a/g
  >        //g           =  http://g
  >        ?y            =  http://a/b/c/?y
  >        g?y           =  http://a/b/c/g?y
  >        #s            =  (current document)#s
  >        g#s           =  http://a/b/c/g#s
  >        g?y#s         =  http://a/b/c/g?y#s
  >        ;x            =  http://a/b/c/;x
  >        g;x           =  http://a/b/c/g;x
  >        g;x?y#s       =  http://a/b/c/g;x?y#s
  >        .             =  http://a/b/c/
  >        ./            =  http://a/b/c/
  >        ..            =  http://a/b/
  >        ../           =  http://a/b/
  >        ../g          =  http://a/b/g
  >        ../..         =  http://a/
  >        ../../        =  http://a/
  >        ../../g       =  http://a/g

  Some URI schemes do not allow a hierarchical syntax matching the syntax, and thus cannot use relative references.

  Parameters:
    `base` - the base URI
    `relative` - the relative URI
  Throws:
    `URIException` - If the new URI cannot be created.

Method Detail

### encode

    protected static char[] encode(String original,
                                   BitSet allowed,
                                   String charset)
                            throws URIException

  Encodes URI string. This is a two mapping, one from original characters to octets, and subsequently a second from octets to URI characters:

  >        original character sequence->octet sequence->URI character sequence

  An escaped octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits representing the octet code. For example, "%20" is the escaped encoding for the US-ASCII space character.

  Conversion from the local filesystem character set to UTF-8 will normally involve a two step process. First convert the local character set to the UCS; then convert the UCS to UTF-8. The first step in the process can be performed by maintaining a mapping table that includes the local character set code and the corresponding UCS code. The next step is to convert the UCS character code to the UTF-8 encoding.

  Mapping between vendor codepages can be done in a very similar manner as described above.

  The only time escape encodings can allowedly be made is when a URI is being created from its component parts. The escape and validate methods are internally performed within this method.

  Parameters:
    `original` - the original character sequence
    `allowed` - those characters that are allowed within a component
    `charset` - the protocol charset
  Returns:
    URI character sequence
  Throws:
    `URIException` - null component or unsupported character encoding

### decode

    protected static String decode(char[] component,
                                   String charset)
                            throws URIException

  Decodes URI encoded string. This is a two mapping, one from URI characters to octets, and subsequently a second from octets to original characters:

  >        URI character sequence->octet sequence->original character sequence

  A URI must be separated into its components before the escaped characters within those components can be allowedly decoded.

  Notice that there is a chance that URI characters that are non UTF-8 may be parsed as valid UTF-8. A recent non-scientific analysis found that EUC encoded Japanese words had a 2.7% false reading; SJIS had a 0.0005% false reading; other encoding such as ASCII or KOI-8 have a 0% false reading.

  The percent "%" character always has the reserved purpose of being the escape indicator, it must be escaped as "%25" in order to be used as data within a URI.

  The unescape method is internally performed within this method.

  Parameters:
    `component` - the URI character sequence
    `charset` - the protocol charset
  Returns:
    original character sequence
  Throws:
    `URIException` - incomplete trailing escape pattern or unsupported character encoding

### decode

    protected static String decode(String component,
                                   String charset)
                            throws URIException

  Decodes URI encoded string. This is a two mapping, one from URI characters to octets, and subsequently a second from octets to original characters:

  >        URI character sequence->octet sequence->original character sequence

  A URI must be separated into its components before the escaped characters within those components can be allowedly decoded.

  Notice that there is a chance that URI characters that are non UTF-8 may be parsed as valid UTF-8. A recent non-scientific analysis found that EUC encoded Japanese words had a 2.7% false reading; SJIS had a 0.0005% false reading; other encoding such as ASCII or KOI-8 have a 0% false reading.

  The percent "%" character always has the reserved purpose of being the escape indicator, it must be escaped as "%25" in order to be used as data within a URI.

  The unescape method is internally performed within this method.

  Parameters:
    `component` - the URI character sequence
    `charset` - the protocol charset
  Returns:
    original character sequence
  Throws:
    `URIException` - incomplete trailing escape pattern or unsupported character encoding
  Since:
    3.0

### prevalidate

    protected boolean prevalidate(String component,
                                  BitSet disallowed)

  Pre-validate the unescaped URI string within a specific component.

  Parameters:
    `component` - the component string within the component
    `disallowed` - those characters disallowed within the component
  Returns:
    if true, it doesn't have the disallowed characters if false, the component is undefined or an incorrect one

### validate

    protected boolean validate(char[] component,
                               BitSet generous)

  Validate the URI characters within a specific component. The component must be performed after escape encoding. Or it doesn't include escaped characters.

  Parameters:
    `component` - the characters sequence within the component
    `generous` - those characters that are allowed within a component
  Returns:
    if true, it's the correct URI character sequence

### validate

    protected boolean validate(char[] component,
                               int soffset,
                               int eoffset,
                               BitSet generous)

  Validate the URI characters within a specific component. The component must be performed after escape encoding. Or it doesn't include escaped characters.

  It's not that much strict, generous. The strict validation might be performed before being called this method.

  Parameters:
    `component` - the characters sequence within the component
    `soffset` - the starting offset of the given component
    `eoffset` - the ending offset of the given component if -1, it means the length of the component
    `generous` - those characters that are allowed within a component
  Returns:
    if true, it's the correct URI character sequence

### parseUriReference

    protected void parseUriReference(String original,
                                     boolean escaped)
                              throws URIException

  In order to avoid any possilbity of conflict with non-ASCII characters, Parse a URI reference as a `String` with the character encoding of the local system or the document.

  The following line is the regular expression for breaking-down a URI reference into its components.

  >        ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
  >         12            3  4          5       6  7        8 9

  For example, matching the above expression to http://jakarta.apache.org/ietf/uri/#Related results in the following subexpression matches:

  >                    $1 = http:
  >       scheme    =  $2 = http
  >                    $3 = //jakarta.apache.org
  >       authority =  $4 = jakarta.apache.org
  >       path      =  $5 = /ietf/uri/
  >                    $6 =
  >       query     =  $7 =
  >                    $8 = #Related
  >       fragment  =  $9 = Related

  Parameters:
    `original` - the original character sequence
    `escaped` - `true` if `original` is escaped
  Throws:
    `URIException` - If an error occurs.

### indexFirstOf

    protected int indexFirstOf(String s,
                               String delims)

  Get the earlier index that to be searched for the first occurrance in one of any of the given string.

  Parameters:
    `s` - the string to be indexed
    `delims` - the delimiters used to index
  Returns:
    the earlier index if there are delimiters

### indexFirstOf

    protected int indexFirstOf(String s,
                               String delims,
                               int offset)

  Get the earlier index that to be searched for the first occurrance in one of any of the given string.

  Parameters:
    `s` - the string to be indexed
    `delims` - the delimiters used to index
    `offset` - the from index
  Returns:
    the earlier index if there are delimiters

### indexFirstOf

    protected int indexFirstOf(char[] s,
                               char delim)

  Get the earlier index that to be searched for the first occurrance in one of any of the given array.

  Parameters:
    `s` - the character array to be indexed
    `delim` - the delimiter used to index
  Returns:
    the ealier index if there are a delimiter

### indexFirstOf

    protected int indexFirstOf(char[] s,
                               char delim,
                               int offset)

  Get the earlier index that to be searched for the first occurrance in one of any of the given array.

  Parameters:
    `s` - the character array to be indexed
    `delim` - the delimiter used to index
    `offset` - The offset.
  Returns:
    the ealier index if there is a delimiter

### parseAuthority

    protected void parseAuthority(String original,
                                  boolean escaped)
                           throws URIException

  Parse the authority component.

  Parameters:
    `original` - the original character sequence of authority component
    `escaped` - `true` if `original` is escaped
  Throws:
    `URIException` - If an error occurs.

### setURI

    protected void setURI()

  Once it's parsed successfully, set this URI.

  See Also:
    `getRawURI()`

### isAbsoluteURI

    public boolean isAbsoluteURI()

  Tell whether or not this URI is absolute.

  Returns:
    true iif this URI is absoluteURI

### isRelativeURI

    public boolean isRelativeURI()

  Tell whether or not this URI is relative.

  Returns:
    true iif this URI is relativeURI

### isHierPart

    public boolean isHierPart()

  Tell whether or not the absoluteURI of this URI is hier_part.

  Returns:
    true iif the absoluteURI is hier_part

### isOpaquePart

    public boolean isOpaquePart()

  Tell whether or not the absoluteURI of this URI is opaque_part.

  Returns:
    true iif the absoluteURI is opaque_part

### isNetPath

    public boolean isNetPath()

  Tell whether or not the relativeURI or heir_part of this URI is net_path. It's the same function as the has_authority() method.

  Returns:
    true iif the relativeURI or heir_part is net_path
  See Also:
    `hasAuthority()`

### isAbsPath

    public boolean isAbsPath()

  Tell whether or not the relativeURI or hier_part of this URI is abs_path.

  Returns:
    true iif the relativeURI or hier_part is abs_path

### isRelPath

    public boolean isRelPath()

  Tell whether or not the relativeURI of this URI is rel_path.

  Returns:
    true iif the relativeURI is rel_path

### hasAuthority

    public boolean hasAuthority()

  Tell whether or not this URI has authority. It's the same function as the is_net_path() method.

  Returns:
    true iif this URI has authority
  See Also:
    `isNetPath()`

### isRegName

    public boolean isRegName()

  Tell whether or not the authority component of this URI is reg_name.

  Returns:
    true iif the authority component is reg_name

### isServer

    public boolean isServer()

  Tell whether or not the authority component of this URI is server.

  Returns:
    true iif the authority component is server

### hasUserinfo

    public boolean hasUserinfo()

  Tell whether or not this URI has userinfo.

  Returns:
    true iif this URI has userinfo

### isHostname

    public boolean isHostname()

  Tell whether or not the host part of this URI is hostname.

  Returns:
    true iif the host part is hostname

### isIPv4address

    public boolean isIPv4address()

  Tell whether or not the host part of this URI is IPv4address.

  Returns:
    true iif the host part is IPv4address

### isIPv6reference

    public boolean isIPv6reference()

  Tell whether or not the host part of this URI is IPv6reference.

  Returns:
    true iif the host part is IPv6reference

### hasQuery

    public boolean hasQuery()

  Tell whether or not this URI has query.

  Returns:
    true iif this URI has query

### hasFragment

    public boolean hasFragment()

  Tell whether or not this URI has fragment.

  Returns:
    true iif this URI has fragment

### setDefaultProtocolCharset

    public static void setDefaultProtocolCharset(String charset)
                                          throws URI.DefaultCharsetChanged

  Set the default charset of the protocol.

  The character set used to store files SHALL remain a local decision and MAY depend on the capability of local operating systems. Prior to the exchange of URIs they SHOULD be converted into a ISO/IEC 10646 format and UTF-8 encoded. This approach, while allowing international exchange of URIs, will still allow backward compatibility with older systems because the code set positions for ASCII characters are identical to the one byte sequence in UTF-8.

  An individual URI scheme may require a single charset, define a default charset, or provide a way to indicate the charset used.

  Always all the time, the setter method is always succeeded and throws `DefaultCharsetChanged` exception. So API programmer must follow the following way: ``

        import org.apache.util.URI$DefaultCharsetChanged;
            .
            .
            .
        try {
            URI.setDefaultProtocolCharset("UTF-8");
        } catch (DefaultCharsetChanged cc) {
            // CASE 1: the exception could be ignored, when it is set by user
            if (cc.getReasonCode() == DefaultCharsetChanged.PROTOCOL_CHARSET) {
            // CASE 2: let user know the default protocol charset changed
            } else {
            // CASE 2: let user know the default document charset changed
            }
        }

  The API programmer is responsible to set the correct charset. And each application should remember its own charset to support.

  Parameters:
    `charset` - the default charset for each protocol
  Throws:
    `URI.DefaultCharsetChanged` - default charset changed

### getDefaultProtocolCharset

    public static String getDefaultProtocolCharset()

  Get the default charset of the protocol.

  An individual URI scheme may require a single charset, define a default charset, or provide a way to indicate the charset used.

  To work globally either requires support of a number of character sets and to be able to convert between them, or the use of a single preferred character set. For support of global compatibility it is STRONGLY RECOMMENDED that clients and servers use UTF-8 encoding when exchanging URIs.

  Returns:
    the default charset string

### getProtocolCharset

    public String getProtocolCharset()

  Get the protocol charset used by this current URI instance. It was set by the constructor for this instance. If it was not set by contructor, it will return the default protocol charset.

  Returns:
    the protocol charset string
  See Also:
    `getDefaultProtocolCharset()`

### setDefaultDocumentCharset

    public static void setDefaultDocumentCharset(String charset)
                                          throws URI.DefaultCharsetChanged

  Set the default charset of the document.

  Notice that it will be possible to contain mixed characters (e.g. ftp://host/KoreanNamespace/ChineseResource). To handle the Bi-directional display of these character sets, the protocol charset could be simply used again. Because it's not yet implemented that the insertion of BIDI control characters at different points during composition is extracted.

  Always all the time, the setter method is always succeeded and throws `DefaultCharsetChanged` exception. So API programmer must follow the following way: ``

        import org.apache.util.URI$DefaultCharsetChanged;
            .
            .
            .
        try {
            URI.setDefaultDocumentCharset("EUC-KR");
        } catch (DefaultCharsetChanged cc) {
            // CASE 1: the exception could be ignored, when it is set by user
            if (cc.getReasonCode() == DefaultCharsetChanged.DOCUMENT_CHARSET) {
            // CASE 2: let user know the default document charset changed
            } else {
            // CASE 2: let user know the default protocol charset changed
            }
        }

  The API programmer is responsible to set the correct charset. And each application should remember its own charset to support.

  Parameters:
    `charset` - the default charset for the document
  Throws:
    `URI.DefaultCharsetChanged` - default charset changed

### getDefaultDocumentCharset

    public static String getDefaultDocumentCharset()

  Get the recommended default charset of the document.

  Returns:
    the default charset string

### getDefaultDocumentCharsetByLocale

    public static String getDefaultDocumentCharsetByLocale()

  Get the default charset of the document by locale.

  Returns:
    the default charset string by locale

### getDefaultDocumentCharsetByPlatform

    public static String getDefaultDocumentCharsetByPlatform()

  Get the default charset of the document by platform.

  Returns:
    the default charset string by platform

### getRawScheme

    public char[] getRawScheme()

  Get the scheme.

  Returns:
    the scheme

### getScheme

    public String getScheme()

  Get the scheme.

  Returns:
    the scheme null if undefined scheme

### setRawAuthority

    public void setRawAuthority(char[] escapedAuthority)
                         throws URIException,
                                NullPointerException

  Set the authority. It can be one type of server, hostport, hostname, IPv4address, IPv6reference and reg_name.

  >        authority     = server | reg_name

  Parameters:
    `escapedAuthority` - the raw escaped authority
  Throws:
    `URIException` - If `parseAuthority(java.lang.String,boolean)` fails
    `NullPointerException` - null authority

### setEscapedAuthority

    public void setEscapedAuthority(String escapedAuthority)
                             throws URIException

  Set the authority. It can be one type of server, hostport, hostname, IPv4address, IPv6reference and reg_name. Note that there is no setAuthority method by the escape encoding reason.

  Parameters:
    `escapedAuthority` - the escaped authority string
  Throws:
    `URIException` - If `parseAuthority(java.lang.String,boolean)` fails

### getRawAuthority

    public char[] getRawAuthority()

  Get the raw-escaped authority.

  Returns:
    the raw-escaped authority

### getEscapedAuthority

    public String getEscapedAuthority()

  Get the escaped authority.

  Returns:
    the escaped authority

### getAuthority

    public String getAuthority()
                        throws URIException

  Get the authority.

  Returns:
    the authority
  Throws:
    `URIException` - If `decode(char[], java.lang.String)` fails

### getRawUserinfo

    public char[] getRawUserinfo()

  Get the raw-escaped userinfo.

  Returns:
    the raw-escaped userinfo
  See Also:
    `getAuthority()`

### getEscapedUserinfo

    public String getEscapedUserinfo()

  Get the escaped userinfo.

  Returns:
    the escaped userinfo
  See Also:
    `getAuthority()`

### getUserinfo

    public String getUserinfo()
                       throws URIException

  Get the userinfo.

  Returns:
    the userinfo
  Throws:
    `URIException` - If `decode(char[], java.lang.String)` fails
  See Also:
    `getAuthority()`

### getRawHost

    public char[] getRawHost()

  Get the host.

  >        host          = hostname | IPv4address | IPv6reference

  Returns:
    the host
  See Also:
    `getAuthority()`

### getHost

    public String getHost()
                   throws URIException

  Get the host.

  >        host          = hostname | IPv4address | IPv6reference

  Returns:
    the host
  Throws:
    `URIException` - If `decode(char[], java.lang.String)` fails
  See Also:
    `getAuthority()`

### getPort

    public int getPort()

  Get the port. In order to get the specfic default port, the specific protocol-supported class extended from the URI class should be used. It has the server-based naming authority.

  Returns:
    the port if -1, it has the default port for the scheme or the server-based naming authority is not supported in the specific URI.

### setRawPath

    public void setRawPath(char[] escapedPath)
                    throws URIException

  Set the raw-escaped path.

  Parameters:
    `escapedPath` - the path character sequence
  Throws:
    `URIException` - encoding error or not proper for initial instance
  See Also:
    `encode(java.lang.String, java.util.BitSet, java.lang.String)`

### setEscapedPath

    public void setEscapedPath(String escapedPath)
                        throws URIException

  Set the escaped path.

  Parameters:
    `escapedPath` - the escaped path string
  Throws:
    `URIException` - encoding error or not proper for initial instance
  See Also:
    `encode(java.lang.String, java.util.BitSet, java.lang.String)`

### setPath

    public void setPath(String path)
                 throws URIException

  Set the path.

  Parameters:
    `path` - the path string
  Throws:
    `URIException` - set incorrectly or fragment only
  See Also:
    `encode(java.lang.String, java.util.BitSet, java.lang.String)`

### resolvePath

    protected char[] resolvePath(char[] basePath,
                                 char[] relPath)
                          throws URIException

  Resolve the base and relative path.

  Parameters:
    `basePath` - a character array of the basePath
    `relPath` - a character array of the relPath
  Returns:
    the resolved path
  Throws:
    `URIException` - no more higher path level to be resolved

### getRawCurrentHierPath

    protected char[] getRawCurrentHierPath(char[] path)
                                    throws URIException

  Get the raw-escaped current hierarchy level in the given path. If the last namespace is a collection, the slash mark ('/') should be ended with at the last character of the path string.

  Parameters:
    `path` - the path
  Returns:
    the current hierarchy level
  Throws:
    `URIException` - no hierarchy level

### getRawCurrentHierPath

    public char[] getRawCurrentHierPath()
                                 throws URIException

  Get the raw-escaped current hierarchy level.

  Returns:
    the raw-escaped current hierarchy level
  Throws:
    `URIException` - If `getRawCurrentHierPath(char[])` fails.

### getEscapedCurrentHierPath

    public String getEscapedCurrentHierPath()
                                     throws URIException

  Get the escaped current hierarchy level.

  Returns:
    the escaped current hierarchy level
  Throws:
    `URIException` - If `getRawCurrentHierPath(char[])` fails.

### getCurrentHierPath

    public String getCurrentHierPath()
                              throws URIException

  Get the current hierarchy level.

  Returns:
    the current hierarchy level
  Throws:
    `URIException` - If `getRawCurrentHierPath(char[])` fails.
  See Also:
    `decode(char[], java.lang.String)`

### getRawAboveHierPath

    public char[] getRawAboveHierPath()
                               throws URIException

  Get the level above the this hierarchy level.

  Returns:
    the raw above hierarchy level
  Throws:
    `URIException` - If `getRawCurrentHierPath(char[])` fails.

### getEscapedAboveHierPath

    public String getEscapedAboveHierPath()
                                   throws URIException

  Get the level above the this hierarchy level.

  Returns:
    the raw above hierarchy level
  Throws:
    `URIException` - If `getRawCurrentHierPath(char[])` fails.

### getAboveHierPath

    public String getAboveHierPath()
                            throws URIException

  Get the level above the this hierarchy level.

  Returns:
    the above hierarchy level
  Throws:
    `URIException` - If `getRawCurrentHierPath(char[])` fails.
  See Also:
    `decode(char[], java.lang.String)`

### getRawPath

    public char[] getRawPath()

  Get the raw-escaped path.

  >        path          = [ abs_path | opaque_part ]

  Returns:
    the raw-escaped path

### getEscapedPath

    public String getEscapedPath()

  Get the escaped path.

  >        path          = [ abs_path | opaque_part ]
  >        abs_path      = "/"  path_segments
  >        opaque_part   = uric_no_slash *uric

  Returns:
    the escaped path string

### getPath

    public String getPath()
                   throws URIException

  Get the path.

  >        path          = [ abs_path | opaque_part ]

  Returns:
    the path string
  Throws:
    `URIException` - If `decode(char[], java.lang.String)` fails.
  See Also:
    `decode(char[], java.lang.String)`

### getRawName

    public char[] getRawName()

  Get the raw-escaped basename of the path.

  Returns:
    the raw-escaped basename

### getEscapedName

    public String getEscapedName()

  Get the escaped basename of the path.

  Returns:
    the escaped basename string

### getName

    public String getName()
                   throws URIException

  Get the basename of the path.

  Returns:
    the basename string
  Throws:
    `URIException` - incomplete trailing escape pattern or unsupported character encoding
  See Also:
    `decode(char[], java.lang.String)`

### getRawPathQuery

    public char[] getRawPathQuery()

  Get the raw-escaped path and query.

  Returns:
    the raw-escaped path and query

### getEscapedPathQuery

    public String getEscapedPathQuery()

  Get the escaped query.

  Returns:
    the escaped path and query string

### getPathQuery

    public String getPathQuery()
                        throws URIException

  Get the path and query.

  Returns:
    the path and query string.
  Throws:
    `URIException` - incomplete trailing escape pattern or unsupported character encoding
  See Also:
    `decode(char[], java.lang.String)`

### setRawQuery

    public void setRawQuery(char[] escapedQuery)
                     throws URIException

  Set the raw-escaped query.

  Parameters:
    `escapedQuery` - the raw-escaped query
  Throws:
    `URIException` - escaped query not valid

### setEscapedQuery

    public void setEscapedQuery(String escapedQuery)
                         throws URIException

  Set the escaped query string.

  Parameters:
    `escapedQuery` - the escaped query string
  Throws:
    `URIException` - escaped query not valid

### setQuery

    public void setQuery(String query)
                  throws URIException

  Set the query.

  When a query string is not misunderstood the reserved special characters ("&", "=", "+", ",", and "$") within a query component, it is recommended to use in encoding the whole query with this method.

  The additional APIs for the special purpose using by the reserved special characters used in each protocol are implemented in each protocol classes inherited from `URI`. So refer to the same-named APIs implemented in each specific protocol instance.

  Parameters:
    `query` - the query string.
  Throws:
    `URIException` - incomplete trailing escape pattern or unsupported character encoding
  See Also:
    `encode(java.lang.String, java.util.BitSet, java.lang.String)`

### getRawQuery

    public char[] getRawQuery()

  Get the raw-escaped query.

  Returns:
    the raw-escaped query

### getEscapedQuery

    public String getEscapedQuery()

  Get the escaped query.

  Returns:
    the escaped query string

### getQuery

    public String getQuery()
                    throws URIException

  Get the query.

  Returns:
    the query string.
  Throws:
    `URIException` - incomplete trailing escape pattern or unsupported character encoding
  See Also:
    `decode(char[], java.lang.String)`

### setRawFragment

    public void setRawFragment(char[] escapedFragment)
                        throws URIException

  Set the raw-escaped fragment.

  Parameters:
    `escapedFragment` - the raw-escaped fragment
  Throws:
    `URIException` - escaped fragment not valid

### setEscapedFragment

    public void setEscapedFragment(String escapedFragment)
                            throws URIException

  Set the escaped fragment string.

  Parameters:
    `escapedFragment` - the escaped fragment string
  Throws:
    `URIException` - escaped fragment not valid

### setFragment

    public void setFragment(String fragment)
                     throws URIException

  Set the fragment.

  Parameters:
    `fragment` - the fragment string.
  Throws:
    `URIException` - If an error occurs.

### getRawFragment

    public char[] getRawFragment()

  Get the raw-escaped fragment.

  The optional fragment identifier is not part of a URI, but is often used in conjunction with a URI.

  The format and interpretation of fragment identifiers is dependent on the media type [RFC2046] of the retrieval result.

  A fragment identifier is only meaningful when a URI reference is intended for retrieval and the result of that retrieval is a document for which the identified fragment is consistently defined.

  Returns:
    the raw-escaped fragment

### getEscapedFragment

    public String getEscapedFragment()

  Get the escaped fragment.

  Returns:
    the escaped fragment string

### getFragment

    public String getFragment()
                       throws URIException

  Get the fragment.

  Returns:
    the fragment string
  Throws:
    `URIException` - incomplete trailing escape pattern or unsupported character encoding
  See Also:
    `decode(char[], java.lang.String)`

### removeFragmentIdentifier

    protected char[] removeFragmentIdentifier(char[] component)

  Remove the fragment identifier of the given component.

  Parameters:
    `component` - the component that a fragment may be included
  Returns:
    the component that the fragment identifier is removed

### normalize

    protected char[] normalize(char[] path)
                        throws URIException

  Normalize the given hier path part.

  Algorithm taken from URI reference parser at http://www.apache.org/~fielding/uri/rev-2002/issues.html.

  Parameters:
    `path` - the path to normalize
  Returns:
    the normalized path
  Throws:
    `URIException` - no more higher path level to be normalized

### normalize

    public void normalize()
                   throws URIException

  Normalizes the path part of this URI. Normalization is only meant to be performed on URIs with an absolute path. Calling this method on a relative path URI will have no effect.

  Throws:
    `URIException` - no more higher path level to be normalized
  See Also:
    `isAbsPath()`

### equals

    protected boolean equals(char[] first,
                             char[] second)

  Test if the first array is equal to the second array.

  Parameters:
    `first` - the first character array
    `second` - the second character array
  Returns:
    true if they're equal

### equals

    public boolean equals(Object obj)

  Test an object if this URI is equal to another.

  Overrides:
    `equals` in class `Object`
  Parameters:
    `obj` - an object to compare
  Returns:
    true if two URI objects are equal

### hashCode

    public int hashCode()

  Return a hash code for this URI.

  Overrides:
    `hashCode` in class `Object`
  Returns:
    a has code value for this URI

### compareTo

    public int compareTo(Object obj)
                  throws ClassCastException

  Compare this URI to another object.

  Specified by:
    `compareTo` in interface `Comparable`
  Parameters:
    `obj` - the object to be compared.
  Returns:
    0, if it's same, -1, if failed, first being compared with in the authority component
  Throws:
    `ClassCastException` - not URI argument

### clone

    public Object clone()
                 throws CloneNotSupportedException

  Create and return a copy of this object, the URI-reference containing the userinfo component. Notice that the whole URI-reference including the userinfo component counld not be gotten as a `String`.

  To copy the identical `URI` object including the userinfo component, it should be used.

  Overrides:
    `clone` in class `Object`
  Returns:
    a clone of this instance
  Throws:
    `CloneNotSupportedException`

### getRawURI

    public char[] getRawURI()

  It can be gotten the URI character sequence. It's raw-escaped. For the purpose of the protocol to be transported, it will be useful.

  It is clearly unwise to use a URL that contains a password which is intended to be secret. In particular, the use of a password within the 'userinfo' component of a URL is strongly disrecommended except in those rare cases where the 'password' parameter is intended to be public.

  When you want to get each part of the userinfo, you need to use the specific methods in the specific URL. It depends on the specific URL.

  Returns:
    the URI character sequence

### getEscapedURI

    public String getEscapedURI()

  It can be gotten the URI character sequence. It's escaped. For the purpose of the protocol to be transported, it will be useful.

  Returns:
    the escaped URI string

### getURI

    public String getURI()
                  throws URIException

  It can be gotten the URI character sequence.

  Returns:
    the original URI string
  Throws:
    `URIException` - incomplete trailing escape pattern or unsupported character encoding
  See Also:
    `decode(char[], java.lang.String)`

### getRawURIReference

    public char[] getRawURIReference()

  Get the URI reference character sequence.

  Returns:
    the URI reference character sequence

### getEscapedURIReference

    public String getEscapedURIReference()

  Get the escaped URI reference string.

  Returns:
    the escaped URI reference string

### getURIReference

    public String getURIReference()
                           throws URIException

  Get the original URI reference string.

  Returns:
    the original URI reference string
  Throws:
    `URIException` - If `decode(char[], java.lang.String)` fails.

### toString

    public String toString()

  Get the escaped URI string.

  On the document, the URI-reference form is only used without the userinfo component like http://jakarta.apache.org/ by the security reason. But the URI-reference form with the userinfo component could be parsed.

  In other words, this URI and any its subclasses must not expose the URI-reference expression with the userinfo component like http://user:password@hostport/restricted_zone.
  It means that the API client programmer should extract each user and password to access manually. Probably it will be supported in the each subclass, however, not a whole URI-reference expression.

  Overrides:
    `toString` in class `Object`
  Returns:
    the escaped URI string
  See Also:
    `clone()`

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 © 2001-2007 Apache Software Foundation. All Rights Reserved.