Class: Url

H .service.Url

new H.service.Url (scheme, host, opt_path, opt_params, opt_port, opt_anchor)

This class represents a URL with elements such as the scheme, host/domain, path, etc. Use the static parse method to populate a new URL object from a URL string. Be aware that URLs with user and password are not supported.

Name	Type	Description
`scheme`	string	The URL scheme (e.g. "http" or "https" or "mailto")
`host`	string	The host (or domain) part of the URL
`opt_path`	string	optional The path following the host, pointing to a resource
`opt_params`	Object.<string, *>	optional The query string parameters of the URL
`opt_port`	number	optional The port on the host on which the host listens (if the value is provided as a string, it must be convertible to an integer)
`opt_anchor`	string	optional An optional anchor part of the URL (usually preceded by '#');

Throws:

Throws an error if either the 'scheme' and 'host' are undefined or if 'opt_params' was specified, but cannot be processed, or if the port is defined, but cannot be converted to a valid port number

Classes

DelimitedQuerySubValues
MultiValueQueryParameter

Methods

H.service.Url.parse (url, opt_baseURL)H.service.Url static

This method parses a URL string and returns a Url object. The URL string must contain at least a scheme and a host.

Name	Type	Description
`url`	string	The URL string to parse
`opt_baseURL`	string	optional The base URL to use to resolve relative URLs. If omitted, the method uses the base URL of the document which loaded the API

Returns:

Type	Description
H.service.Url	The parsed URL object

addSubDomain (subDomain)H.service.Url

This method adds a subdomain to the host in the given Url object.

Name	Type	Description
`subDomain`	string	The sub domain (a non-empty string) to be added

Throws:

Throws an error if the argument is not a non-empty string

Returns:

Type	Description
H.service.Url	An object representing the given `Url` object after modifications applied by the method

addSubPath (subPath)H.service.Url

This method adds a sub-path to the given Url's path.

Name	Type	Description
`subPath`	string	The path to be added

Throws:

Throws an error if the argument is not a non-empty string

Returns:

Type	Description
H.service.Url	An object representing the given `Url` object after modifications applied by the method

clone ()H.service.Url

This method clones the given URL object. Optionally, mutations can be passed to this method to modify properties of the cloned object. Note that URL parameters are not replaced but merged with the parameters of the given instance.

Returns:

Type	Description
H.service.Url	An object representing the clone of the given URL object

getAnchor ()string | undefined

This method retrieves the anchor from the given Url object.

Returns:

Type	Description
string \| undefined	The retrieved anchor

getHost ()string

This method retrieves the host name from the given Url object.

Returns:

Type	Description
string	A string containing the host (for example 'api.here.com')

getPath ()string | undefined

This method retrieves the path part of the given Url object.

Returns:

Type	Description
string \| undefined	A string containing the retrieved path (for example 'myresources/resource.html') or `undefined` if the path is not set

getQuery ()Object.<string, *>

This method retrieves the query object of the given Url object.

Returns:

Type	Description
Object.<string, *>	The retrieved query object

getScheme ()string

This method retrieves the scheme for the given Url object.

Returns:

Type	Description
string	The scheme (for example 'http')

hasQuery ()boolean

This method retrieves a Boolean value indicating whether there are any query string parameter associated with the given Url.

Returns:

Type	Description
boolean	`true` if there are parameters, `false` if none are present

mergeQuery (other)H.service.Url

This method merges the provided parameters into the given Url's existing parameters. The key-value pairs which are defined in the argument are used to overwrite the existing URL parameters with matching keys. The key-value pairs which are defined in the argument and are not defined in the given Url object as URL parameters are added. Prototype properties and function properties are not be merged.

Name	Type	Description
`other`	Object.<string, *>	The parameters to be merged into the existing query string parameters

Throws:

Throws an error if the argument is not of type 'object'

Returns:

Type	Description
H.service.Url	An object representing the given `Url` object after modifications applied by the method

Example

var url = new H.service.Url('http', 'api.here.com');
url.setQuery({ 'foo': 'bar' });
url.mergeQuery({ 'foo': 'baz', 'bar': 'foo' });

var newQuery = url.getQuery();
newQuery['foo'] === 'bar' // false
newQuery['foo'] === 'baz' // true
newQuery['bar'] === 'foo' // true

setAnchor (anchor)H.service.Url

This method sets the anchor for the given Url object.

Name	Type	Description
`anchor`	string \| undefined	The new anchor or undefined to clear the anchor

Returns:

Type	Description
H.service.Url	The given `Url` object reflecting the modification applied by this method

setHost (host)H.service.Url

This method sets the host for the given Url object.

Name	Type	Description
`host`	string	The new host

Throws:

Throws an error if the host is not a string, empty or if the host name contains illegal characters (i.e. starts with '-' or '.' or ends with '.').

Returns:

Type	Description
H.service.Url	An object representing the given `Url` object after modification

setPath (path)H.service.Url

This method sets the path for the given Url object.

Name	Type	Description
`path`	string \| undefined	A string containing the new path or `undefined` to clear the path

Returns:

Type	Description
H.service.Url	An object representing the given `Url` object after modification

setQuery (params)H.service.Url

This method sets the specified parameters for the given Url object. Keys in this object, which are associated with undefined values, are treated as query string parameters with no value.

Name	Type	Description
`params`	!Object.<string, *> \| undefined	A hash of query string parameters specifying the parameters to be set or a undefined to clear the parameters

Throws:

Throws an error if the argument is not an object

Returns:

Type	Description
H.service.Url	The given `Url` object reflecting the modification applied by the method

setScheme (scheme)H.service.Url

This method sets the scheme of the given URL object.

Name	Type	Description
`scheme`	string	The new scheme

Throws:

Throws an error if the scheme is not a string or empty

Returns:

Type	Description
H.service.Url	An object representing the given instance of `Url` after modification

toString ()string

This method retrieves a string representation of the given Url object.

Returns:

Type	Description
string	A string representation of the given `Url` instance