public interface HttpUrlBuilder
This builder applies appropriate escaping of values to produce valid HTTP URLs.
Typically used to build URLs for use with the HttpClient
.
import ratpack.http.HttpUrlBuilder;
import static org.junit.Assert.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);
}
}
Modifier and Type | Method and 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 |
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 |
params(Action<? super ImmutableMultimap.Builder<String,Object>> params)
Add some query params to the URL.
|
HttpUrlBuilder |
params(Map<String,?> params)
Add some query params to the URL.
|
HttpUrlBuilder |
params(Multimap<String,?> params)
Add some query params to the URL.
|
HttpUrlBuilder |
params(String... params)
Add some query params to the URL.
|
HttpUrlBuilder |
path(String path)
Appends some 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.
|
static HttpUrlBuilder base(URI uri)
The URI must be of the http
or https
protocol.
If it is of any other, an IllegalArgumentException
will be thrown.
uri
- the uri to base the builder's state fromstatic HttpUrlBuilder http()
The protocol is set to HTTP, host to localhost
and port to the default for the protocol.
static HttpUrlBuilder https()
The protocol is set to HTTPS, host to localhost
and port to the default for the protocol.
HttpUrlBuilder secure()
If the port has not been explicitly set, it will be changed to match the default for HTTPS.
HttpUrlBuilder host(String host)
host
- The host.HttpUrlBuilder port(int port)
Any value less than 1 will throw an IllegalAccessException
.
port
- The port number.HttpUrlBuilder path(String path)
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...)
.
path
- The path to append.HttpUrlBuilder segment(String pathSegment, Object... args)
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. "/"
).
pathSegment
- the path segment format stringargs
- token argumentsHttpUrlBuilder params(String... params)
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.
params
- the param listdefault HttpUrlBuilder params(Action<? super ImmutableMultimap.Builder<String,Object>> params) throws Exception
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.
params
- an action that contributes query paramsException
- any thrown by params
HttpUrlBuilder params(Map<String,?> params)
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.
params
- a map of query params to add to the URL being builtHttpUrlBuilder params(Multimap<String,?> params)
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.
params
- a multi map of query params to add to the URL being builtURI build()