public interface HttpUrlBuilder

Builds a HTTP URL, safely.

This builder applies appropriate escaping of values to produce valid HTTP URLs. Typically used to build URLs for use with the HttpClient.


 import ratpack.core.http.HttpUrlBuilder;

 import static org.junit.jupiter.api.Assertions.assertEquals;

 public class Example {

   public static void main(String... args) {
     String url = HttpUrlBuilder.http()
       .host("foo.com")
       .path("a/b")
       .segment("c/%s", "d")
       .params("k1", "v1", "k2", "v2")
       .build()
       .toString();

     assertEquals("http://foo.com/a/b/c%2Fd?k1=v1&k2=v2", url);
   }
 }

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`static HttpUrlBuilder`	`base(URI uri)`	Create a new builder, with the initial state of the given URI.
`URI`	`build()`	Builds the URI based on this builder's current state.
`HttpUrlBuilder`	`encodedPath(String path)`	Appends the path to the URL, without escaping any meta characters.
`HttpUrlBuilder`	`fragment(String fragment)`	Add a fragment to the URL.
`HttpUrlBuilder`	`host(String host)`	Sets the host to the given value.
`static HttpUrlBuilder`	`http()`	Create a new HTTP URL builder.
`static HttpUrlBuilder`	`https()`	Create a new HTTPS URL builder.
`default HttpUrlBuilder`	`maybeEncodedPath(String path)`	Appends the path to the URL, without escaping any meta characters, unless it is empty or `null`.
`default HttpUrlBuilder`	`maybePath(String path)`	Appends the path to the URL, unless it is empty or `null`.
`HttpUrlBuilder`	`params(com.google.common.collect.Multimap<String,?> params)`	Add some query params to the URL.
`HttpUrlBuilder`	`params(String... params)`	Add some query params to the URL.
`HttpUrlBuilder`	`params(Map<String,?> params)`	Add some query params to the URL.
`default HttpUrlBuilder`	`params(Action<? super com.google.common.collect.ImmutableMultimap.Builder<String,Object>> params)`	Add some query params to the URL.
`HttpUrlBuilder`	`params(MultiValueMap<String,?> params)`	Add some query params to the URL.
`HttpUrlBuilder`	`path(String path)`	Appends the path to the URL.
`HttpUrlBuilder`	`port(int port)`	Sets the port to the given value.
`HttpUrlBuilder`	`secure()`	Sets the protocol to be HTTPS.
`HttpUrlBuilder`	`segment(String pathSegment, Object... args)`	Appends one path segment to the URL.

- Method Detail
  - base
```
static HttpUrlBuilder base(URI uri)
```
    Create a new builder, with the initial state of the given URI.
    The URI must be of the http or https protocol. If it is of any other, an IllegalArgumentException will be thrown.
    
    Parameters:
    
    uri - the uri to base the builder's state from
    
    Returns:
    
    a new url builder
  - http
```
static HttpUrlBuilder http()
```
    Create a new HTTP URL builder.
    The protocol is set to HTTP, host to localhost and port to the default for the protocol.
    
    Returns:
    
    a new url builder
  - https
```
static HttpUrlBuilder https()
```
    Create a new HTTPS URL builder.
    The protocol is set to HTTPS, host to localhost and port to the default for the protocol.
    
    Returns:
    
    a new url builder
  - secure
```
HttpUrlBuilder secure()
```
    Sets the protocol to be HTTPS.
    If the port has not been explicitly set, it will be changed to match the default for HTTPS.
    
    Returns:
    
    this
  - host
```
HttpUrlBuilder host(String host)
```
    Sets the host to the given value.
    
    Parameters:
    
    host - The host.
    
    Returns:
    
    this
  - port
```
HttpUrlBuilder port(int port)
```
    Sets the port to the given value.
    Any value less than 1 will throw an IllegalAccessException.
    
    Parameters:
    
    port - The port number.
    
    Returns:
    
    this
  - path
```
HttpUrlBuilder path(String path)
```
    Appends the path to the URL.
    The given value will may be a string such as "foo" or "foo/bar". In the case of the latter, the "/" character will not be URL escaped. All other meta characters that apply to the path component of a HTTP URL will be percent encoded.
    If the value to append should be exactly one path segment (i.e. "/" should be encoded), use segment(String, Object...).
    
    Parameters:
    
    path - the path to append
    
    Returns:
    
    this
  - maybePath
```
default HttpUrlBuilder maybePath(String path)
```
    Appends the path to the URL, unless it is empty or null.
    Has the same result as path(String), except that empty or null values are ignored.
    
    Parameters:
    
    path - the path to append
    
    Returns:
    
    this
    
    Since:
    
    1.2
  - encodedPath
```
HttpUrlBuilder encodedPath(String path)
```
    Appends the path to the URL, without escaping any meta characters.
    This can be used when it is guaranteed that the value has already been suitably encoded.
    If the value has not already been encoded, use path(String)
    
    Parameters:
    
    path - the path to append
    
    Returns:
    
    this
    
    Since:
    
    1.2
  - maybeEncodedPath
```
default HttpUrlBuilder maybeEncodedPath(String path)
```
    Appends the path to the URL, without escaping any meta characters, unless it is empty or null.
    Has the same result as encodedPath(String), except that empty or null values are ignored.
    
    Parameters:
    
    path - the path to append
    
    Returns:
    
    this
    
    Since:
    
    1.2
  - segment
```
HttpUrlBuilder segment(String pathSegment,
                       Object... args)
```
    Appends one path segment to the URL.
    This method first builds a string using String.format(String, Object...). The resultant string is percent encoded as is applicable for the path component of a HTTP URL.
    This method should generally be preferred over path(String) when incrementally building dynamic URLs, where values may container the HTTP URL path delimiter (i.e. "/").
    
    Parameters:
    
    pathSegment - the path segment format string
    
    args - token arguments
    
    Returns:
    
    this
  - params
```
HttpUrlBuilder params(String... params)
```
    Add some query params to the URL.
    Counting from zero, even numbered items are considered keys and odd numbered items are considered values. If param list ends in a key, a subsequent value of "" will be implied.
    
    Parameters:
    
    params - the param list
    
    Returns:
    
    this
  - params
```
default HttpUrlBuilder params(Action<? super com.google.common.collect.ImmutableMultimap.Builder<String,Object>> params)
                       throws Exception
```
    Add some query params to the URL.
    The given action will be supplied with a multi map builder, to which it can contribute query params.
    This method is additive with regard to the query params of this builder.
    
    Parameters:
    
    params - an action that contributes query params
    
    Returns:
    
    this
    
    Throws:
    
    Exception - any thrown by params
  - params
```
HttpUrlBuilder params(Map<String,?> params)
```
    Add some query params to the URL.
    The entries of the given map are added as query params to the URL being built.
    This method is additive with regard to the query params of this builder.
    
    Parameters:
    
    params - a map of query params to add to the URL being built
    
    Returns:
    
    this
  - params
```
HttpUrlBuilder params(com.google.common.collect.Multimap<String,?> params)
```
    Add some query params to the URL.
    The entries of the given multi map are added as query params to the URL being built.
    This method is additive with regard to the query params of this builder.
    
    Parameters:
    
    params - a multi map of query params to add to the URL being built
    
    Returns:
    
    this
  - params
```
HttpUrlBuilder params(MultiValueMap<String,?> params)
```
    Add some query params to the URL.
    The entries of the given multi value map are added as query params to the URL being built.
    This method is additive with regard to the query params of this builder.
    
    Parameters:
    
    params - a multi value map of query params to add to the URL being built
    
    Returns:
    
    this
    
    Since:
    
    1.2
  - fragment
```
HttpUrlBuilder fragment(String fragment)
```
    Add a fragment to the URL.
    
    Parameters:
    
    fragment - string of the fragment
    
    Returns:
    
    this
    
    Since:
    
    1.6
  - build
```
URI build()
```
    Builds the URI based on this builder's current state.
    
    Returns:
    
    a new HTTP/HTTPS URI

Interface HttpUrlBuilder

Method Summary

Method Detail

base

http

https

secure

host

port

path

maybePath

encodedPath

maybeEncodedPath

segment

params

params

params

params

params

fragment

build