org.apache.river.api.net

Class Uri

java.lang.Object

org.apache.river.api.net.Uri

All Implemented Interfaces:

Comparable<Uri>

public final class Uri
extends Object
implements Comparable<Uri>

This class represents an immutable instance of a URI as defined by RFC 3986. This class replaces java.net.URI functionality. Unlike java.net.URI this class is not Serializable and hashCode and equality is governed by strict RFC3986 normalisation. In addition "other" characters allowed in java.net.URI as specified by javadoc, not specifically allowed by RFC3986 are illegal and must be escaped. This strict adherence is essential to eliminate false negative or positive matches. In addition to RFC3896 normalisation, on OS platforms with a \ file separator the path is converted to UPPER CASE for comparison for file: schema, during equals and hashCode calls. IPv6 and IPvFuture host addresses must be enclosed in square brackets as per RFC3986.

Since:

3.0.0

Constructor Summary

Constructors

Constructor and Description
Uri(String uri) Creates a new URI instance according to the given string uri.
Uri(String scheme, String ssp, String frag) Creates a new URI instance using the given arguments.
Uri(String scheme, String userinfo, String host, int port, String path, String query, String fragment) Creates a new URI instance using the given arguments.
Uri(String scheme, String host, String path, String fragment) Creates a new URI instance using the given arguments.
Uri(String scheme, String authority, String path, String query, String fragment) Creates a new URI instance using the given arguments.

Method Summary

Modifier and Type	Method and Description
int	compareTo(Uri uri) Compares this URI with the given argument uri.
static Uri	create(String rfc3986compliantURI) Parses the given argument rfc3986compliantURI and creates an appropriate URI instance.
boolean	equals(Object o) Compares this URI instance with the given argument o and determines if both are equal.
static Uri	escapeAndCreate(String unescapedString) The parameter string doesn't contain any existing escape sequences, any escape character % found is encoded as %25.
static Uri	filePathToUri(String path)
static Uri	fileToUri(File file)
static String	fixWindowsURI(String uri) Fixes windows file URI string by converting back slashes to forward slashes and inserting a forward slash before the drive letter if it is missing.
String	getAuthority() Gets the decoded authority part of this URI.
String	getFragment() Gets the decoded fragment part of this URI.
String	getHost() Gets the host part of this URI.
String	getPath() Gets the decoded path part of this URI.
int	getPort() Gets the port number of this URI.
String	getQuery() Gets the decoded query part of this URI.
String	getRawAuthority() Gets the authority part of this URI in raw form.
String	getRawFragment() Gets the fragment part of this URI in raw form.
String	getRawPath() Gets the path part of this URI in raw form.
String	getRawQuery() Gets the query part of this URI in raw form.
String	getRawSchemeSpecificPart() Gets the scheme-specific part of this URI in raw form.
String	getRawUserInfo() Gets the user-info part of this URI in raw form.
String	getScheme() Gets the scheme part of this URI.
String	getSchemeSpecificPart() Gets the decoded scheme-specific part of this URI.
String	getUserInfo() Gets the decoded user-info part of this URI.
int	hashCode() Gets the hashcode value of this URI instance.
boolean	implies(Uri implied) Indicates whether the specified Uri is implied by this Uri.
boolean	isAbsolute() Indicates whether this URI is absolute, which means that a scheme part is defined in this URI.
boolean	isOpaque() Indicates whether this URI is opaque or not.
Uri	normalize() Normalizes the path part of this URI.
static Uri	parseAndCreate(String nonCompliantEscapedString) The parameter string may already contain escaped sequences, any illegal characters are escaped and any that shouldn't be escaped are un-escaped.
Uri	parseServerAuthority() Tries to parse the authority component of this URI to divide it into the host, port, and user-info.
Uri	relativize(Uri relative) Makes the given URI relative to a relative URI against the URI represented by this instance.
Uri	resolve(String relative) Creates a new URI instance by parsing the given string relative and resolves the created URI against the URI represented by this instance.
Uri	resolve(Uri relative) Resolves the given URI relative against the URI represented by this instance.
String	toASCIIString() Returns the textual string representation of this URI instance using the US-ASCII encoding.
String	toString() Returns the textual string representation of this URI instance.
URL	toURL() Converts this URI instance to a URL.
static File	uriToFile(Uri uri)
static URI	uriToURI(Uri uri)
static Uri	urlToUri(URL url)

Methods inherited from class java.lang.Object

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

Constructor Detail

Uri

public Uri(String uri)
    throws URISyntaxException

Creates a new URI instance according to the given string uri. The URI must strictly conform to RFC3986, it doesn't support extended characters sets like java.net.URI, instead all non ASCII characters must be escaped. Any encoded unreserved characters are decoded.

Parameters:

uri - the textual URI representation to be parsed into a URI object.

Throws:

URISyntaxException - if the given string uri doesn't fit to the specification RF3986 or could not be parsed correctly.

Uri

public Uri(String scheme,
           String ssp,
           String frag)
    throws URISyntaxException

Creates a new URI instance using the given arguments. This constructor first creates a temporary URI string from the given components. This string will be parsed later on to create the URI instance.

[scheme:]scheme-specific-part[#fragment]

Parameters:

scheme - the scheme part of the URI.

ssp - the scheme-specific-part of the URI.

frag - the fragment part of the URI.

Throws:

URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.

Uri

public Uri(String scheme,
           String userinfo,
           String host,
           int port,
           String path,
           String query,
           String fragment)
    throws URISyntaxException

Creates a new URI instance using the given arguments. This constructor first creates a temporary URI string from the given components. This string will be parsed later on to create the URI instance.

[scheme:][user-info@]host[:port][path][?query][#fragment]

Parameters:

scheme - the scheme part of the URI.

userinfo - the user information of the URI for authentication and authorization.

host - the host name of the URI.

port - the port number of the URI.

path - the path to the resource on the host.

query - the query part of the URI to specify parameters for the resource.

fragment - the fragment part of the URI.

Throws:

URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.

Uri

public Uri(String scheme,
           String host,
           String path,
           String fragment)
    throws URISyntaxException

Creates a new URI instance using the given arguments. This constructor first creates a temporary URI string from the given components. This string will be parsed later on to create the URI instance.

[scheme:]host[path][#fragment]

Parameters:

scheme - the scheme part of the URI.

host - the host name of the URI.

path - the path to the resource on the host.

fragment - the fragment part of the URI.

Throws:

URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.

Uri

public Uri(String scheme,
           String authority,
           String path,
           String query,
           String fragment)
    throws URISyntaxException

Creates a new URI instance using the given arguments. This constructor first creates a temporary URI string from the given components. This string will be parsed later on to create the URI instance.

[scheme:][//authority][path][?query][#fragment]

Parameters:

scheme - the scheme part of the URI.

authority - the authority part of the URI.

path - the path to the resource on the host.

query - the query part of the URI to specify parameters for the resource.

fragment - the fragment part of the URI.

Throws:

URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.

Method Detail

fixWindowsURI

public static String fixWindowsURI(String uri)

Fixes windows file URI string by converting back slashes to forward slashes and inserting a forward slash before the drive letter if it is missing. No normalisation or modification of case is performed.

Parameters:

uri - String representation of URI

Returns:

fixed URI String

uriToURI

public static URI uriToURI(Uri uri)

urlToUri

public static Uri urlToUri(URL url)
                    throws URISyntaxException

Throws:

URISyntaxException

uriToFile

public static File uriToFile(Uri uri)

fileToUri

public static Uri fileToUri(File file)
                     throws URISyntaxException

Throws:

URISyntaxException

filePathToUri

public static Uri filePathToUri(String path)
                         throws URISyntaxException

Throws:

URISyntaxException

compareTo

public int compareTo(Uri uri)

Compares this URI with the given argument uri. This method will return a negative value if this URI instance is less than the given argument and a positive value if this URI instance is greater than the given argument. The return value 0 indicates that the two instances represent the same URI. To define the order the single parts of the URI are compared with each other. String components will be orderer in the natural case-sensitive way. A hierarchical URI is less than an opaque URI and if one part is null the URI with the undefined part is less than the other one.

Specified by:

compareTo in interface Comparable<Uri>

Parameters:

uri - the URI this instance has to compare with.

Returns:

the value representing the order of the two instances.

create

public static Uri create(String rfc3986compliantURI)

Parses the given argument rfc3986compliantURI and creates an appropriate URI instance. The parameter string is checked for compliance, an IllegalArgumentException is thrown if the string is non compliant.

Parameters:

rfc3986compliantURI - the string which has to be parsed to create the URI instance.

Returns:

the created instance representing the given URI.

escapeAndCreate

public static Uri escapeAndCreate(String unescapedString)
                           throws URISyntaxException

The parameter string doesn't contain any existing escape sequences, any escape character % found is encoded as %25. Illegal characters are escaped if possible. The Uri is normalised according to RFC3986.

Parameters:

unescapedString - URI in un-escaped string form

Returns:

an RFC3986 compliant Uri.

Throws:

URISyntaxException - if string cannot be escaped.

parseAndCreate

public static Uri parseAndCreate(String nonCompliantEscapedString)
                          throws URISyntaxException

The parameter string may already contain escaped sequences, any illegal characters are escaped and any that shouldn't be escaped are un-escaped. The escape character % is not re-encoded.

Parameters:

nonCompliantEscapedString - URI in string from.

Returns:

an RFC3986 compliant Uri.

Throws:

URISyntaxException - if string cannot be escaped.

equals

public boolean equals(Object o)

Compares this URI instance with the given argument o and determines if both are equal. Two URI instances are equal if all single parts are identical in their meaning.

Overrides:

equals in class Object

Parameters:

o - the URI this instance has to be compared with.

Returns:

true if both URI instances point to the same resource, false otherwise.

implies

public boolean implies(Uri implied)

Indicates whether the specified Uri is implied by this Uri. Returns true if all of the following conditions are true, otherwise false:

• this scheme is not null
• this scheme is equal to implied's scheme.
• if this host is not null, the following conditions are checked
  • cs's host is not null
  • the wildcard or partial wildcard of this Uri's host matches implied's host.
• if this Uri's port != -1 the port of implied's location is equal to this Uri's port
• this Uri's path matches implied's path whereas special wildcard matching applies as described below.

Matching rules for path:

• if this Uri's path ends with "/-", then implied's path must start with Uri's path (exclusive the trailing '-')
• if this Uri's path ends with "/*", then implied's path must start with Uri's path (exclusive the trailing '*') and must not have any further '/'
• if this Uri's path ends with "/", then implied's path must start with Uri's path
• if this Uri's path does not end with "/", then implied's path must start with Uri's path with the '/' appended to it.

Examples for Uri that imply the Uri "http://harmony.apache.org/milestones/M9/apache-harmony.jar":

 http:
 http://*/milestones/M9/*
 http://*.apache.org/milestones/M9/*
 http://harmony.apache.org/milestones/-
 http://harmony.apache.org/milestones/M9/apache-harmony.jar
 

Parameters:

implied - the Uri to check.

Returns:

true if the argument is implied by this Uri, otherwise false.

getAuthority

public String getAuthority()

Gets the decoded authority part of this URI.

Returns:

the decoded authority part or null if undefined.

getFragment

public String getFragment()

Gets the decoded fragment part of this URI.

Returns:

the decoded fragment part or null if undefined.

getHost

public String getHost()

Gets the host part of this URI.

Returns:

the host part or null if undefined.

getPath

public String getPath()

Gets the decoded path part of this URI.

Returns:

the decoded path part or null if undefined.

getPort

public int getPort()

Gets the port number of this URI.

Returns:

the port number or -1 if undefined.

getQuery

public String getQuery()

Gets the decoded query part of this URI.

Returns:

the decoded query part or null if undefined.

getRawAuthority

public String getRawAuthority()

Gets the authority part of this URI in raw form.

Returns:

the encoded authority part or null if undefined.

getRawFragment

public String getRawFragment()

Gets the fragment part of this URI in raw form.

Returns:

the encoded fragment part or null if undefined.

getRawPath

public String getRawPath()

Gets the path part of this URI in raw form.

Returns:

the encoded path part or null if undefined.

getRawQuery

public String getRawQuery()

Gets the query part of this URI in raw form.

Returns:

the encoded query part or null if undefined.

getRawSchemeSpecificPart

public String getRawSchemeSpecificPart()

Gets the scheme-specific part of this URI in raw form.

Returns:

the encoded scheme-specific part or null if undefined.

getRawUserInfo

public String getRawUserInfo()

Gets the user-info part of this URI in raw form.

Returns:

the encoded user-info part or null if undefined.

getScheme

public String getScheme()

Gets the scheme part of this URI.

Returns:

the scheme part or null if undefined.

getSchemeSpecificPart

public String getSchemeSpecificPart()

Gets the decoded scheme-specific part of this URI.

Returns:

the decoded scheme-specific part or null if undefined.

getUserInfo

public String getUserInfo()

Gets the decoded user-info part of this URI.

Returns:

the decoded user-info part or null if undefined.

hashCode

public int hashCode()

Gets the hashcode value of this URI instance.

Overrides:

hashCode in class Object

Returns:

the appropriate hashcode value.

isAbsolute

public boolean isAbsolute()

Indicates whether this URI is absolute, which means that a scheme part is defined in this URI.

Returns:

true if this URI is absolute, false otherwise.

isOpaque

public boolean isOpaque()

Indicates whether this URI is opaque or not. An opaque URI is absolute and has a scheme-specific part which does not start with a slash character. All parts except scheme, scheme-specific and fragment are undefined.

Returns:

true if the URI is opaque, false otherwise.

normalize

public Uri normalize()

Normalizes the path part of this URI.

Returns:

an URI object which represents this instance with a normalized path.

parseServerAuthority

public Uri parseServerAuthority()
                         throws URISyntaxException

Tries to parse the authority component of this URI to divide it into the host, port, and user-info. If this URI is already determined as a ServerAuthority this instance will be returned without changes.

Returns:

this instance with the components of the parsed server authority.

Throws:

URISyntaxException - if the authority part could not be parsed as a server-based authority.

relativize

public Uri relativize(Uri relative)

Makes the given URI relative to a relative URI against the URI represented by this instance.

Parameters:

relative - the URI which has to be relativized against this URI.

Returns:

the relative URI.

resolve

public Uri resolve(Uri relative)

Resolves the given URI relative against the URI represented by this instance.

Parameters:

relative - the URI which has to be resolved against this URI.

Returns:

the resolved URI.

resolve

public Uri resolve(String relative)

Creates a new URI instance by parsing the given string relative and resolves the created URI against the URI represented by this instance.

Parameters:

relative - the given string to create the new URI instance which has to be resolved later on.

Returns:

the created and resolved URI.

toASCIIString

public String toASCIIString()

Returns the textual string representation of this URI instance using the US-ASCII encoding.

Returns:

the US-ASCII string representation of this URI.

toString

public String toString()

Returns the textual string representation of this URI instance.

Overrides:

toString in class Object

Returns:

the textual string representation of this URI.

toURL

public URL toURL()
          throws MalformedURLException

Converts this URI instance to a URL.

Returns:

the created URL representing the same resource as this URI.

Throws:

MalformedURLException - if an error occurs while creating the URL or no protocol handler could be found.