Class to represent general URLs. More...

#include <arc/URL.h>

Inheritance diagram for Arc::URL:

Public Types
enum	Scope { base, onelevel, subtree }
	Scope for LDAP URLs. More...

Public Member Functions
	URL ()
	Empty constructor. URL object is invalid. More...

	URL (const std::string &url, bool encoded=false, int defaultPort=-1, const std::string &defaultPath="")
	Constructs a new URL from a string representation. More...

virtual	~URL ()
	Empty destructor. More...

void	URIDecode (void)
	Perform decoding of stored URL parts according to RFC 3986. More...

const std::string &	Protocol () const
	Returns the protocol of the URL. More...

void	ChangeProtocol (const std::string &newprot)
	Changes the protocol of the URL. More...

const std::string &	Username () const
	Returns the username of the URL. More...

const std::string &	Passwd () const
	Returns the password of the URL. More...

const std::string &	Host () const
	Returns the hostname of the URL. More...

void	ChangeHost (const std::string &newhost)
	Changes the hostname of the URL. More...

int	Port () const
	Returns the port of the URL. More...

void	ChangePort (int newport)
	Changes the port of the URL. More...

const std::string &	Path () const
	Returns the path of the URL. More...

std::string	FullPath () const
	Returns the path of the URL with all options attached. More...

std::string	FullPathURIEncoded () const
	Returns the path and all options, URI-encoded according to RFC 3986. More...

void	ChangePath (const std::string &newpath)
	Changes the path of the URL. More...

void	ChangeFullPath (const std::string &newpath, bool encoded=false)
	Changes the path of the URL and all options attached. More...

const std::map< std::string, std::string > &	HTTPOptions () const
	Returns HTTP options if any. More...

const std::string &	HTTPOption (const std::string &option, const std::string &undefined="") const
	Returns the value of an HTTP option. More...

bool	AddHTTPOption (const std::string &option, const std::string &value, bool overwrite=true)
	Adds a HTP option with the given value. More...

void	RemoveHTTPOption (const std::string &option)
	Removes a HTTP option if exists. More...

const std::list< std::string > &	LDAPAttributes () const
	Returns the LDAP attributes if any. More...

void	AddLDAPAttribute (const std::string &attribute)
	Adds an LDAP attribute. More...

Scope	LDAPScope () const
	Returns the LDAP scope. More...

void	ChangeLDAPScope (const Scope newscope)
	Changes the LDAP scope. More...

const std::string &	LDAPFilter () const
	Returns the LDAP filter. More...

void	ChangeLDAPFilter (const std::string &newfilter)
	Changes the LDAP filter. More...

const std::map< std::string, std::string > &	Options () const
	Returns URL options if any. More...

const std::string &	Option (const std::string &option, const std::string &undefined="") const
	Returns the value of a URL option. More...

const std::map< std::string, std::string > &	MetaDataOptions () const
	Returns metadata options if any. More...

const std::string &	MetaDataOption (const std::string &option, const std::string &undefined="") const
	Returns the value of a metadata option. More...

bool	AddOption (const std::string &option, const std::string &value, bool overwrite=true)
	Adds a URL option with the given value. More...

bool	AddOption (const std::string &option, bool overwrite=true)
	Adds a URL option where option has the format "name=value". More...

void	AddMetaDataOption (const std::string &option, const std::string &value, bool overwrite=true)
	Adds a metadata option. More...

void	AddLocation (const URLLocation &location)
	Adds a Location. More...

const std::list< URLLocation > &	Locations () const
	Returns the locations if any. More...

const std::map< std::string, std::string > &	CommonLocOptions () const
	Returns the common location options if any. More...

const std::string &	CommonLocOption (const std::string &option, const std::string &undefined="") const
	Returns the value of a common location option. More...

void	RemoveOption (const std::string &option)
	Removes a URL option if exists. More...

void	RemoveMetaDataOption (const std::string &option)
	Remove a metadata option if exits. More...

virtual std::string	str (bool encode=false) const
	Returns a string representation of the URL including meta-options. More...

virtual std::string	plainstr (bool encode=false) const
	Returns a string representation of the URL without any options. More...

virtual std::string	fullstr (bool encode=false) const
	Returns a string representation including options and locations. More...

virtual std::string	ConnectionURL () const
	Returns a string representation with protocol, host and port only. More...

bool	operator< (const URL &url) const
	Compares one URL to another. More...

bool	operator== (const URL &url) const
	Is one URL equal to another? More...

	operator bool () const
	Check if instance holds valid URL. More...

bool	operator! () const
	Check if instance does not hold valid URL. More...

bool	StringMatches (const std::string &str) const
	Returns true if string matches url. More...

std::map< std::string, std::string >	ParseOptions (const std::string &optstring, char separator, bool encoded=false)
	Parse a string of options separated by separator into an attribute->value map. More...

Static Public Member Functions
static std::string	OptionString (const std::map< std::string, std::string > &options, char separator, bool encode=false)
	Returns a string representation of the options given in the options map. More...

static std::string	URIEncode (const std::string &str)
	Perform encoding according to RFC 3986. More...

static std::string	URIDecode (const std::string &str)
	Perform decoding according to RFC 3986. More...

Protected Member Functions
void	ParsePath (bool encoded=false)
	Convenience method for splitting schema specific part into path and options. More...

Static Protected Member Functions
static std::string	BaseDN2Path (const std::string &)
	a private method that converts an ldap basedn to a path. More...

static std::string	Path2BaseDN (const std::string &)
	a private method that converts an ldap path to a basedn. More...

Protected Attributes
std::string	protocol
	the url protocol. More...

std::string	username
	username of the url. More...

std::string	passwd
	password of the url. More...

std::string	host
	hostname of the url. More...

bool	ip6addr
	if host is IPv6 numerical address notation. More...

int	port
	portnumber of the url. More...

std::string	path
	the url path. More...

std::map< std::string, std::string >	httpoptions
	HTTP options of the url. More...

std::map< std::string, std::string >	metadataoptions
	Meta data options. More...

std::list< std::string >	ldapattributes
	LDAP attributes of the url. More...

Scope	ldapscope
	LDAP scope of the url. More...

std::string	ldapfilter
	LDAP filter of the url. More...

std::map< std::string, std::string >	urloptions
	options of the url. More...

std::list< URLLocation >	locations
	locations for index server URLs. More...

std::map< std::string, std::string >	commonlocoptions
	common location options for index server URLs. More...

bool	valid
	flag to describe validity of URL More...

Friends
std::ostream &	operator<< (std::ostream &out, const URL &u)
	Overloaded operator << to print a URL. More...

Detailed Description

Class to represent general URLs.

  The URL is split into protocol, hostname, port and path. This class tries
  to follow RFC 3986 for splitting URLs, at least for protocol + host part.
  It also accepts local file paths which are converted to file:path.
  The usual system dependent file paths are supported. Relative paths are
  converted to absolute paths by prepending them with current working
  directory path. A file path can't start from # symbol. If the string
  representation of URL starts from '@' then it is treated as path to a
  file containing a list of URLs.

  A URL is parsed in the following way:

 [protocol:][//[username:passwd@][host][:port]][;urloptions[;...]][/path[?httpoption[&...]][:metadataoption[:...]]]

The 'protocol' and 'host' parts are treated as case-insensitive and to avoid confusion are converted to lowercase in constructor. Note that 'path' is always converted to absolute path in the constructor. The meaning of 'absolute' may depend upon URL type. For generic URL and local POSIX file paths that means the path starts from / like

 /path/to/file

For Windows paths the absolute path may look like

 C:\path\to\file

It is important to note that path still can be empty. For referencing a local file using an absolute path on a POSIX filesystem one may use either

 file:///path/to/file or file:/path/to/file

The relative path will look like

 file:to/file

For local Windows files possible URLs are

 %file:C:\path\to\file or %file:to\file

URLs representing LDAP resources have a different structure of options following the 'path' part:

 ldap://host[:port][;urloptions[;...]][/path[?attributes[?scope[?filter]]]]

For LDAP URLs paths are converted from /key1=value1/.../keyN=valueN notation to keyN=valueN,...,key1=value1 and hence path does not contain a leading /. If an LDAP URL initially had its path in the second notation, the leading / is treated as a separator only and is stripped.

URLs of indexing services optionally may have locations specified before the 'host' part

 protocol://[location[;location[;...]]@][host][:port]...

The structure of the 'location' element is protocol specific.

Member Enumeration Documentation

enum Arc::URL::Scope

Scope for LDAP URLs.

Constructor & Destructor Documentation

Arc::URL::URL ( )

Empty constructor. URL object is invalid.

Arc::URL::URL	(	const std::string &	url,
		bool	encoded = `false`,
		int	defaultPort = `-1`,
		const std::string &	defaultPath = `""`
	)

Constructs a new URL from a string representation.

Parameters

url	The string representation of URL
encoded	Set to true if URL is encoded according to RFC 3986
defaultPort	Port to use if 'url' doesn't specify port
defaultPath	Path to use if 'url' doesn't specify path

Since: Changed in 4.1.0. defaultPort and defaultPath arguments added.

virtual Arc::URL::~URL ( )

virtual

Empty destructor.

Member Function Documentation

bool Arc::URL::AddHTTPOption	(	const std::string &	option,
		const std::string &	value,
		bool	overwrite = `true`
	)

Adds a HTP option with the given value.

Returns: false if overwrite is false and option already exists, true otherwise.

void Arc::URL::AddLDAPAttribute ( const std::string & attribute )

Adds an LDAP attribute.

void Arc::URL::AddLocation ( const URLLocation & location )

Adds a Location.

void Arc::URL::AddMetaDataOption	(	const std::string &	option,
		const std::string &	value,
		bool	overwrite = `true`
	)

Adds a metadata option.

bool Arc::URL::AddOption	(	const std::string &	option,
		const std::string &	value,
		bool	overwrite = `true`
	)

Adds a URL option with the given value.

Note that some compilers may interpret AddOption("name", "value") as a call to AddOption(const std::string&, bool) so it is recommended to use explicit string types when calling this method.

Returns: false if overwrite is false and option already exists, true otherwise.

bool Arc::URL::AddOption	(	const std::string &	option,
		bool	overwrite = `true`
	)

Adds a URL option where option has the format "name=value".

Returns: false if overwrite is true and option already exists or if option does not have the correct format. Returns true otherwise.

static std::string Arc::URL::BaseDN2Path ( const std::string & )

staticprotected

a private method that converts an ldap basedn to a path.

void Arc::URL::ChangeFullPath	(	const std::string &	newpath,
		bool	encoded = `false`
	)

Changes the path of the URL and all options attached.

void Arc::URL::ChangeHost ( const std::string & newhost )

Changes the hostname of the URL.

void Arc::URL::ChangeLDAPFilter ( const std::string & newfilter )

Changes the LDAP filter.

void Arc::URL::ChangeLDAPScope ( const Scope newscope )

Changes the LDAP scope.

void Arc::URL::ChangePath ( const std::string & newpath )

Changes the path of the URL.

void Arc::URL::ChangePort ( int newport )

Changes the port of the URL.

void Arc::URL::ChangeProtocol ( const std::string & newprot )

Changes the protocol of the URL.

const std::string& Arc::URL::CommonLocOption	(	const std::string &	option,
		const std::string &	undefined = `""`
	)		const

Returns the value of a common location option.

Parameters

option	The option whose value is returned.
undefined	This value is returned if the common location option is not defined.

const std::map<std::string, std::string>& Arc::URL::CommonLocOptions ( ) const

Returns the common location options if any.

virtual std::string Arc::URL::ConnectionURL ( ) const

virtual

Returns a string representation with protocol, host and port only.

std::string Arc::URL::FullPath ( ) const

Returns the path of the URL with all options attached.

std::string Arc::URL::FullPathURIEncoded ( ) const

Returns the path and all options, URI-encoded according to RFC 3986.

Forward slashes ('/') in the path are not encoded but are encoded in the options.

virtual std::string Arc::URL::fullstr ( bool encode = false ) const

virtual

Returns a string representation including options and locations.

const std::string& Arc::URL::Host ( ) const

Returns the hostname of the URL.

const std::string& Arc::URL::HTTPOption	(	const std::string &	option,
		const std::string &	undefined = `""`
	)		const

Returns the value of an HTTP option.

Parameters

option	The option whose value is returned.
undefined	This value is returned if the HTTP option is not defined.

const std::map<std::string, std::string>& Arc::URL::HTTPOptions ( ) const

Returns HTTP options if any.

const std::list<std::string>& Arc::URL::LDAPAttributes ( ) const

Returns the LDAP attributes if any.

const std::string& Arc::URL::LDAPFilter ( ) const

Returns the LDAP filter.

Scope Arc::URL::LDAPScope ( ) const

Returns the LDAP scope.

const std::list<URLLocation>& Arc::URL::Locations ( ) const

Returns the locations if any.

const std::string& Arc::URL::MetaDataOption	(	const std::string &	option,
		const std::string &	undefined = `""`
	)		const

Returns the value of a metadata option.

Parameters

option	The option whose value is returned.
undefined	This value is returned if the metadata option is not defined.

const std::map<std::string, std::string>& Arc::URL::MetaDataOptions ( ) const

Returns metadata options if any.

Arc::URL::operator bool ( ) const

Check if instance holds valid URL.

bool Arc::URL::operator! ( ) const

Check if instance does not hold valid URL.

Python interface deviation: Method is unavailable in Python interface

Java interface deviation: Method is unavailable in Java interface

bool Arc::URL::operator< ( const URL & url ) const

Compares one URL to another.

bool Arc::URL::operator== ( const URL & url ) const

Is one URL equal to another?

const std::string& Arc::URL::Option	(	const std::string &	option,
		const std::string &	undefined = `""`
	)		const

Returns the value of a URL option.

Parameters

option	The option whose value is returned.
undefined	This value is returned if the URL option is not defined.

const std::map<std::string, std::string>& Arc::URL::Options ( ) const

Returns URL options if any.

static std::string Arc::URL::OptionString	(	const std::map< std::string, std::string > &	options,
		char	separator,
		bool	encode = `false`
	)

static

Returns a string representation of the options given in the options map.

Parameters

options	Key-value map of options
separator	The character that separates options
encode	if set to true then options are encoded according to RFC 3986

std::map<std::string, std::string> Arc::URL::ParseOptions	(	const std::string &	optstring,
		char	separator,
		bool	encoded = `false`
	)

Parse a string of options separated by separator into an attribute->value map.

void Arc::URL::ParsePath ( bool encoded = false )

protected

Convenience method for splitting schema specific part into path and options.

const std::string& Arc::URL::Passwd ( ) const

Returns the password of the URL.

const std::string& Arc::URL::Path ( ) const

Returns the path of the URL.

static std::string Arc::URL::Path2BaseDN ( const std::string & )

staticprotected

a private method that converts an ldap path to a basedn.

virtual std::string Arc::URL::plainstr ( bool encode = false ) const

virtual

Returns a string representation of the URL without any options.

int Arc::URL::Port ( ) const

Returns the port of the URL.

const std::string& Arc::URL::Protocol ( ) const

Returns the protocol of the URL.

void Arc::URL::RemoveHTTPOption ( const std::string & option )

Removes a HTTP option if exists.

Parameters

option The option to remove.

void Arc::URL::RemoveMetaDataOption ( const std::string & option )

Remove a metadata option if exits.

Parameters

option The option to remove.

void Arc::URL::RemoveOption ( const std::string & option )

Removes a URL option if exists.

Parameters

option The option to remove.

virtual std::string Arc::URL::str ( bool encode = false ) const

virtual

Returns a string representation of the URL including meta-options.

bool Arc::URL::StringMatches ( const std::string & str ) const

Returns true if string matches url.

void Arc::URL::URIDecode ( void )

Perform decoding of stored URL parts according to RFC 3986.

This method is supposed to be used only if for some reason URL constructor was called with encoded=false for URL which was encoded. Use it only once.

static std::string Arc::URL::URIDecode ( const std::string & str )

static

Perform decoding according to RFC 3986.

This simply calls Arc::uri_unencode().

static std::string Arc::URL::URIEncode ( const std::string & str )

static

Perform encoding according to RFC 3986.

This simply calls Arc::uri_encode().

const std::string& Arc::URL::Username ( ) const

Returns the username of the URL.

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	out,
		const URL &	u
	)

friend

Overloaded operator << to print a URL.

Field Documentation

std::map<std::string, std::string> Arc::URL::commonlocoptions

protected

common location options for index server URLs.

Java interface deviation: The member is only accessible through the getcommonlocoptions and setcommonlocoptions methods in the Java interface

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Field Documentation