Package org.czeal.urireference

Class URIReference

java.lang.Object

org.czeal.urireference.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
 

Author:

Hideki Ikeda

See Also:

RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax, Serialized Form

Method Summary

Modifier and Type	Method	Description
int	compareTo(URIReference other)	Compares this URIReference object with another URIReference object for order.
boolean	equals(Object obj)	Compares this URIReference object with the specified object for equality.
Authority	getAuthority()	Get the authority of this URI reference.
Charset	getCharset()	Returns the charset used for percent-encoding some characters (e.g. reserved characters) contained in this URI reference.
String	getFragment()	Get the fragment of this URI reference.
Host	getHost()	Get the host of this URI reference.
String	getPath()	Get the path of this URI reference.
int	getPort()	Get the port of this URI reference.
String	getQuery()	Get the query of this URI reference.
String	getScheme()	Get the scheme of this URI reference.
String	getUserinfo()	Get the userinfo of this URI reference.
boolean	hasAuthority()	Checks whether or not this URI reference has an authority.
int	hashCode()	Returns a hash code value for this URIReference object.
boolean	isRelativeReference()	Returns true if the URI reference is a relative reference.
URIReference	normalize()	Normalizes this URI reference.
static URIReference	parse(String uriRef)	Parses a string based on in RFC 3986 and creates a URIReference instance if parsing succeeds.
static URIReference	parse(String uriRef, Charset charset)	Parses a string based on in RFC 3986 and creates a URIReference instance if parsing succeeds.
URIReference	resolve(String uriRef)	Resolves the given URI reference against this URI reference.
URIReference	resolve(URIReference uriRef)	Resolve the given URI reference against this URI reference.
String	toString()	Returns a string representation of this URIReference object.

Methods inherited from class java.lang.Object

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

Method Detail

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:

RFC 3986 Uniform Resource Identifier (URI): Generic Syntax

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:

RFC 3986 Uniform Resource Identifier (URI): Generic Syntax

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:

RFC 3986, 4.2. Relative Reference

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.