com.google.api.client.http

Class GenericUrl

java.lang.Object

java.util.AbstractMap<String,Object>

com.google.api.client.util.GenericData

com.google.api.client.http.GenericUrl

All Implemented Interfaces:

Cloneable, Map<String,Object>

public class GenericUrl
extends GenericData

URL builder in which the query parameters are specified as generic data key/value pairs, based on the specification RFC 3986: Uniform Resource Identifier (URI).

The query parameters are specified with the data key name as the parameter name, and the data value as the parameter value. Subclasses can declare fields for known query parameters using the Key annotation. null parameter names are not allowed, but null query values are allowed.

Query parameter values are parsed using UrlEncodedParser.parse(String, Object).

Implementation is not thread-safe.

Since:

1.0

Author:

Yaniv Inbar

Nested Class Summary

Nested classes/interfaces inherited from class com.google.api.client.util.GenericData

GenericData.Flags

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
GenericUrl()
GenericUrl(String encodedUrl) Constructs a GenericUrl from a URL encoded string.
GenericUrl(String encodedUrl, boolean verbatim) Constructs a GenericUrl from a string.
GenericUrl(URI uri) Constructs from a URI.
GenericUrl(URI uri, boolean verbatim) Constructs from a URI.
GenericUrl(URL url) Constructs from a URL.
GenericUrl(URL url, boolean verbatim) Constructs from a URL.

Method Summary

Modifier and Type	Method and Description
void	appendRawPath(String encodedPath) Appends the given raw encoded path to the current pathParts, setting field only if it is null or empty.
String	build() Constructs the string representation of the URL, including the path specified by pathParts and the query parameters specified by this generic URL.
String	buildAuthority() Constructs the portion of the URL containing the scheme, host and port.
String	buildRelativeUrl() Constructs the portion of the URL beginning at the rooted path.
GenericUrl	clone() Makes a "deep" clone of the generic data, in which the clone is completely independent of the original.
boolean	equals(Object obj)
Collection<Object>	getAll(String name) Returns all query parameter values for the given query parameter name.
Object	getFirst(String name) Returns the first query parameter value for the given query parameter name.
String	getFragment() Returns the fragment component or null for none.
String	getHost() Returns the host, for example "www.google.com".
List<String>	getPathParts() Returns the decoded path component by parts with each part separated by a '/' or null for none.
int	getPort() Returns the port number or -1 if undefined, for example 443.
String	getRawPath() Returns the raw encoded path computed from the pathParts.
String	getScheme() Returns the scheme (lowercase), for example "https".
String	getUserInfo() Returns the user info or null for none, for example "username:password".
int	hashCode()
GenericUrl	set(String fieldName, Object value) Sets the given field value (may be null) for the given field name.
void	setFragment(String fragment) Sets the fragment component or null for none.
void	setHost(String host) Sets the host, for example "www.google.com".
void	setPathParts(List<String> pathParts) Sets the decoded path component by parts with each part separated by a '/' or null for none.
void	setPort(int port) Sets the port number, for example 443.
void	setRawPath(String encodedPath) Sets the pathParts from the given raw encoded path.
void	setScheme(String scheme) Sets the scheme (lowercase), for example "https".
void	setUserInfo(String userInfo) Sets the user info or null for none, for example "username:password".
static List<String>	toPathParts(String encodedPath) Returns the decoded path parts for the given encoded path.
static List<String>	toPathParts(String encodedPath, boolean verbatim) Returns the path parts (decoded if not verbatim).
String	toString()
URI	toURI() Constructs the URI based on the string representation of the URL from build().
URL	toURL() Constructs the URL based on the string representation of the URL from build().
URL	toURL(String relativeUrl) Constructs the URL based on URL(URL, String) with this URL representation from toURL() and a relative url.

Methods inherited from class com.google.api.client.util.GenericData

entrySet, get, getClassInfo, getUnknownKeys, put, putAll, remove, setUnknownKeys

Methods inherited from class java.util.AbstractMap

clear, containsKey, containsValue, isEmpty, keySet, size, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

GenericUrl

public GenericUrl()

GenericUrl

public GenericUrl(String encodedUrl)

Constructs a GenericUrl from a URL encoded string.

Any known query parameters with pre-defined fields as data keys will be parsed based on their data type. Any unrecognized query parameter will always be parsed as a string.

Any MalformedURLException is wrapped in an IllegalArgumentException.

Upgrade warning: starting in version 1.18 this parses the encodedUrl using new URL(encodedUrl). In previous versions it used new URI(encodedUrl). In particular, this means that only a limited set of schemes are allowed such as "http" and "https", but that parsing is compliant with, at least, RFC 3986.

Parameters:

encodedUrl - encoded URL, including any existing query parameters that should be parsed

Throws:

IllegalArgumentException - if the URL has a syntax error

GenericUrl

public GenericUrl(String encodedUrl,
                  boolean verbatim)

Constructs a GenericUrl from a string.

Any known query parameters with pre-defined fields as data keys will be parsed based on their data type. Any unrecognized query parameter will always be parsed as a string.

Any MalformedURLException is wrapped in an IllegalArgumentException.

Parameters:

encodedUrl - encoded URL, including any existing query parameters that should be parsed

verbatim - flag, to specify if URL should be used as is (without encoding, decoding and escaping)

Throws:

IllegalArgumentException - if URL has a syntax error

GenericUrl

public GenericUrl(URI uri)

Constructs from a URI.

Parameters:

uri - URI

Since:

1.14

GenericUrl

public GenericUrl(URI uri,
                  boolean verbatim)

Constructs from a URI.

Parameters:

uri - URI

verbatim - flag, to specify if URL should be used as is (without encoding, decoding and escaping)

GenericUrl

public GenericUrl(URL url)

Constructs from a URL.

Parameters:

url - URL

Since:

1.14

GenericUrl

public GenericUrl(URL url,
                  boolean verbatim)

Constructs from a URL.

Parameters:

url - URL

verbatim - flag, to specify if URL should be used as is (without encoding, decoding and escaping)

Since:

1.14

Method Detail

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<String,Object>

Overrides:

hashCode in class GenericData

equals

public boolean equals(Object obj)

Specified by:

equals in interface Map<String,Object>

Overrides:

equals in class GenericData

toString

public String toString()

Overrides:

toString in class GenericData

clone

public GenericUrl clone()

Description copied from class: GenericData

Makes a "deep" clone of the generic data, in which the clone is completely independent of the original.

Overrides:

clone in class GenericData

set

public GenericUrl set(String fieldName,
                      Object value)

Description copied from class: GenericData

Sets the given field value (may be null) for the given field name. Any existing value for the field will be overwritten. It may be more slightly more efficient than GenericData.put(String, Object) because it avoids accessing the field's original value.

Overriding is only supported for the purpose of calling the super implementation and changing the return type, but nothing else.

Overrides:

set in class GenericData

getScheme

public final String getScheme()

Returns the scheme (lowercase), for example "https".

Since:

1.5

setScheme

public final void setScheme(String scheme)

Sets the scheme (lowercase), for example "https".

Since:

1.5

getHost

public String getHost()

Returns the host, for example "www.google.com".

Since:

1.5

setHost

public final void setHost(String host)

Sets the host, for example "www.google.com".

Since:

1.5

getUserInfo

public final String getUserInfo()

Returns the user info or null for none, for example "username:password".

Since:

1.15

setUserInfo

public final void setUserInfo(String userInfo)

Sets the user info or null for none, for example "username:password".

Since:

1.15

getPort

public int getPort()

Returns the port number or -1 if undefined, for example 443.

Since:

1.5

setPort

public final void setPort(int port)

Sets the port number, for example 443.

Since:

1.5

getPathParts

public List<String> getPathParts()

Returns the decoded path component by parts with each part separated by a '/' or null for none.

Since:

1.5

setPathParts

public void setPathParts(List<String> pathParts)

Sets the decoded path component by parts with each part separated by a '/' or null for none.

For example "/m8/feeds/contacts/default/full" is represented by "", "m8", "feeds", "contacts", "default", "full".

Use appendRawPath(String) to append to the path, which ensures that no extra slash is added.

Since:

1.5

getFragment

public String getFragment()

Returns the fragment component or null for none.

Since:

1.5

setFragment

public final void setFragment(String fragment)

Sets the fragment component or null for none.

Since:

1.5

build

public final String build()

Constructs the string representation of the URL, including the path specified by pathParts and the query parameters specified by this generic URL.

buildAuthority

public final String buildAuthority()

Constructs the portion of the URL containing the scheme, host and port.

For the URL "http://example.com/something?action=add" this method would return "http://example.com".

Returns:

scheme://[user-info@]host[:port]

Since:

1.9

buildRelativeUrl

public final String buildRelativeUrl()

Constructs the portion of the URL beginning at the rooted path.

For the URL "http://example.com/something?action=add" this method would return "/something?action=add".

Returns:

path with with leading '/' if the path is non-empty, query parameters and fragment

Since:

1.9

toURI

public final URI toURI()

Constructs the URI based on the string representation of the URL from build().

Any URISyntaxException is wrapped in an IllegalArgumentException.

Returns:

new URI instance

Since:

1.14

toURL

public final URL toURL()

Constructs the URL based on the string representation of the URL from build().

Any MalformedURLException is wrapped in an IllegalArgumentException.

Returns:

new URL instance

Since:

1.14

toURL

public final URL toURL(String relativeUrl)

Constructs the URL based on URL(URL, String) with this URL representation from toURL() and a relative url.

Any MalformedURLException is wrapped in an IllegalArgumentException.

Returns:

new URL instance

Since:

1.14

getFirst

public Object getFirst(String name)

Returns the first query parameter value for the given query parameter name.

Parameters:

name - query parameter name

Returns:

first query parameter value

getAll

public Collection<Object> getAll(String name)

Returns all query parameter values for the given query parameter name.

Parameters:

name - query parameter name

Returns:

unmodifiable collection of query parameter values (possibly empty)

getRawPath

public String getRawPath()

Returns the raw encoded path computed from the pathParts.

Returns:

raw encoded path computed from the pathParts or null if pathParts is null

setRawPath

public void setRawPath(String encodedPath)

Sets the pathParts from the given raw encoded path.

Parameters:

encodedPath - raw encoded path or null to set pathParts to null

appendRawPath

public void appendRawPath(String encodedPath)

Appends the given raw encoded path to the current pathParts, setting field only if it is null or empty.

The last part of the pathParts is merged with the first part of the path parts computed from the given encoded path. Thus, if the current raw encoded path is "a", and the given encoded path is "b", then the resulting raw encoded path is "ab".

Parameters:

encodedPath - raw encoded path or null to ignore

toPathParts

public static List<String> toPathParts(String encodedPath)

Returns the decoded path parts for the given encoded path.

Parameters:

encodedPath - slash-prefixed encoded path, for example "/m8/feeds/contacts/default/full"

Returns:

decoded path parts, with each part assumed to be preceded by a '/', for example "", "m8", "feeds", "contacts", "default", "full", or null for null or "" input

toPathParts

public static List<String> toPathParts(String encodedPath,
                                       boolean verbatim)

Returns the path parts (decoded if not verbatim).

Parameters:

encodedPath - slash-prefixed encoded path, for example "/m8/feeds/contacts/default/full"

verbatim - flag, to specify if URL should be used as is (without encoding, decoding and escaping)

Returns:

path parts (decoded if not verbatim), with each part assumed to be preceded by a '/', for example "", "m8", "feeds", "contacts", "default", "full", or null for null or "" input