Java Doc for URI.java in  » Net » Apache-common-HttpClient » org » apache » commons » httpclient » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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
 

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
 

author:
   Sung-Gu
author:
   Mike Bowler
version:
   $Revision: 564973 $ $Date: 2002/03/14 15:14:01

 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
 .

 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.

 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.

 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.

Notice that it will be possible to contain mixed characters (e.g. ftp://host/KoreanNamespace/ChineseResource).

The character set used to store files SHALL remain a local decision and MAY depend on the capability of local operating systems.

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.

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.

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

 IPv6address = hexpart [ ":" IPv4address ]
 

 IPv6reference   = "[" IPv6address "]"
 

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

 abs_path      = "/"  path_segments
 

 absoluteURI   = scheme ":" ( hier_part | opaque_part )
 

 alpha         = lowalpha | upalpha
 

 alphanum      = alpha | digit
 

 authority     = server | reg_name
 

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

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

 escaped       = "%" hex hex
 

 fragment      = *uric
 

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

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

 host          = hostname | IPv4address | IPv6reference
 

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

 hostport      = host [ ":" port ]
 

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

 net_path      = "//" authority [ abs_path ]
 

 opaque_part   = uric_no_slash *uric
 

 param         = *pchar
 

 path          = [ abs_path | opaque_part ]
 

 path_segments = segment *( "/" segment )
 

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

 query         = *uric
 

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

 rel_path      = rel_segment [ abs_path ]
 

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

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

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

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

 segment       = *pchar *( ";" param )
 

 server        = [ [ userinfo "@" ] hostport ]
 

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

 unreserved    = alphanum | mark
 

 uric          = reserved | unreserved | escaped
 

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

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

 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 sequenceIt is one of absoluteURI and relativeURI.
throws:
  URIException - If the URI cannot be created.
See Also:   URI.getDefaultProtocolCharset

 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
Parameters:
  schemeSpecificPart - scheme_specific_part
Parameters:
  fragment - the fragment string
throws:
  URIException - If the URI cannot be created.
See Also:   URI.getDefaultProtocolCharset

 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
Parameters:
  authority - the authority string
Parameters:
  path - the path string
Parameters:
  query - the query string
Parameters:
  fragment - the fragment string
throws:
  URIException - If the new URI cannot be created.
See Also:   URI.getDefaultProtocolCharset

 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
Parameters:
  relative - the relative URI
throws:
  URIException - If the new URI cannot be created.

To copy the identical URI object including the userinfo component, it should be used. a clone of this instance

 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
Parameters:
  charset - the protocol charset original character sequence
throws:
  URIException - incomplete trailing escape pattern or unsupportedcharacter encoding

 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
Parameters:
  charset - the protocol charset original character sequence
throws:
  URIException - incomplete trailing escape pattern or unsupportedcharacter encoding
since:
   3.0

 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
Parameters:
  allowed - those characters that are allowed within a component
Parameters:
  charset - the protocol charset URI character sequence
throws:
  URIException - null component or unsupported character encoding

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. the default charset string

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

the escaped path string

 host          = hostname | IPv4address | IPv6reference
 

the host
throws:
  URIException - If URI.decode fails
See Also:   URI.getAuthority

 path          = [ abs_path | opaque_part ]
 

the path string
throws:
  URIException - If URI.decode fails.
See Also:   URI.decode

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. the raw-escaped fragment

 host          = hostname | IPv4address | IPv6reference
 

the host
See Also:   URI.getAuthority

 path          = [ abs_path | opaque_part ]
 

the raw-escaped path

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. the URI character sequence

Algorithm taken from URI reference parser at http://www.apache.org/~fielding/uri/rev-2002/issues.html.
Parameters:
  path - the path to normalize the normalized path
throws:
  URIException - no more higher path level to be normalized

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
Parameters:
  escaped - true if original is escaped
throws:
  URIException - If an error occurs.

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 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
 }
 }
 

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 unsupportedcharacter encoding
See Also:   URI.encode

 authority     = server | reg_name
 

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

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. the escaped URI string
See Also:   URI.clone()