Class URI

java.lang.Object
java.net.URI
public class URI extends java.lang.Object

An implementation of a Univeral Resource Identifier (URI). While the output is mostly compatible with the Java 6 API, there are a few somewhat subtle differences:

1) For socket related URIs, the toString() methods use semicolon (;) as the
   query marker instead of the normal question mark (?), and the parameters are separated
   with a semicolon instead of the normal ampersand (&).  With this, the URIs are compatible
   with those used by J2ME socket connectors.  (The Java 6 API treats socket URIs as URNs).
2) This implementation does not yet "rigorously parse IPv4" addresses like the Java 6 version does,
   the host address is simply stored as provided by the caller.  This will be enhanced using the
   InetAddress class when available.
3) The characters defined as legal "other characters" are not all interpreted correctly, which
   just means some unicode characters will get encoded that aren't required to be.  The
   method URIHelper.isLegalUnicode() needs to be inspected further.
4) Because of 3) toASCIIString() and toString() return the same value.
TODO: finish this list

  • Constructor Summary

    Constructors
    Constructor
    Description
    URI(java.lang.String uriString)
    Constructor that parses its values from a URI string.
    URI(java.lang.String scheme, java.lang.String ssp, java.lang.String fragment)
    Constructor for building URNs.
    URI(java.lang.String scheme, java.lang.String userInfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment)
    Constructor to create a new URI object.
    URI(java.lang.String scheme, java.lang.String authority, java.lang.String path, java.lang.String query, java.lang.String fragment)
    Constructor to create a new URI object.

  • Method Summary

    Modifier and Type
    Method
    Description
    static URI
    create(java.lang.String uriString)
    A convenience factory method, intended to be used when the URI string is known to be valid (ie. a static application URI), so it is not needed for the caller to handle invalid syntax.
    boolean
    equals(java.lang.Object that)
     
    java.lang.String
    getAuthority()
    Returns
    java.lang.String
    getFragment()
    Get the decoded fragment (otherwise known as the "reference" or "anchor") part of the uri.
    java.lang.String
    getHost()
    Get the host name part of the URI.
    java.lang.String
    getPath()
    Get the decoded path part of the uri.
    int
    getPort()
    Get the port number for this URI.
    java.lang.String
    getQuery()
    Get the decoded query part of the uri.
    java.lang.String
    getRawAuthority()
    Returns
    java.lang.String
    getRawFragment()
    Get the encoded fragment (otherwise known as the "reference" or "anchor") part of the uri.
    java.lang.String
    getRawPath()
    Get the encoded path part of the uri.
    java.lang.String
    getRawQuery()
    Get the encoded query part of the uri.
    java.lang.String
    getRawSchemeSpecificPart()
    Returns
    java.lang.String
    getRawUserInfo()
    Returns
    java.lang.String
    getScheme()
    Get the scheme part of the URI.
    java.lang.String
    getSchemeSpecificPart()
    Returns
    java.lang.String
    getUserInfo()
    Returns
    int
    hashCode()
     
    boolean
    isAbsolute()
    Returns
    boolean
    isOpaque()
    Returns
    URI
    normalize()
    Normalize a URI by removing any "./" segments, and "path/../" segments.
    protected void
    parseSchemeSpecificPart(java.lang.String ssp, boolean encode)
    Utility method used to parse a given scheme specific part.
    protected void
    parseURI(java.lang.String uriString)
    Rather than attempting to process the uri string in a linear fashion, this implementation works its way from outside-in
    protected java.lang.String
    rebuildSchemeSpecificPart()
    Utility method to construct the scheme specific part from the uri segments (less scheme and fragment)
    URI
    relativize(URI uri)
    Create a relative URI object against this URI, given the uri parameter.
    URI
    resolve(URI uri)
    Resolve a relative URI by merging it with this URI.
    protected void
    setAuthority(java.lang.String newAuthority, boolean encode)
    Utility method - set the part, ensuring valid format.
    protected void
    setAuthority(java.lang.String host, int port, java.lang.String userInfo, boolean encode)
    Utility method to construct the authority segment from given host, port, and userinfo segments.
    protected void
    setFragment(java.lang.String fragment, boolean encode)
    Utility method to set the fragment.
    protected void
    setPath(java.lang.String path, boolean encode)
    Utility method to set the path.
    protected void
    setQuery(java.lang.String query, boolean encode)
    Utility method to set the query.
    protected void
    setScheme(java.lang.String scheme)
    Utility method - set the scheme, ensuring valid format, and determining the query separator to use.
    protected void
    setSchemeSpecificPart(java.lang.String ssp, boolean encode)
    Utility method - set the scheme specific part, ensuring valid format.
    java.lang.String
    toASCIIString()
    Returns
    java.lang.String
    toString()
    Returns

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • URI

      public URI(java.lang.String scheme, java.lang.String userInfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment) throws URISyntaxException

      Constructor to create a new URI object. The userInfo, path, query and fragment should be unencoded values - they will be encoded as required.

      Parameters

      • scheme: @param scheme the scheme of the URI (for URLs, this would be the protocol), or null for relative URIs.

      • userInfo: @param userInfo the unencoded userinfo segment (ie. username:password) or null.

      • host: the hostname or address, or null.

      • port: the host port, or -1.

      • path: the unencoded path segment.

      • query: the unencoded query segment.

      • fragment: @param fragment the unencoded fragment (often referred to as the 'reference' or 'anchor'), or null.

      Throws
      • URISyntaxException: if any of the fragments are invalid.
      Throws:
      URISyntaxException

    • URI

      public URI(java.lang.String scheme, java.lang.String authority, java.lang.String path, java.lang.String query, java.lang.String fragment) throws URISyntaxException

      Constructor to create a new URI object. The authority, path, query and fragment should be unencoded values - they will be encoded as required.

      Parameters

      • scheme: @param scheme the scheme of the URI (for URLs, this would be the protocol), or null for relative URIs.

      • authority: @param authority the unencoded authority segment (ie. username:password@host:port, or simply: host) or null.

      • path: the unencoded path segment.

      • query: the unencoded query segment.

      • fragment: @param fragment the unencoded fragment (often referred to as the 'reference' or 'anchor'), or null.

      Throws
      • URISyntaxException: if any of the fragments are invalid.
      Throws:
      URISyntaxException

    • URI

      public URI(java.lang.String scheme, java.lang.String ssp, java.lang.String fragment) throws URISyntaxException

      Constructor for building URNs. The ssp and fragment should be unencoded values - they will be encoded as required.

      Examples: mailto:user@codenameone.com sms:+5555551212 tel:+5555551212 isbn:9781935182962

      Parameters

      • scheme

      • ssp: @param ssp the unencoded scheme specific part (everything except the scheme and fragment)

      • fragment: the unencoded fragment, or null

      Throws
      • URISyntaxException: if any of the segments are invalid.
      Throws:
      URISyntaxException

    • URI

      public URI(java.lang.String uriString) throws URISyntaxException

      Constructor that parses its values from a URI string. This method expects all segments to be property encoded by the caller. The URIHelper class can be used to encode segments.

      Parameters
      • uriString: a full encoded URI in string form to be parsed.
      Throws
      • URISyntaxException: if any of the parsed segments are invalid.
      Throws:
      URISyntaxException

  • Method Details

    • setScheme

      protected void setScheme(java.lang.String scheme) throws URISyntaxException

      Utility method - set the scheme, ensuring valid format, and determining the query separator to use.

      See also
      Throws:
      URISyntaxException

    • setSchemeSpecificPart

      protected void setSchemeSpecificPart(java.lang.String ssp, boolean encode) throws URISyntaxException
      Utility method - set the scheme specific part, ensuring valid format. If encode=true, then some elements will be run through the encoder (path, userinfo, query, fragment), otherwise the elements will be validated for proper encoding.
      Throws:
      URISyntaxException

    • setAuthority

      protected void setAuthority(java.lang.String newAuthority, boolean encode) throws URISyntaxException
      Utility method - set the part, ensuring valid format. If encode=true, then some elements will be run through the encoder (path, userinfo, query, fragment), otherwise the elements will be validated for proper encoding.
      Throws:
      URISyntaxException

    • setQuery

      protected void setQuery(java.lang.String query, boolean encode) throws URISyntaxException

      Utility method to set the query. If parameter encode=true, then the result will be encoded, otherwise the result will be validated to ensure encoding is valid. Typically the multi-parameter constructors will call this method with encode=true, and the single parameter construct will pass encode=false.

      Parameters

      • query

      • encode

      Throws
      • URISyntaxException
      Throws:
      URISyntaxException

    • setPath

      protected void setPath(java.lang.String path, boolean encode) throws URISyntaxException

      Utility method to set the path. If parameter encode=true, then the result will be encoded, otherwise the result will be validated to ensure encoding is valid. Typically the multi-parameter constructors will call this method with encode=true, and the single parameter construct will pass encode=false.

      Parameters

      • path

      • encode

      Throws
      • URISyntaxException
      Throws:
      URISyntaxException

    • setAuthority

      protected void setAuthority(java.lang.String host, int port, java.lang.String userInfo, boolean encode) throws URISyntaxException

      Utility method to construct the authority segment from given host, port, and userinfo segments. If parameter encode=true, then the userinfo segment will be encoded, otherwise the it will be validated to ensure encoding is valid. Typically the multi-parameter constructors will call this method with encode=true, and the single parameter construct will pass encode=false.

      Parameters

      • host

      • port

      • userInfo

      • encode

      Throws
      • URISyntaxException
      Throws:
      URISyntaxException

    • setFragment

      protected void setFragment(java.lang.String fragment, boolean encode)

      Utility method to set the fragment. If parameter encode=true, then the result will be encoded, otherwise the result will be validated to ensure encoding is valid. Typically the multi-parameter constructors will call this method with encode=true, and the single parameter construct will pass encode=false.

      Parameters

      • fragment

      • encode

    • rebuildSchemeSpecificPart

      protected java.lang.String rebuildSchemeSpecificPart()
      Utility method to construct the scheme specific part from the uri segments (less scheme and fragment)

    • create

      public static URI create(java.lang.String uriString)

      A convenience factory method, intended to be used when the URI string is known to be valid (ie. a static application URI), so it is not needed for the caller to handle invalid syntax. NOTE: this is not away to avoid handling errors altogether - passing an invalid URI string will result in an IllegalArgumentException being thrown. The benefit here is that the compiler will not complain if you don't explicitly handle the error at compile time.

      When handling a user-editable URI, use the URI constructors instead.

      Parameters
      • uriString: URI address as a string
      Returns

      parsed URI object

    • parseURI

      protected void parseURI(java.lang.String uriString) throws URISyntaxException

      Rather than attempting to process the uri string in a linear fashion, this implementation works its way from outside-in

      Parameters
      • uriString
      Throws
      • URISyntaxException
      Throws:
      URISyntaxException

    • parseSchemeSpecificPart

      protected void parseSchemeSpecificPart(java.lang.String ssp, boolean encode) throws URISyntaxException

      Utility method used to parse a given scheme specific part. If parameter encode=true, then the result will be encoded, otherwise the result will be validated to ensure encoding is valid. Typically the multi-parameter constructors will call this method with encode=true, and the single parameter construct will pass encode=false.

      Parameters

      • ssp: @param ssp scheme specific part (the URI without the scheme or fragment included).

      • encode: @param encode true if ssp needs to be encoded, false if ssp needs to be verified.

      Throws
      • URISyntaxException: if the ssp is invalid.
      Throws:
      URISyntaxException

    • getScheme

      public java.lang.String getScheme()

      Get the scheme part of the URI.

      Returns

      the scheme part of the URI.

    • getHost

      public java.lang.String getHost()

      Get the host name part of the URI.

      Returns

      the host name part of the URI.

    • getPort

      public int getPort()

      Get the port number for this URI.

      Returns
      Returns:
      the port number for this URI, or -1 if a port number was not specified.

    • getPath

      public java.lang.String getPath()

      Get the decoded path part of the uri.

      Returns
      Returns:
      the query part of the URI, or an empty string if no path is included in the URI.

    • getRawPath

      public java.lang.String getRawPath()

      Get the encoded path part of the uri.

      Returns
      Returns:
      the query part of the URI, or an empty string if no path is included in the URI.

    • getQuery

      public java.lang.String getQuery()

      Get the decoded query part of the uri. The query marker (?) itself is not included in the result.

      Returns

      the query part of the URI.

    • getRawQuery

      public java.lang.String getRawQuery()

      Get the encoded query part of the uri. The query marker (?) itself is not included in the result.

      Returns

      the query part of the URI.

    • getFragment

      public java.lang.String getFragment()

      Get the decoded fragment (otherwise known as the "reference" or "anchor") part of the uri. The anchor marker (#) itself is not included in the result.

      Returns

      the anchor part of the URI.

    • getRawFragment

      public java.lang.String getRawFragment()

      Get the encoded fragment (otherwise known as the "reference" or "anchor") part of the uri. The anchor marker (#) itself is not included in the result.

      Returns

      the anchor part of the URI.

    • getSchemeSpecificPart

      public java.lang.String getSchemeSpecificPart()
      Returns

      the schemeSpecificPart

    • getRawSchemeSpecificPart

      public java.lang.String getRawSchemeSpecificPart()
      Returns

      the schemeSpecificPart

    • getAuthority

      public java.lang.String getAuthority()
      Returns

      the authority

    • getRawAuthority

      public java.lang.String getRawAuthority()
      Returns

      the authority

    • getUserInfo

      public java.lang.String getUserInfo()
      Returns

      the userInfo

    • getRawUserInfo

      public java.lang.String getRawUserInfo()
      Returns

      the userInfo

    • isOpaque

      public boolean isOpaque()
      Returns

      true if this URI has a scheme and starts with a slash

    • isAbsolute

      public boolean isAbsolute()
      Returns

      true if the URI is not a relative URI.

    • toString

      public java.lang.String toString()
      Returns

      the uri as a string

      Overrides:
      toString in class java.lang.Object

    • toASCIIString

      public java.lang.String toASCIIString()
      Returns

      the uri as a string with parts encoded.

    • relativize

      public URI relativize(URI uri)

      Create a relative URI object against this URI, given the uri parameter.

      Parameters
      • uri
      See also

    • resolve

      public URI resolve(URI uri)

      Resolve a relative URI by merging it with this URI.

      Parameters
      • uri: a URI to resolve against this URI.
      Returns

      a new URI created by merging given URI with this URI.

      See also

    • normalize

      public URI normalize()

      Normalize a URI by removing any "./" segments, and "path/../" segments.

      Returns

      a new URI instance with redundant segments removed.

      See also

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class java.lang.Object

    • equals

      public boolean equals(java.lang.Object that)
      Overrides:
      equals in class java.lang.Object