Package com.google.api.client.http

Class GenericUrl

  • All Implemented Interfaces:
    java.lang.Cloneable, java.util.Map<java.lang.String,​java.lang.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

    • Nested Class Summary

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

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>

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

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.String fragment
      Fragment component or null for none.
      private java.lang.String host
      Host, for example "www.google.com".
      private java.util.List<java.lang.String> pathParts
      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".
      private int port
      Port number or -1 if undefined, for example 443.
      private java.lang.String scheme
      Scheme (lowercase), for example "https".
      private static Escaper URI_FRAGMENT_ESCAPER  
      private java.lang.String userInfo
      User info or null for none, for example "username:password".
      private boolean verbatim
      If true, the URL string originally given is used as is (without encoding, decoding and escaping) whenever referenced; otherwise, part of the URL string may be encoded or decoded as deemed appropriate or necessary.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        GenericUrl()  
        GenericUrl​(java.lang.String encodedUrl)
      Constructs a GenericUrl from a URL encoded string.
        GenericUrl​(java.lang.String encodedUrl, boolean verbatim)
      Constructs a GenericUrl from a string.
      private GenericUrl​(java.lang.String scheme, java.lang.String host, int port, java.lang.String path, java.lang.String fragment, java.lang.String query, java.lang.String userInfo, boolean verbatim)  
        GenericUrl​(java.net.URI uri)
      Constructs from a URI.
        GenericUrl​(java.net.URI uri, boolean verbatim)
      Constructs from a URI.
        GenericUrl​(java.net.URL url)
      Constructs from a URL.
        GenericUrl​(java.net.URL url, boolean verbatim)
      Constructs from a URL.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static void addQueryParams​(java.util.Set<java.util.Map.Entry<java.lang.String,​java.lang.Object>> entrySet, java.lang.StringBuilder buf, boolean verbatim)
      Adds query parameters from the provided entrySet into the buffer.
      private static boolean appendParam​(boolean first, java.lang.StringBuilder buf, java.lang.String name, java.lang.Object value, boolean verbatim)  
      void appendRawPath​(java.lang.String encodedPath)
      Appends the given raw encoded path to the current pathParts, setting field only if it is null or empty.
      private void appendRawPathFromParts​(java.lang.StringBuilder buf)  
      java.lang.String build()
      Constructs the string representation of the URL, including the path specified by pathParts and the query parameters specified by this generic URL.
      java.lang.String buildAuthority()
      Constructs the portion of the URL containing the scheme, host and port.
      java.lang.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​(java.lang.Object obj)  
      java.util.Collection<java.lang.Object> getAll​(java.lang.String name)
      Returns all query parameter values for the given query parameter name.
      java.lang.Object getFirst​(java.lang.String name)
      Returns the first query parameter value for the given query parameter name.
      java.lang.String getFragment()
      Returns the fragment component or null for none.
      java.lang.String getHost()
      Returns the host, for example "www.google.com".
      java.util.List<java.lang.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.
      java.lang.String getRawPath()
      Returns the raw encoded path computed from the pathParts.
      java.lang.String getScheme()
      Returns the scheme (lowercase), for example "https".
      java.lang.String getUserInfo()
      Returns the user info or null for none, for example "username:password".
      int hashCode()  
      private static java.net.URL parseURL​(java.lang.String encodedUrl)
      Returns the URI for the given encoded URL.
      GenericUrl set​(java.lang.String fieldName, java.lang.Object value)
      Sets the given field value (may be null) for the given field name.
      void setFragment​(java.lang.String fragment)
      Sets the fragment component or null for none.
      void setHost​(java.lang.String host)
      Sets the host, for example "www.google.com".
      void setPathParts​(java.util.List<java.lang.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​(java.lang.String encodedPath)
      Sets the pathParts from the given raw encoded path.
      void setScheme​(java.lang.String scheme)
      Sets the scheme (lowercase), for example "https".
      void setUserInfo​(java.lang.String userInfo)
      Sets the user info or null for none, for example "username:password".
      static java.util.List<java.lang.String> toPathParts​(java.lang.String encodedPath)
      Returns the decoded path parts for the given encoded path.
      static java.util.List<java.lang.String> toPathParts​(java.lang.String encodedPath, boolean verbatim)
      Returns the path parts (decoded if not verbatim).
      java.lang.String toString()  
      java.net.URI toURI()
      Constructs the URI based on the string representation of the URL from build().
      private static java.net.URI toURI​(java.lang.String encodedUrl)
      Returns the URI for the given encoded URL.
      java.net.URL toURL()
      Constructs the URL based on the string representation of the URL from build().
      java.net.URL toURL​(java.lang.String relativeUrl)
      Constructs the URL based on URL(URL, String) with this URL representation from toURL() and a relative url.

      • 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

    • Field Detail

      • URI_FRAGMENT_ESCAPER

        private static final Escaper URI_FRAGMENT_ESCAPER

      • scheme

        private java.lang.String scheme
        Scheme (lowercase), for example "https".

      • host

        private java.lang.String host
        Host, for example "www.google.com".

      • userInfo

        private java.lang.String userInfo
        User info or null for none, for example "username:password".

      • port

        private int port
        Port number or -1 if undefined, for example 443.

      • pathParts

        private java.util.List<java.lang.String> pathParts
        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.

      • fragment

        private java.lang.String fragment
        Fragment component or null for none.

      • verbatim

        private boolean verbatim
        If true, the URL string originally given is used as is (without encoding, decoding and escaping) whenever referenced; otherwise, part of the URL string may be encoded or decoded as deemed appropriate or necessary.

    • Constructor Detail

      • GenericUrl

        public GenericUrl()

      • GenericUrl

        public GenericUrl​(java.lang.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:
        java.lang.IllegalArgumentException - if the URL has a syntax error

      • GenericUrl

        public GenericUrl​(java.lang.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:
        java.lang.IllegalArgumentException - if URL has a syntax error

      • GenericUrl

        public GenericUrl​(java.net.URI uri)
        Constructs from a URI.
        Parameters:
        uri - URI
        Since:
        1.14

      • GenericUrl

        public GenericUrl​(java.net.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​(java.net.URL url)
        Constructs from a URL.
        Parameters:
        url - URL
        Since:
        1.14

      • GenericUrl

        public GenericUrl​(java.net.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

      • GenericUrl

        private GenericUrl​(java.lang.String scheme,
                   java.lang.String host,
                   int port,
                   java.lang.String path,
                   java.lang.String fragment,
                   java.lang.String query,
                   java.lang.String userInfo,
                   boolean verbatim)

    • Method Detail

      • hashCode

        public int hashCode()
        Specified by:
        hashCode in interface java.util.Map<java.lang.String,​java.lang.Object>
        Overrides:
        hashCode in class GenericData

      • equals

        public boolean equals​(java.lang.Object obj)
        Specified by:
        equals in interface java.util.Map<java.lang.String,​java.lang.Object>
        Overrides:
        equals 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​(java.lang.String fieldName,
                      java.lang.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 java.lang.String getScheme()
        Returns the scheme (lowercase), for example "https".
        Since:
        1.5

      • setScheme

        public final void setScheme​(java.lang.String scheme)
        Sets the scheme (lowercase), for example "https".
        Since:
        1.5

      • getHost

        public java.lang.String getHost()
        Returns the host, for example "www.google.com".
        Since:
        1.5

      • setHost

        public final void setHost​(java.lang.String host)
        Sets the host, for example "www.google.com".
        Since:
        1.5

      • getUserInfo

        public final java.lang.String getUserInfo()
        Returns the user info or null for none, for example "username:password".
        Since:
        1.15

      • setUserInfo

        public final void setUserInfo​(java.lang.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 java.util.List<java.lang.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​(java.util.List<java.lang.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 java.lang.String getFragment()
        Returns the fragment component or null for none.
        Since:
        1.5

      • setFragment

        public final void setFragment​(java.lang.String fragment)
        Sets the fragment component or null for none.
        Since:
        1.5

      • build

        public final java.lang.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 java.lang.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 java.lang.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 java.net.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 java.net.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 java.net.URL toURL​(java.lang.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 java.lang.Object getFirst​(java.lang.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 java.util.Collection<java.lang.Object> getAll​(java.lang.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 java.lang.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​(java.lang.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​(java.lang.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 java.util.List<java.lang.String> toPathParts​(java.lang.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 java.util.List<java.lang.String> toPathParts​(java.lang.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

      • appendRawPathFromParts

        private void appendRawPathFromParts​(java.lang.StringBuilder buf)

      • addQueryParams

        static void addQueryParams​(java.util.Set<java.util.Map.Entry<java.lang.String,​java.lang.Object>> entrySet,
                           java.lang.StringBuilder buf,
                           boolean verbatim)
        Adds query parameters from the provided entrySet into the buffer.

      • appendParam

        private static boolean appendParam​(boolean first,
                                   java.lang.StringBuilder buf,
                                   java.lang.String name,
                                   java.lang.Object value,
                                   boolean verbatim)

      • toURI

        private static java.net.URI toURI​(java.lang.String encodedUrl)
        Returns the URI for the given encoded URL.

        Any URISyntaxException is wrapped in an IllegalArgumentException.

        Parameters:
        encodedUrl - encoded URL
        Returns:
        URI

      • parseURL

        private static java.net.URL parseURL​(java.lang.String encodedUrl)
        Returns the URI for the given encoded URL.

        Any MalformedURLException is wrapped in an IllegalArgumentException.

        Parameters:
        encodedUrl - encoded URL
        Returns:
        URL