Package org.kiwiproject.net

Class KiwiUrls

java.lang.Object
org.kiwiproject.net.KiwiUrls
public final class KiwiUrls extends Object
Static utilities for creating URLs

  • Field Details

  • Method Details

    • 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

    • createUrlObject

      public static URL createUrlObject(String urlSpec)
      Wrapper around URL's constructor which throws a checked MalformedURLException. This instead assumes the given urlSpec is valid and throws UncheckedMalformedURLException in case it is actually not valid.
      Parameters:
      urlSpec - the String to parse as a URL
      Returns:
      a new URL instance
      Throws:
      UncheckedMalformedURLException - that wraps a MalformedURLException if any error occurs

    • createUrl

      public static String createUrl(String schemeHostPort, String... pathParts)
      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
      pathParts - zero or more path parts to append
      Returns:
      the constructed URL as a String

    • createUrlObject

      public static URL createUrlObject(String schemeHostPort, String... pathParts)
      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
      pathParts - zero or more path parts to append
      Returns:
      the constructed URL as a URL

    • toURL

      public static URL toURL(URI uri)
      Tries to convert the given uri into a URL, throwing an unchecked exception if the conversion fails. The thrown unchecked exception wraps the original checked MalformedURLException.
      Parameters:
      uri - the URI to convert
      Returns:
      a URL instance
      Throws:
      UncheckedMalformedURLException - if conversion from URI to URL fails
      See Also:

    • 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

    • stripLeadingSlash

      public static String stripLeadingSlash(String path)
      Trims path and, if a leading slash is present, removes it.
      Parameters:
      path - a path
      Returns:
      a new String without 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
      Throws:
      IllegalArgumentException - if the port in the URL is not a number
      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.
      Throws:
      IllegalArgumentException - if the port is not a number
      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 (composed 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 value 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:

    • 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

      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:

    • 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, and each parameter pair is separated by an & character.

      For example, page=0&pageSize=25&sort1=last&sortDir1=desc&sort2=first&sortDir2=asc.

      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:

    • 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:

    • 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:

    • 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: