URI (Codename One API)

java.lang.Object
- java.net.URI

public class URI
extends 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

See Also:: http://docs.oracle.com/javase/6/docs/api/java/net/URI.html, http://en.wikipedia.org/wiki/Uniform_resource_identifier, http://en.wikipedia.org/wiki/Uniform_resource_name, http://www.ietf.org/rfc/rfc2396.txt, http://www.ietf.org/rfc/rfc2732.txt, http://tools.ietf.org/html/rfc2141

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static URI`	`create(String uriString)` A convenience factory method, intended to be used when the URI string is known to be valid (ie.
`boolean`	`equals(Object that)` Indicates whether some other object is "equal to" this one.
`String`	`getAuthority()`
`String`	`getFragment()` Get the decoded fragment (otherwise known as the "reference" or "anchor") part of the uri.
`String`	`getHost()` Get the host name part of the URI.
`String`	`getPath()` Get the decoded path part of the uri.
`int`	`getPort()` Get the port number for this URI.
`String`	`getQuery()` Get the decoded query part of the uri.
`String`	`getRawAuthority()`
`String`	`getRawFragment()` Get the encoded fragment (otherwise known as the "reference" or "anchor") part of the uri.
`String`	`getRawPath()` Get the encoded path part of the uri.
`String`	`getRawQuery()` Get the encoded query part of the uri.
`String`	`getRawSchemeSpecificPart()`
`String`	`getRawUserInfo()`
`String`	`getScheme()` Get the scheme part of the URI.
`String`	`getSchemeSpecificPart()`
`String`	`getUserInfo()`
`int`	`hashCode()` Returns a hash code value for the object.
`boolean`	`isAbsolute()`
`boolean`	`isOpaque()`
`URI`	`normalize()` Normalize a URI by removing any "./" segments, and "path/../" segments.
`protected void`	`parseSchemeSpecificPart(String ssp, boolean encode)` Utility method used to parse a given scheme specific part.
`protected void`	`parseURI(String uriString)` Rather than attempting to process the uri string in a linear fashion, this implementation works its way from outside-in
`protected 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(String newAuthority, boolean encode)` Utility method - set the part, ensuring valid format.
`protected void`	`setAuthority(String host, int port, String userInfo, boolean encode)` Utility method to construct the authority segment from given host, port, and userinfo segments.
`protected void`	`setFragment(String fragment, boolean encode)` Utility method to set the fragment.
`protected void`	`setPath(String path, boolean encode)` Utility method to set the path.
`protected void`	`setQuery(String query, boolean encode)` Utility method to set the query.
`protected void`	`setScheme(String scheme)` Utility method - set the scheme, ensuring valid format, and determining the query separator to use.
`protected void`	`setSchemeSpecificPart(String ssp, boolean encode)` Utility method - set the scheme specific part, ensuring valid format.
`String`	`toASCIIString()`
`String`	`toString()` Returns a string representation of the object.

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

- Constructor Detail
  - URI
```
public URI(String scheme,
           String userInfo,
           String host,
           int port,
           String path,
           String query,
           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 - the scheme of the URI (for URLs, this would be the protocol), or null for relative URIs.
    
    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 - the unencoded fragment (often referred to as the 'reference' or 'anchor'), or null.
    
    Throws:
    
    URISyntaxException - if any of the fragments are invalid.
  - URI
```
public URI(String scheme,
           String authority,
           String path,
           String query,
           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 - the scheme of the URI (for URLs, this would be the protocol), or null for relative URIs.
    
    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 - the unencoded fragment (often referred to as the 'reference' or 'anchor'), or null.
    
    Throws:
    
    URISyntaxException - if any of the fragments are invalid.
  - URI
```
public URI(String scheme,
           String ssp,
           String fragment)
    throws URISyntaxException
```
    Constructor for building URNs. The ssp and fragment should be unencoded values - they will be encoded as required. Examples: mailto:[email protected] sms:+5555551212 tel:+5555551212 isbn:9781935182962
    
    Parameters:
    
    scheme -
    
    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.
  - URI
```
public URI(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.
- Method Detail
  - setScheme
```
protected void setScheme(String scheme)
                  throws URISyntaxException
```
    Utility method - set the scheme, ensuring valid format, and determining the query separator to use.
    
    Throws:
    
    URISyntaxException
    
    See Also:
    
    http://en.wikipedia.org/wiki/Uniform_resource_name
  - setSchemeSpecificPart
```
protected void setSchemeSpecificPart(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(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(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
  - setPath
```
protected void setPath(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
  - setAuthority
```
protected void setAuthority(String host,
                            int port,
                            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
  - setFragment
```
protected void setFragment(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 String rebuildSchemeSpecificPart()
```
    Utility method to construct the scheme specific part from the uri segments (less scheme and fragment)
    
    Returns:
  - create
```
public static URI create(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(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
  - parseSchemeSpecificPart
```
protected void parseSchemeSpecificPart(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 - scheme specific part (the URI without the scheme or fragment included).
    
    encode - true if ssp needs to be encoded, false if ssp needs to be verified.
    
    Throws:
    
    URISyntaxException - if the ssp is invalid.
  - getScheme
```
public String getScheme()
```
    Get the scheme part of the URI.
    
    Returns:
    
    the scheme part of the URI.
  - getHost
```
public 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:
    
    the port number for this URI, or -1 if a port number was not specified.
  - getPath
```
public String getPath()
```
    Get the decoded path part of the uri.
    
    Returns:
    
    the query part of the URI, or an empty string if no path is included in the URI.
  - getRawPath
```
public String getRawPath()
```
    Get the encoded path part of the uri.
    
    Returns:
    
    the query part of the URI, or an empty string if no path is included in the URI.
  - getQuery
```
public 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 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 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 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 String getSchemeSpecificPart()
```
    Returns:
    
    the schemeSpecificPart
  - getRawSchemeSpecificPart
```
public String getRawSchemeSpecificPart()
```
    Returns:
    
    the schemeSpecificPart
  - getAuthority
```
public String getAuthority()
```
    Returns:
    
    the authority
  - getRawAuthority
```
public String getRawAuthority()
```
    Returns:
    
    the authority
  - getUserInfo
```
public String getUserInfo()
```
    Returns:
    
    the userInfo
  - getRawUserInfo
```
public 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 String toString()
```
    Description copied from class: Object
    
    Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + '@' + Integer.toHexString(hashCode())
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    the uri as a string
  - toASCIIString
```
public 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 -
    
    Returns:
    
    See Also:
    
    ://docs.oracle.com/javase/6/docs/api/java/net/URI.html#relativize %28java.net.URI%29
  - 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:
    
    ://docs.oracle.com/javase/6/docs/api/java/net/URI.html#resolve%28 java.net.URI%29
  - 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:
    
    ://docs.oracle.com/javase/6/docs/api/java/net/URI.html#normalize% 28%29
  - hashCode
```
public int hashCode()
```
    Description copied from class: Object
    
    Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable. The general contract of hashCode is: Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables. As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)
    
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object that)
```
    Description copied from class: Object
    
    Indicates whether some other object is "equal to" this one. The equals method implements an equivalence relation: It is reflexive: for any reference value x, x.equals(x) should return true. It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true. It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified. For any non-null reference value x, x.equals(null) should return false. The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).
    
    Overrides:
    
    equals in class Object

Class URI

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

URI

URI

URI

URI

Method Detail

setScheme

setSchemeSpecificPart

setAuthority

setQuery

setPath

setAuthority

setFragment

rebuildSchemeSpecificPart

create

parseURI

parseSchemeSpecificPart

getScheme

getHost

getPort

getPath

getRawPath

getQuery

getRawQuery

getFragment

getRawFragment

getSchemeSpecificPart

getRawSchemeSpecificPart

getAuthority

getRawAuthority

getUserInfo

getRawUserInfo

isOpaque

isAbsolute

toString

toASCIIString

relativize

resolve

normalize

hashCode

equals