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
Methods |
---|
This method parses a URL string and returns a |
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. |
This method sets the scheme of the given URL object. |
This method retrieves the scheme for the given |
This method sets the host for the given |
This method retrieves the host name from the given |
This method sets the path for the given |
This method retrieves the path part of the given |
This method sets the specified parameters for the given |
This method retrieves a Boolean value indicating whether there are any query string parameter associated with the given |
This method retrieves the query object of the given |
This method sets the anchor for the given |
This method retrieves the anchor from the given |
This method merges the provided parameters into the given |
This method adds a sub-domain to the host in the given |
This method adds a sub-path to the given |
This method retrieves a string representation of the given |
Class Description
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.
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