Maps API for JavaScript Developer's Guide

H.service.Url

Class Summary

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, for example, "ftp://user:password@foo.bar/", are not supported.

[ For full details, see the Class Details ]

Method Summary

Table 1. Methods
Methods
`static parse (url, opt_baseURL) : {H.service.Url}` This method parses a URL string and returns a `Url` object. The URL string must contain at least a scheme and a host.
`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.
`setScheme (scheme) : {H.service.Url}` This method sets the scheme of the given URL object.
`getScheme () : {string}` This method retrieves the scheme for the given `Url` object.
`setHost (host) : {H.service.Url}` This method sets the host for the given `Url` object.
`getHost () : {string}` This method retrieves the host name from the given `Url` object.
`setPath (path) : {H.service.Url}` This method sets the path for the given `Url` object.
`getPath () : {(string \| undefined)}` This method retrieves the path part of the given `Url` object.
`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.
`hasQuery () : {boolean}` This method retrieves a Boolean value indicating whether there are any query string parameter associated with the given `Url`.
`getQuery () : {Object}` This method retrieves the query object of the given `Url` object.
`setAnchor (anchor) : {H.service.Url}` This method sets the anchor for the given `Url` object.
`getAnchor () : {(string \| undefined)}` This method retrieves the anchor from the given `Url` object.
`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.
`addSubDomain (subDomain) : {H.service.Url}` This method adds a sub-domain to the host in the given `Url` object.
`addSubPath (subPath) : {H.service.Url}` This method adds a sub-path to the given `Url`'s path.
`toString () : {string}` This method retrieves a string representation of the given `Url` object.

Class Description

Constructor Details

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

Parameters:
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=} [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:
: {Error}
: 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 number

Method Details

static parse (url, opt_baseURL) : {H.service.Url}

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

Parameters:
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:
: {H.service.Url}
: The parsed URL object

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:
: {H.service.Url}
: An object representing the clone of the given URL object

setScheme (scheme) : {H.service.Url}

This method sets the scheme of the given URL object.

Parameters:
scheme:: {string}
: The new scheme

Returns:
: {H.service.Url}
: An object representing the given instance of Url after modification

getScheme () : {string}

This method retrieves the scheme for the given Url object.

Returns:
: {string}
: The scheme (for example 'http')

setHost (host) : {H.service.Url}

This method sets the host for the given Url object.

Parameters:
host:: {string}
: The new host

Returns:
: {H.service.Url}
: An object representing the given Url object after modification

Throws:
: {Error}
: 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 '.').

getHost () : {string}

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

Returns:
: {string}
: A string containing the host (for example 'api.here.com')

setPath (path) : {H.service.Url}

This method sets the path for the given Url object.

Parameters:
path:: {(string | undefined)}
: A string containing the new path or undefined to clear the path

Returns:
: {H.service.Url}
: An object representing the given Url object after modification

getPath () : {(string | undefined)}

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

Returns:
: {(string | undefined)}
: A string containing the retrieved path (for example 'myresources/resource.html') or undefined if the path is not set

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.

Parameters:
params:: {(Object | undefined)}
: A hash of query string parameters specifying the parameters to be set or a undefined to clear the parameters.

Returns:
: {H.service.Url}
: The given Url object reflecting the modification applied by the method

hasQuery () : {boolean}

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

Returns:
: {boolean}
: true if there are parameters, false if none are present

getQuery () : {Object}

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

Returns:
: {Object}
: The retrieved query object

setAnchor (anchor) : {H.service.Url}

This method sets the anchor for the given Url object.

Parameters:
anchor:: {(string | boolean | undefined)}
: The new anchor or undefined to clear the anchor

Returns:
: {H.service.Url}
: The given Url object reflecting the modification applied by this method

getAnchor () : {(string | undefined)}

This method retrieves the anchor from the given Url object.

Returns:
: {(string | undefined)}
: The retrieved anchor

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.

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

Parameters:
other:: {Object}
: The parameters to be merged into the existing query string parameters

Returns:
: {H.service.Url}
: An object representing the given Url object after modifications applied by the method

Throws:
: {Error}
: Throws an error if the argument is not of type 'object'.

addSubDomain (subDomain) : {H.service.Url}

This method adds a sub-domain to the host in the given Url object.

Parameters:
subDomain:: {string}
: The sub domain (a non-empty string) to be added

Returns:
: {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.

Parameters:
subPath:: {string}
: The path to be added

Returns:
: {H.service.Url}
: An object representing the given Url object after modifications applied by the method

toString () : {string}

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

Returns:
: {string}
: A string representation of the given Url instance