decaf::net::URI Class Reference

This class represents an instance of a URI as defined by RFC 2396. More...

#include <src/main/decaf/net/URI.h>

Inheritance diagram for decaf::net::URI:

Public Member Functions
	URI ()
	Default Constructor, same as calling a Constructor with all fields empty.
	URI (const URI &uri)
	Constructs a URI as a copy of another URI.
	URI (const std::string &uri)
	Constructs a URI from the given string.
	URI (const std::string &scheme, const std::string &ssp, const std::string &fragment)
	Constructs a URI from the given components.
	URI (const std::string &scheme, const std::string &userInfo, const std::string &host, int port, const std::string &path, const std::string &query, const std::string &fragment)
	Constructs a URI from the given components.
	URI (const std::string &scheme, const std::string &host, const std::string &path, const std::string &fragment)
	Constructs a URI from the given components.
	URI (const std::string &scheme, const std::string &authority, const std::string &path, const std::string &query, const std::string &fragment)
	Constructs a URI from the given components.
virtual	~URI ()
virtual int	compareTo (const URI &value) const
	Compares this object with the specified object for order.
virtual bool	equals (const URI &value) const
virtual bool	operator== (const URI &value) const
	Compares equality between this object and the one passed.
virtual bool	operator< (const URI &value) const
	Compares this object to another and returns true if this object is considered to be less than the one passed.
std::string	getAuthority () const
std::string	getFragment () const
std::string	getHost () const
std::string	getPath () const
int	getPort () const
std::string	getQuery () const
std::string	getScheme () const
std::string	getUserInfo () const
std::string	getRawAuthority () const
	Returns the raw authority component of this URI.
std::string	getRawFragment () const
	Returns the raw fragment component of this URI.
std::string	getRawPath () const
	Returns the raw path component of this URI.
std::string	getRawQuery () const
	Returns the raw query component of this URI.
std::string	getRawSchemeSpecificPart () const
	Returns the raw scheme-specific part of this URI.
std::string	getSchemeSpecificPart () const
	Returns the decoded scheme-specific part of this URI.
std::string	getRawUserInfo () const
	Returns the raw user-information component of this URI.
bool	isAbsolute () const
	Tells whether or not this URI is absolute.
bool	isOpaque () const
	Tells whether or not this URI is opaque.
URI	normalize () const
	Normalizes this URI's path.
URI	parseServerAuthority () const
	Attempts to parse this URI's authority component, if defined, into user-information, host, and port components.
URI	relativize (const URI &uri) const
	Relativizes the given URI against this URI.
URI	resolve (const std::string &str) const
	Constructs a new URI by parsing the given string and then resolving it against this URI.
URI	resolve (const URI &uri) const
	Resolves the given URI against this URI.
std::string	toString () const
	Returns the content of this URI as a string.
URL	toURL () const
	Constructs a URL from this URI.
Static Public Member Functions
static URI	create (const std::string uri)
	Creates a URI by parsing the given string.

---

Detailed Description

This class represents an instance of a URI as defined by RFC 2396.

---

Constructor & Destructor Documentation

decaf::net::URI::URI

(

)

Default Constructor, same as calling a Constructor with all fields empty.

decaf::net::URI::URI

(

const URI &

uri

)

Constructs a URI as a copy of another URI.

Parameters:

uri	- uri to copy

Exceptions:

URISyntaxException

if the URI passed is malformed.

decaf::net::URI::URI

(

const std::string &

uri

)

Constructs a URI from the given string.

Parameters:

uri	- string uri to parse.

Exceptions:

URISyntaxException

if the URI passed is malformed.

decaf::net::URI::URI	(	const std::string &	scheme,
		const std::string &	ssp,
		const std::string &	fragment
	)

Constructs a URI from the given components.

Parameters:

scheme	- the uri scheme
ssp	- Scheme specific part
fragment	- Fragment

Exceptions:

URISyntaxException

if the URI passed is malformed.

decaf::net::URI::URI	(	const std::string &	scheme,
		const std::string &	userInfo,
		const std::string &	host,
		int	port,
		const std::string &	path,
		const std::string &	query,
		const std::string &	fragment
	)

Constructs a URI from the given components.

Parameters:

scheme	- Scheme name
userInfo	- User name and authorization information
host	- Host name
port	- Port number
path	- Path
query	- Query
fragment	- Fragment

Exceptions:

URISyntaxException

if the URI passed is malformed.

decaf::net::URI::URI	(	const std::string &	scheme,
		const std::string &	host,
		const std::string &	path,
		const std::string &	fragment
	)

Constructs a URI from the given components.

Parameters:

scheme	- Scheme name
host	- Host name
path	- Path
fragment	- Fragment

Exceptions:

URISyntaxException

if the URI passed is malformed.

decaf::net::URI::URI	(	const std::string &	scheme,
		const std::string &	authority,
		const std::string &	path,
		const std::string &	query,
		const std::string &	fragment
	)

Constructs a URI from the given components.

Parameters:

scheme	- Scheme name
authority	- Authority
path	- Path
query	- Query
fragment	- Fragment

Exceptions:

URISyntaxException

if the URI passed is malformed.

virtual decaf::net::URI::~URI

(

)

[inline, virtual]

---

Member Function Documentation

virtual int decaf::net::URI::compareTo

(

const URI &

value

)

const [virtual]

Compares this object with the specified object for order.

Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Parameters:

value

- the value to compare to this one.

Returns:

zero if equal minus one if less than and one if greater than.

static URI decaf::net::URI::create

(

const std::string

uri

)

[static]

Creates a URI by parsing the given string.

This convenience factory method works as if by invoking the URI(string) constructor; any URISyntaxException thrown by the constructor is caught and wrapped in a new IllegalArgumentException object, which is then thrown.

Parameters:

uri	- URI string to parse

Exceptions:

IllegalArgumentException

virtual bool decaf::net::URI::equals

(

const URI &

value

)

const [virtual]

Returns:

true if this value is considered equal to the passed value.

std::string decaf::net::URI::getAuthority

(

)

const

Returns:

the decoded authority component of this URI.

std::string decaf::net::URI::getFragment

(

)

const

Returns:

the decoded fragment component of this URI.

std::string decaf::net::URI::getHost

(

)

const

Returns:

the host component of this URI.

std::string decaf::net::URI::getPath

(

)

const

Returns:

the path component of this URI.

int decaf::net::URI::getPort

(

)

const

Returns:

the port component of this URI.

std::string decaf::net::URI::getQuery

(

)

const

Returns:

the query component of this URI.

std::string decaf::net::URI::getRawAuthority

(

)

const

Returns the raw authority component of this URI.

The authority component of a URI, if defined, only contains the commercial-at character ('@') and characters in the unreserved, punct, escaped, and other categories. If the authority is server-based then it is further constrained to have valid user-information, host, and port components.

Returns:

the raw authority component of the URI

std::string decaf::net::URI::getRawFragment

(

)

const

Returns the raw fragment component of this URI.

The fragment component of a URI, if defined, only contains legal URI characters.

Returns:

the raw fragment component of this URI

std::string decaf::net::URI::getRawPath

(

)

const

Returns the raw path component of this URI.

The path component of a URI, if defined, only contains the slash character ('/'), the commercial-at character ('@'), and characters in the unreserved, punct, escaped, and other categories.

Returns:

the raw path component of this URI

std::string decaf::net::URI::getRawQuery

(

)

const

Returns the raw query component of this URI.

The query component of a URI, if defined, only contains legal URI characters.

Returns:

the raw query component of the URI.

std::string decaf::net::URI::getRawSchemeSpecificPart

(

)

const

Returns the raw scheme-specific part of this URI.

The scheme-specific part is never undefined, though it may be empty. The scheme-specific part of a URI only contains legal URI characters.

Returns:

the raw scheme special part of the uri

std::string decaf::net::URI::getRawUserInfo

(

)

const

Returns the raw user-information component of this URI.

The user-information component of a URI, if defined, only contains characters in the unreserved, punct, escaped, and other categories.

Returns:

the raw user-information component of the URI

std::string decaf::net::URI::getScheme

(

)

const

Returns:

the scheme component of this URI

std::string decaf::net::URI::getSchemeSpecificPart

(

)

const

Returns the decoded scheme-specific part of this URI.

The string returned by this method is equal to that returned by the getRawSchemeSpecificPart method except that all sequences of escaped octets are decoded.

Returns:

the raw scheme specific part of the uri.

std::string decaf::net::URI::getUserInfo

(

)

const

Returns:

the user info component of this URI

bool decaf::net::URI::isAbsolute

(

)

const

Tells whether or not this URI is absolute.

A URI is absolute if, and only if, it has a scheme component.

Returns:

true if, and only if, this URI is absolute

bool decaf::net::URI::isOpaque

(

)

const

Tells whether or not this URI is opaque.

A URI is opaque if, and only if, it is absolute and its scheme-specific part does not begin with a slash character ('/'). An opaque URI has a scheme, a scheme-specific part, and possibly a fragment; all other components are undefined.

Returns:

true if, and only if, this URI is opaque

URI decaf::net::URI::normalize

(

)

const

Normalizes this URI's path.

If this URI is opaque, or if its path is already in normal form, then this URI is returned. Otherwise a new URI is constructed that is identical to this URI except that its path is computed by normalizing this URI's path in a manner consistent with RFC 2396, section 5.2, step 6, sub-steps c through f; that is:

1. All "." segments are removed. 2. If a ".." segment is preceded by a non-".." segment then both of these segments are removed. This step is repeated until it is no longer applicable. 3. If the path is relative, and if its first segment contains a colon character (':'), then a "." segment is prepended. This prevents a relative URI with a path such as "a:b/c/d" from later being re-parsed as an opaque URI with a scheme of "a" and a scheme-specific part of "b/c/d". (Deviation from RFC 2396)

A normalized path will begin with one or more ".." segments if there were insufficient non-".." segments preceding them to allow their removal. A normalized path will begin with a "." segment if one was inserted by step 3 above. Otherwise, a normalized path will not contain any "." or ".." segments.

Returns:

A URI equivalent to this URI, but whose path is in normal form

virtual bool decaf::net::URI::operator<

(

const URI &

value

)

const [virtual]

Compares this object to another and returns true if this object is considered to be less than the one passed.

This

Parameters:

value

- the value to be compared to this one.

Returns:

true if this object is equal to the one passed.

virtual bool decaf::net::URI::operator==

(

const URI &

value

)

const [virtual]

Compares equality between this object and the one passed.

Parameters:

value

- the value to be compared to this one.

Returns:

true if this object is equal to the one passed.

URI decaf::net::URI::parseServerAuthority

(

)

const

Attempts to parse this URI's authority component, if defined, into user-information, host, and port components.

If this URI's authority component has already been recognized as being server-based then it will already have been parsed into user-information, host, and port components. In this case, or if this URI has no authority component, this method simply returns this URI.

Otherwise this method attempts once more to parse the authority component into user-information, host, and port components, and throws an exception describing why the authority component could not be parsed in that way.

Returns:

A URI whose authority field has been parsed as a server-based authority

Exceptions:

URISyntaxException

- If the authority component of this URI is defined but cannot be parsed as a server-based authority.

URI decaf::net::URI::relativize

(

const URI &

uri

)

const

Relativizes the given URI against this URI.

The relativization of the given URI against this URI is computed as follows:

1. If either this URI or the given URI are opaque, or if the scheme and authority components of the two URIs are not identical, or if the path of this URI is not a prefix of the path of the given URI, then the given URI is returned. 2. Otherwise a new relative hierarchical URI is constructed with query and fragment components taken from the given URI and with a path component computed by removing this URI's path from the beginning of the given URI's path.

Parameters:

uri	- The URI to be relativized against this URI

Returns:

The resulting URI

URI decaf::net::URI::resolve

(

const std::string &

str

)

const

Constructs a new URI by parsing the given string and then resolving it against this URI.

This convenience method works as if invoking it were equivalent to evaluating the expression resolve( URI::create( str ) ).

Parameters:

str	- The string to be parsed into a URI

Returns:

The resulting URI

Exceptions:

IllegalArgumentException

- If the given string violates RFC 2396

URI decaf::net::URI::resolve

(

const URI &

uri

)

const

Resolves the given URI against this URI.

If the given URI is already absolute, or if this URI is opaque, then a copy of the given URI is returned.

If the given URI's fragment component is defined, its path component is empty, and its scheme, authority, and query components are undefined, then a URI with the given fragment but with all other components equal to those of this URI is returned. This allows a URI representing a standalone fragment reference, such as "#foo", to be usefully resolved against a base URI.

Otherwise this method constructs a new hierarchical URI in a manner consistent with RFC 2396, section 5.2; that is:

1. A new URI is constructed with this URI's scheme and the given URI's query and fragment components. 2. If the given URI has an authority component then the new URI's authority and path are taken from the given URI. 3. Otherwise the new URI's authority component is copied from this URI, and its path is computed as follows:

1. If the given URI's path is absolute then the new URI's path is taken from the given URI. 2. Otherwise the given URI's path is relative, and so the new URI's path is computed by resolving the path of the given URI against the path of this URI. This is done by concatenating all but the last segment of this URI's path, if any, with the given URI's path and then normalizing the result as if by invoking the normalize method.

The result of this method is absolute if, and only if, either this URI is absolute or the given URI is absolute.

Parameters:

uri	- The URI to be resolved against this URI

Returns:

The resulting URI

std::string decaf::net::URI::toString

(

)

const

Returns the content of this URI as a string.

If this URI was created by invoking one of the constructors in this class then a string equivalent to the original input string, or to the string computed from the originally-given components, as appropriate, is returned. Otherwise this URI was created by normalization, resolution, or relativization, and so a string is constructed from this URI's components according to the rules specified in RFC 2396, section 5.2, step 7.

Returns:

the string form of this URI

URL decaf::net::URI::toURL

(

)

const

Constructs a URL from this URI.

This convenience method works as if invoking it were equivalent to evaluating the expression new URL(this.toString()) after first checking that this URI is absolute.

Returns:

A URL constructed from this URI

Exceptions:

IllegalArgumentException	- If this URL is not absolute
MalformedURLException	- If a protocol handler for the URL could not be found, or if some other error occurred while constructing the URL

---

The documentation for this class was generated from the following file:

• src/main/decaf/net/URI.h