Package org.kiwiproject.net

Class KiwiUrls

  • public class KiwiUrls
extends Object
    Static utilities for creating URLs

    • Constructor Detail

      • KiwiUrls

        public KiwiUrls()

    • Method Detail

      • createUrl

        public static String createUrl​(String protocol,
                               String hostname,
                               int port)
        Create a well-formed URL (String) from the given protocol, hostname, and port.
        Parameters:
        protocol - the protocol
        hostname - the host name
        port - the port
        Returns:
        the URL as a String object

      • createUrlObject

        public static URL createUrlObject​(String protocol,
                                  String hostname,
                                  int port)
        Create a well-formed URL from the given protocol, hostname, and port.
        Parameters:
        protocol - the protocol
        hostname - the host name
        port - the port
        Returns:
        the URL as a URL object

      • createUrl

        public static String createUrl​(String protocol,
                               String hostname,
                               int port,
                               String path)
        Create a well-formed URL (String) from the given protocol, hostname, port and path.
        Parameters:
        protocol - the protocol
        hostname - the host name
        port - the port
        path - the path
        Returns:
        the URL as a String object

      • createUrlObject

        public static URL createUrlObject​(String protocol,
                                  String hostname,
                                  int port,
                                  String path)
        Create a well-formed URL from the given protocol, hostname, port, and path.
        Parameters:
        protocol - the protocol
        hostname - the host name
        port - the port
        path - the path
        Returns:
        the URL as a URL object

      • createUrl

        public static String createUrl​(String schemeHostPort,
                               String... pathComponents)
        Create a well-formed URL string from the given schemeHostPort and zero or more path components.
        Parameters:
        schemeHostPort - a string containing the scheme, host, and port parts, e.g. http://acme.com:8080
        pathComponents - zero or more path components to append
        Returns:
        the constructed URL as a String

      • createUrlObject

        public static URL createUrlObject​(String schemeHostPort,
                                  String... pathComponents)
        Create a well-formed URL from the given schemeHostPort and zero or more path components.
        Parameters:
        schemeHostPort - a string containing the scheme, host, and port parts, e.g. http://acme.com:8080
        pathComponents - zero or more path components to append
        Returns:
        the constructed URL as a URL

      • prependLeadingSlash

        public static String prependLeadingSlash​(String path)
        Trims path and, if a leading slash is not present, adds it.
        Parameters:
        path - a path
        Returns:
        a new String with a leading slash

      • createHttpUrl

        public static String createHttpUrl​(String hostname,
                                   int port)
        Create a well-formed HTTP URL (String) from the given hostname and port.
        Parameters:
        hostname - the host name
        port - the port
        Returns:
        a URL as a String

      • createHttpUrlObject

        public static URL createHttpUrlObject​(String hostname,
                                      int port)
        Create a well-formed HTTP URL from the given hostname and port.
        Parameters:
        hostname - the host name
        port - the port
        Returns:
        a URL as a URL

      • createHttpUrl

        public static String createHttpUrl​(String hostname,
                                   int port,
                                   String path)
        Create a well-formed HTTP URL (String) from the given hostname, port and path.
        Parameters:
        hostname - the host name
        port - the port
        path - the path
        Returns:
        a URL as a String

      • createHttpUrlObject

        public static URL createHttpUrlObject​(String hostname,
                                      int port,
                                      String path)
        Create a well-formed HTTP URL from the given hostname, port and path.
        Parameters:
        hostname - the host name
        port - the port
        path - the path
        Returns:
        a URL as a URL

      • createHttpsUrl

        public static String createHttpsUrl​(String hostname,
                                    int port)
        Create a well-formed HTTPS URL (String) from the given hostname and port.
        Parameters:
        hostname - the host name
        port - the port
        Returns:
        a URL as a String

      • createHttpsUrlObject

        public static URL createHttpsUrlObject​(String hostname,
                                       int port)
        Create a well-formed HTTPS URL from the given hostname and port.
        Parameters:
        hostname - the host name
        port - the port
        Returns:
        a URL as a URL

      • createHttpsUrl

        public static String createHttpsUrl​(String hostname,
                                    int port,
                                    String path)
        Create a well-formed HTTPS URL (String) from the given hostname, port and path.
        Parameters:
        hostname - the host name
        port - the port
        path - the path
        Returns:
        a URL as a String

      • createHttpsUrlObject

        public static URL createHttpsUrlObject​(String hostname,
                                       int port,
                                       String path)
        Create a well-formed HTTPS URL from the given hostname, port and path.
        Parameters:
        hostname - the host name
        port - the port
        path - the path
        Returns:
        a URL as a URL

      • extractAllFrom

        public static KiwiUrls.Components extractAllFrom​(String url)
        Extract all the relevant sections from the given uri.

        As an example, if given "https://news.bbc.co.uk:8080/a-news-article" this would return the following:

        • scheme = "https"
        • subDomainName = "news"
        • domainName = "bbc.co.uk"
        • canonicalName = "news.bbc.co.uk"
        • port = 8080
        • path = "a-news-article"
        Parameters:
        url - the URL to analyze
        Returns:
        the KiwiUrls.Components found or an empty KiwiUrls.Components object if the URL was invalid
        Implementation Note:
        This method does not check if the URL is valid or not.

      • stripTrailingSlash

        public static String stripTrailingSlash​(String url)
        Trims url and, if present, strips the trailing slash
        Parameters:
        url - the URL
        Returns:
        the URL minus any trailing slash

      • stripTrailingSlashes

        public static List<String> stripTrailingSlashes​(List<String> urls)
        Trims each URL in urls and strips any trailing slashes
        Parameters:
        urls - a list of URLs
        Returns:
        a list of URLs matching the input URLs minus any trailing slash

      • extractCanonicalNameFrom

        public static Optional<String> extractCanonicalNameFrom​(String url)
        Extracts the canonical server name from a given URL.

        As an example, if given "https://news.bbc.co.uk:8080/a-news-article" this method would return "news.bbc.co.uk"

        Parameters:
        url - the URL to evaluate
        Returns:
        an Optional containing the canonical server name or Optional.empty() if it could not be found.
        Implementation Note:
        This method does not check if the URL is valid or not. Also, if you will need to extract more than one section of the URL, you should instead use extractAllFrom(String).

      • extractDomainNameFrom

        public static Optional<String> extractDomainNameFrom​(String url)
        Extracts the server's domain name from a given URL.

        As an example, if given "https://news.bbc.co.uk:8080/a-news-article" this method would return "bbc.co.uk"

        Parameters:
        url - the URL to evaluate
        Returns:
        an Optional containing the server's domain name or Optional.empty() if it could not be found.
        Implementation Note:
        This method does not check if the URL is valid or not. Also, if you will need to extract more than one section of the URL, you should instead use extractAllFrom(String).

      • extractPathFrom

        public static Optional<String> extractPathFrom​(String url)
        Extracts the path from a given URL.

        As an example, if given "https://news.bbc.co.uk:8080/a-news-article" this method would return "a-news-article"

        Parameters:
        url - the URL to evaluate
        Returns:
        an Optional containing the path or Optional.empty() if it could not be found.
        Implementation Note:
        This method does not check if the URL is valid or not. Also, if you will need to extract more than one section of the URL, you should instead use extractAllFrom(String).

      • extractPortFrom

        public static OptionalInt extractPortFrom​(String url)
        Extracts the port from a given URL.

        As an example, if given "https://news.bbc.co.uk:8080/a-news-article" this method would return "8080" (represented by an int).

        Parameters:
        url - the URL to evaluate
        Returns:
        an Optional containing the port or Optional.empty() if it could not be found.
        Implementation Note:
        This method does not check if the URL is valid or not. Also, if you will need to extract more than one section of the URL, you should instead use extractAllFrom(String).

      • extractSchemeFrom

        public static Optional<String> extractSchemeFrom​(String url)
        Extracts the scheme from a given URL.

        As an example, if given "https://news.bbc.co.uk:8080/a-news-article" this method would return "https"

        Parameters:
        url - the URL to evaluate
        Returns:
        an Optional containing the canonical server name or Optional.empty() if it could not be found.
        Implementation Note:
        This method does not check if the URL is valid or not. Also, if you will need to extract more than one section of the URL, you should instead use extractAllFrom(String).

      • extractSubDomainNameFrom

        public static Optional<String> extractSubDomainNameFrom​(String url)
        Extracts the simple server name from a given URL.

        As an example, if given "https://news.bbc.co.uk:8080/a-news-article" this method would return "news"

        Parameters:
        url - the URL to evaluate
        Returns:
        an Optional containing the simple server name or Optional.empty() if it could not be found.
        Implementation Note:
        This method does not check if the URL is valid or not. Also, if you will need to extract more than one section of the URL, you should instead use extractAllFrom(String).

      • replaceDomainsIn

        public static String replaceDomainsIn​(String commaDelimitedUrls,
                                      String replacementDomain)
        Searches the commaDelimitedUrls for its domains, and if found, replaces all entries with replacementDomain. The commaDelimitedUrls can be a standalone URL.
        Parameters:
        commaDelimitedUrls - the comma delimited URLs to search
        replacementDomain - the domain to replace if found
        Returns:
        the updated comma-delimited URLs if a domain is found, otherwise commaDelimitedUrls unchanged
        Implementation Note:
        This method assumes that the domains are the same for all URLs in the commaDelimitedUrls; it only checks the first URL to obtain the domain.

      • queryStringToMap

        public static Map<String,​String> queryStringToMap​(String queryString)
        Converts a query string (comprised of key/value pairs separated by '&' characters) into a Map whose keys are the parameter names and values are the parameter values.

        Note specifically that this method does not decode the query string parameters. It splits on literal & characters to obtain the key/value pairs and then on the literal = to get the name and value of each pair. If a parameter doesn't contain any value, its values is set to an empty string. For example, in the query string ?sorted&sortProp=, both sorted and sortProp will have an empty string as their value in the returned map.

        Also note that if a parameter has multiple values, only the first one is returned, e.g. the value of "topping" in the query string topping=pepperoni&topping=banana+pepper&topping=sausage will always be "pepperoni".

        Parameters:
        queryString - the query string to create the map from
        Returns:
        a map of the query params
        See Also:
        toQueryString(Map) for the inverse operation

      • queryStringToMultimap

        public static com.google.common.collect.Multimap<String,​String> queryStringToMultimap​(String queryString)
        Converts a query string into a Guava Multimap whose keys are the parameter names and values are lists containing one or more values. Use this method (or queryStringToMultivaluedMap(String)) when parameters can have multiple values.

        Like queryStringToMap(String) this method does not decode the query parameters, and it properly handles parameters with no value.

        If a parameter has multiple values, they are grouped under the parameter name in the Multimap. For example, given the query string topping=pepperoni&topping=banana+pepper&topping=sausage, calling multimap.get("topping") will return a Collection of strings containing "pepperoni", "banana+pepper", and "sausage".

        Parameters:
        queryString - the query string to create the Multimap from
        Returns:
        a Multimap of the query parameters
        See Also:
        queryStringToMultivaluedMap(String)

      • queryStringToMultivaluedMap

        public static Map<String,​List<String>> queryStringToMultivaluedMap​(String queryString)
        Converts a query string into a Map whose keys are the parameter names and values are List containing one or more values. Use this (or queryStringToMultimap(String) when parameters can have multiple values.

        Like queryStringToMap(String) this method does not decode the query parameters, and it properly handles parameters with no value.

        If a parameter has multiple values, they are grouped under the parameter name. For example, given the query string topping=onion&topping=mushroom&topping=extra+cheese&topping=fresh+basil, calling map.get("topping") will return a List of strings containing "onion", "mushroom", "extra+cheese", and "fresh+basil".

        Parameters:
        queryString - the query string to create the Multimap from
        Returns:
        a Map of the query parameters
        See Also:
        queryStringToMultimap(String)

      • toQueryString

        public static <V> String toQueryString​(Map<String,​V> parameters)
        Converts a Map containing String keys and V values into one (potentially long) string of key/value parameters (each key/value parameter is separated by an '=' character), with each parameter pair separated by an '&' character.

        Note specifically that this method does not URL encode the parameters.

        Type Parameters:
        V - the type of values in the parameters map
        Parameters:
        parameters - the map of the parameters to create the query string from
        Returns:
        a concatenated query string
        See Also:
        queryStringToMap(String) for the inverse operation

      • toEncodedQueryString

        public static <V> String toEncodedQueryString​(Map<String,​V> parameters)
        Converts a Map containing String keys and V values into a URL-encoded query string. Encodes the query string using StandardCharsets.UTF_8 as the character set.
        Type Parameters:
        V - the type of values in the parameters map
        Parameters:
        parameters - the map of the parameters to create the query string from
        Returns:
        a URL-encoded query string
        See Also:
        URLEncoder.encode(String, Charset)

      • toEncodedQueryString

        public static <V> String toEncodedQueryString​(Map<String,​V> parameters,
                                              String charsetName)
        Converts a Map containing String keys and V values into a URL-encoded query string. Encodes the query string using the given charsetName, which must be a valid charsetName name. The Charset.forName(String) method is used to convert the given charsetName name to a Charset; see that class for the exceptions it throws when given illegal arguments.
        Type Parameters:
        V - the type of values in the parameters map
        Parameters:
        parameters - the map of the parameters to create the query string from
        charsetName - the name of the Charset (must be valid via Charset.forName(String))
        Returns:
        a URL-encoded query string
        See Also:
        Charset.forName(String), URLEncoder.encode(String, Charset)

      • toEncodedQueryString

        public static <V> String toEncodedQueryString​(Map<String,​V> parameters,
                                              Charset charset)
        Converts a Map containing String keys and V values into a URL-encoded query string. Encodes the query string using the given Charset.
        Type Parameters:
        V - the type of values in the parameters map
        Parameters:
        parameters - the map of the parameters to create the query string from
        charset - the Charset to use when encoding the parameters
        Returns:
        a URL-encoded query string
        See Also:
        URLEncoder.encode(String, Charset)