Class UsableURI

java.lang.Object
org.archive.url.LaxURI
org.archive.url.UsableURI
All Implemented Interfaces:
Serializable, CharSequence, Cloneable, Comparable
public class UsableURI extends LaxURI implements CharSequence, Serializable
Usable URI. This class wraps URI adding caching and methods. It cannot be instantiated directly. Go via UURIFactory.

We used to use URI for parsing URIs but ran across quirky behaviors and bugs. URI is not subclassable -- its final -- and its unlikely that java.net.URI will change any time soon (See Gordon's considered petition here: java.net.URI should have loose/tolerant/compatibility option (or allow reuse)).

This class tries to cache calculated strings such as the extracted host and this class as a string rather than have the parent class rerun its calculation everytime.

Author:
gojomo, stack
See Also:

  • Field Details

    • MAX_URL_LENGTH

      public static final int MAX_URL_LENGTH
      Consider URIs too long for IE as illegal.
      See Also:

    • MASSAGEHOST_PATTERN

      public static final String MASSAGEHOST_PATTERN
      See Also:

    • 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 Details

  • Method Details

    • resolve

      public UsableURI resolve(String uri) throws URIException
      Parameters:
      uri - URI as string that is resolved relative to this UURI.
      Returns:
      UURI that uses this UURI as base.
      Throws:
      URIException

    • resolve

      public UsableURI resolve(String uri, boolean e) throws URIException
      Parameters:
      uri - URI as string that is resolved relative to this UURI.
      e - True if escaped.
      Returns:
      UURI that uses this UURI as base.
      Throws:
      URIException

    • resolve

      public UsableURI resolve(String uri, boolean e, String charset) throws URIException
      Parameters:
      uri - URI as string that is resolved relative to this UURI.
      e - True if uri is escaped.
      charset - Charset to use.
      Returns:
      UURI that uses this UURI as base.
      Throws:
      URIException

    • equals

      public boolean equals(Object obj)
      Test an object if this UURI is equal to another.
      Parameters:
      obj - an object to compare
      Returns:
      true if two URI objects are equal

    • getHostBasename

      public String getHostBasename() throws URIException
      Strips www variants from the host. Strips www[0-9]*\. from the host. If calling getHostBaseName becomes a performance issue we should consider adding the hostBasename member that is set on initialization.
      Returns:
      Host's basename.
      Throws:
      URIException

    • toCustomString

      public String toCustomString()
      Returns an alternate, functional String representation -- in this case, a String of the URI represented by this UURI instance.
      Returns:

    • toString

      public String toString()
      Override to cache result TODO: eliminate, moving most callers to toCustomString, to avoid overloading/diluting toString() (see http://webteam.archive.org/confluence/display/Heritrix/Preserve+toString%28%29 )
      Specified by:
      toString in interface CharSequence
      Returns:
      String representation of this URI
      See Also:

    • toUnicodeHostString

      public String toUnicodeHostString()
      In the case of a puny encoded IDN, this method returns the decoded Unicode version.

      Most of this implementation is copied from URI.setURI().

      Returns:
      decoded IDN version of URI

    • 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

    • coalesceUriStrings

      protected void coalesceUriStrings()
      The two String fields cachedString and cachedEscapedURI are usually identical; if so, coalesce into a single instance.

    • 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:

    • coalesceHostAuthorityStrings

      protected void coalesceHostAuthorityStrings()
      The two String fields cachedHost and cachedAuthorityMinusUserInfo are usually identical; if so, coalesce into a single instance.

    • getReferencedHost

      public String getReferencedHost() throws URIException
      Return the referenced host in the UURI, if any, also extracting the host of a DNS-lookup URI where necessary.
      Returns:
      the target or topic host of the URI
      Throws:
      URIException

    • getSurtForm

      public String getSurtForm()
      Returns:
      Return the 'SURT' format of this UURI

    • getAuthorityMinusUserinfo

      public String getAuthorityMinusUserinfo() throws URIException
      Return the authority minus userinfo (if any). If no userinfo present, just returns the authority.
      Returns:
      The authority stripped of any userinfo if present.
      Throws:
      URIException

    • length

      public int length()
      Specified by:
      length in interface CharSequence

    • charAt

      public char charAt(int index)
      Specified by:
      charAt in interface CharSequence

    • subSequence

      public CharSequence subSequence(int start, int end)
      Specified by:
      subSequence in interface CharSequence

    • compareTo

      public int compareTo(Object arg0)
      Compare this URI to another object.
      Specified by:
      compareTo in interface Comparable
      Parameters:
      arg0 - the object to be compared.
      Returns:
      0, if it's same, -1, if failed, first being compared with in the authority component

    • hasScheme

      public static boolean hasScheme(String possibleUrl)
      Test if passed String has likely URI scheme prefix.
      Parameters:
      possibleUrl - URL string to examine.
      Returns:
      True if passed string looks like it could be an URL.

    • parseFilename

      public static String parseFilename(String pathOrUri) throws URISyntaxException
      Parameters:
      pathOrUri - A file path or a URI.
      Returns:
      Path parsed from passed pathOrUri.
      Throws:
      URISyntaxException

    • 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

    • 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

    • 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

    • 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:

    • 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:

    • 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 org.archive.url.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:
      org.archive.url.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:

    • setDefaultDocumentCharset

      public static void setDefaultDocumentCharset(String charset) throws org.archive.url.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:
      org.archive.url.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(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(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:

    • getEscapedUserinfo

      public String getEscapedUserinfo()
      Get the escaped userinfo.
      Returns:
      the escaped userinfo
      See Also:

    • getUserinfo

      public String getUserinfo() throws URIException
      Get the userinfo.
      Returns:
      the userinfo
      Throws:
      URIException - If decode(char[], java.lang.String) fails
      See Also:

    • getRawHost

      public char[] getRawHost()
      Get the host. 

         host          = hostname | IPv4address | IPv6reference

      Returns:
      the host
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

    • 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:

    • 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

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

    • hashCode

      public int hashCode()
      Return a hash code for this URI.
      Overrides:
      hashCode in class Object
      Returns:
      a has code value for this URI

    • 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

    • 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.