Package org.czeal.rfc3986

Class URIReference

Object
URIReference
All Implemented Interfaces:
Serializable, Comparable<URIReference>
public class URIReference extends Object implements Serializable, Comparable<URIReference>
A class representing a URI reference, as defined in RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax. This class provides various methods for working with URI references, including parsing, resolving, and normalizing them.

The parse(String) method parses a given string as a URI reference according to RFC 3986 and creates a URIReference instance, representing either a URI or a relative reference. The isRelativeReference() can be used to check if the parsed URI instance represents a relative reference (returns true) or a URI (returns false). Access URI components such as scheme using corresponding getter methods like getScheme().

The resolve(String) method and resolve(URIReference) method return a new URIReference instance representing a URI reference obtained by resolving the current URI reference against a given base URI, following the rules in RFC 3986, 5 Reference Resolution.

The normalize() method returns a new URIReference instance representing a URI reference obtained by normalizing the current URI reference, in accordance with RFC 3986, 6 Normalization and Comparison. Note that a URI reference must be resolved before it can be normalized.

This class is immutable.

Examples:


 //---------------------------------------------------------------------------
 // Parsing.
 //---------------------------------------------------------------------------
 URIReference uriRef = URIReference
                           .parse("http://example.com/a"); // Parse a URI.

 System.out.println(uriRef.isRelativeReference());     // false
 System.out.println(uriRef.getScheme());               // "http"
 System.out.println(uriRef.hasAuthority());            // true
 System.out.println(uriRef.getAuthority().toString()); // "example.com"
 System.out.println(uriRef.getUserinfo());             // null
 System.out.println(uriRef.getHost().getType());       // "REGNAME"
 System.out.println(uriRef.getHost().getValue());      // "example.com"
 System.out.println(uriRef.getPort());                 // -1
 System.out.println(uriRef.getPath());                 // "/a"
 System.out.println(uriRef.getQuery());                // null
 System.out.println(uriRef.getFragment());             // null


 //---------------------------------------------------------------------------
 // Resolution.
 //---------------------------------------------------------------------------
 URIReference uriRef = URIReference
                           .parse("http://example.com") // Parse a base URI.
                           .resolve("/a/b");            // Resolve a relative reference against the base URI.

 System.out.println(uriRef.isRelativeReference());     // false
 System.out.println(uriRef.getScheme());               // "http"
 System.out.println(uriRef.hasAuthority());            // true
 System.out.println(uriRef.getAuthority().toString()); // "example.com"
 System.out.println(uriRef.getUserinfo());             // null
 System.out.println(uriRef.getHost().getType());       // "REGNAME"
 System.out.println(uriRef.getHost().getValue());      // "example.com"
 System.out.println(uriRef.getPort());                 // -1
 System.out.println(uriRef.getPath());                 // "/a/b"
 System.out.println(uriRef.getQuery());                // null
 System.out.println(uriRef.getFragment());             // null


 //---------------------------------------------------------------------------
 // Normalization.
 //---------------------------------------------------------------------------
 URIReference uriRef = URIReference
                           .parse("hTTp://example.com:80/a/b/c/../d/") // Parse a URI.
                           .normalize();                               // Normalize it.

 System.out.println(uriRef.isRelativeReference());     // false
 System.out.println(uriRef.getScheme());               // "http"
 System.out.println(uriRef.hasAuthority());            // true
 System.out.println(uriRef.getAuthority().toString()); // "example.com:80"
 System.out.println(uriRef.getUserinfo());             // null
 System.out.println(uriRef.getHost().getType());       // "REGNAME"
 System.out.println(uriRef.getHost().getValue());      // "example.com"
 System.out.println(uriRef.getPort());                 // -1
 System.out.println(uriRef.getPath());                 // "/a/b/d/"
 System.out.println(uriRef.getQuery());                // null
 System.out.println(uriRef.getFragment());             // null
See Also:

  • Method Details

    • parse

      public static URIReference parse(String uriRef)
      Parses a string based on in RFC 3986 and creates a URIReference instance if parsing succeeds. If parsing fails due to invalid input string, an IllegalArgumentException will be thrown.

      Note that this method works as if invoking it were equivalent to evaluating the expression parse(String uriRef, StandardCharsets.UTF_8).

      Examples:

      
 // Example 1. Parse a string as a URI.
 URIReference.parse("http://example.com");

 // Example 2. Parse a string as a relative reference.
 URIReference.parse("//example.com/path1");

 // Example 3. Parse a string with an IPV4 host as a URI.
 URIReference.parse("http://101.102.103.104");

 // Example 4. Parse a string with an IPV6 host as a URI.
 URIReference.parse("http://[2001:0db8:0001:0000:0000:0ab9:C0A8:0102]");

 // Example 5. Parse a string with percent-encoded values as a URI.
 URIReference.parse("http://%6A%6F%68%6E@example.com");
      Parameters:
      uriRef - A input string to parse as a URI reference.
      Returns:
      The URIReference instance obtained by parsing the input string.
      Throws:
      NullPointerException - If uriRef or charset is null.
      IllegalArgumentException - If uriRef is invalid as a URI reference.
      See Also:

    • parse

      public static URIReference parse(String uriRef, Charset charset)

      Parses a string based on in RFC 3986 and creates a URIReference instance if parsing succeeds. If parsing fails due to invalid input string, an IllegalArgumentException will be thrown.

      Examples:

      
 // Example 1. Create a URI using UTF-8 encoding.
 URIReference.parse("http://example.com", StandardCharsets.UTF_8);

 // Example 2. Create a relative reference using UTF-8 encoding.
 URIReference.parse("//example.com/path1", StandardCharsets.UTF_8);

 // Example 3. Create a URI with IPV4 host using UTF-8 encoding.
 URIReference.parse("http://101.102.103.104", StandardCharsets.UTF_8);

 // Example 4. Create a URI with IPV6 host using UTF-8 encoding.
 URIReference.parse("http://[2001:0db8:0001:0000:0000:0ab9:C0A8:0102]", StandardCharsets.UTF_8);

 // Example 5. Create a URI with percent-encoded values using UTF-8 encoding.
 URIReference.parse("http://%6A%6F%68%6E@example.com", StandardCharsets.UTF_8);
      Parameters:
      uriRef - The input string to be parsed as a URIReference instance.
      charset - The charset used for percent-encoding some characters (e.g. reserved characters) contained in the input string.
      Returns:
      The URIReference instance obtained by parsing the input string.
      Throws:
      NullPointerException - If uriRef or charset is null.
      IllegalArgumentException - If uriRef is invalid as a URI reference.
      See Also:

    • getCharset

      public Charset getCharset()
      Returns the charset used for percent-encoding some characters (e.g. reserved characters) contained in this URI reference.
      Returns:
      The charset used for percent-encoding some characters (e.g. reserved characters) contained in this URI reference.

    • isRelativeReference

      public boolean isRelativeReference()
      Returns true if the URI reference is a relative reference. See RFC 3986, 4.2. Relative Reference for more details.
      Returns:
      true if the URI reference is a relative reference. otherwise, false.
      See Also:

    • getScheme

      public String getScheme()
      Get the scheme of this URI reference. If this URI reference is a relative reference, null is returned.
      Returns:
      The scheme of this URI reference.

    • getAuthority

      public Authority getAuthority()
      Get the authority of this URI reference.
      Returns:
      The authority of this URI reference.

    • getUserinfo

      public String getUserinfo()
      Get the userinfo of this URI reference.
      Returns:
      The userinfo of this URI reference.

    • getHost

      public Host getHost()
      Get the host of this URI reference.
      Returns:
      The host of this URI reference.

    • getPort

      public int getPort()
      Get the port of this URI reference.
      Returns:
      The port of this URI reference.

    • getPath

      public String getPath()
      Get the path of this URI reference.
      Returns:
      The path of this URI reference.

    • getQuery

      public String getQuery()
      Get the query of this URI reference.
      Returns:
      The query of this URI reference.

    • getFragment

      public String getFragment()
      Get the fragment of this URI reference.
      Returns:
      The fragment of this URI reference.

    • hasAuthority

      public boolean hasAuthority()
      Checks whether or not this URI reference has an authority.
      Returns:
      true if this URI reference has an authority; otherwise, false.

    • toString

      public String toString()
      Returns a string representation of this URIReference object.

      The string is constructed by concatenating the scheme, authority, path, query, and fragment components, separated by appropriate delimiters.

      Overrides:
      toString in class Object
      Returns:
      A string representation of this URIReference object.

    • equals

      public boolean equals(Object obj)
      Compares this URIReference object with the specified object for equality.

      The comparison is based on the values of scheme, authority, path, query, and fragment components.

      Overrides:
      equals in class Object
      Parameters:
      obj - The object to be compared for equality with this URIReference.
      Returns:
      true if the specified object is equal to this URIReference.

    • hashCode

      public int hashCode()
      Returns a hash code value for this URIReference object.

      The hash code is generated based on the values of scheme, authority, path, query, and fragment components.

      Overrides:
      hashCode in class Object
      Returns:
      A hash code value for this object.

    • compareTo

      public int compareTo(URIReference other)
      Compares this URIReference object with another URIReference object for order. The comparison is based on the string representation of the URIReference objects.
      Specified by:
      compareTo in interface Comparable<URIReference>
      Parameters:
      other - The URIReference object to be compared.
      Returns:
      0 if this URIReference object is equal to the specified URIReference object. A negative value if this URIReference object is less than the specified object. A positive value if this URIReference object is greater than the specified object.
      Throws:
      NullPointerException - If the specified URIReference object is null.

    • resolve

      public URIReference resolve(String uriRef)
      Resolves the given URI reference against this URI reference. This method works as if invoking it were equivalent to evaluating the expression resolve(parse(uriRef, getCharset())).

      Examples:

      
 // A base URI.
 URIReference baseUri = URIReference.parse("http://example.com");

 // A relative reference.
 String relRef = "/path1/path2";

 // Resolve the relative reference against the base URI.
 URIReference resolved = baseUri.resolve(relRef);

 // This will output "http://example.com/path1/path2".
 System.out.println(resolved.toString());
      Parameters:
      uriRef - A string representing a URI reference to be resolved against this URI reference.
      Returns:
      The URI reference obtained by resolving the input string against this URI reference.
      Throws:
      NullPointerException - If uriRef is null.
      IllegalStateException - If this URI reference is not an absolute URI.

    • resolve

      public URIReference resolve(URIReference uriRef)
      Resolve the given URI reference against this URI reference.

      Examples:

      
 // A base URI.
 URIReference baseUri = URIReference.parse("http://example.com");

 // A relative reference.
 URIReference relRef = URIReference.parse("/path1/path2");

 // Resolve the relative reference against the base URI.
 URIReference resolved = baseUri.resolve(relRef);

 // This will output "http://example.com/path1/path2".
 System.out.println(resolved.toString());
      Parameters:
      uriRef - A URI reference to be resolved against this URI reference.
      Returns:
      The URI reference obtained by resolving the input string against this URI reference.
      Throws:
      NullPointerException - If str is null.
      IllegalStateException - If this URI reference is not an absolute URI.

    • normalize

      public URIReference normalize()
      Normalizes this URI reference.

      This method does not modify the state of the original URIReference instance on which this method is called. Instead, it creates a new URIReference instance and initializes it with the information about the normalized URI reference.

      Note that this method throws an IllegalStateException if this URI reference has not been resolved yet.

      Returns:
      A new URIReference instance representing the normalized URI reference.
      Throws:
      IllegalStateException - If this URI reference has not been resolved yet.