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(java.net.URI uri)
Create a new builder, with the initial state of the given URI.
|
java.net.URI |
build()
Builds the URI based on this builder's current state.
|
HttpUrlBuilder |
encodedPath(java.lang.String path)
Appends the path to the URL, without escaping any meta characters.
|
HttpUrlBuilder |
fragment(java.lang.String fragment)
Add a fragment to the URL
|
HttpUrlBuilder |
host(java.lang.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(java.lang.String path)
Appends the path to the URL, without escaping any meta characters, unless it is empty or
null . |
default HttpUrlBuilder |
maybePath(java.lang.String path)
Appends the path to the URL, unless it is empty or
null . |
default HttpUrlBuilder |
params(Action<? super com.google.common.collect.ImmutableMultimap.Builder<java.lang.String,java.lang.Object>> params)
Add some query params to the URL.
|
HttpUrlBuilder |
params(java.util.Map<java.lang.String,?> params)
Add some query params to the URL.
|
HttpUrlBuilder |
params(com.google.common.collect.Multimap<java.lang.String,?> params)
Add some query params to the URL.
|
HttpUrlBuilder |
params(MultiValueMap<java.lang.String,?> params)
Add some query params to the URL.
|
HttpUrlBuilder |
params(java.lang.String... params)
Add some query params to the URL.
|
HttpUrlBuilder |
path(java.lang.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(java.lang.String pathSegment,
java.lang.Object... args)
Appends one path segment to the URL.
|
static HttpUrlBuilder base(java.net.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.
this
HttpUrlBuilder host(java.lang.String host)
host
- The host.this
HttpUrlBuilder port(int port)
Any value less than 1 will throw an IllegalAccessException
.
port
- The port number.this
HttpUrlBuilder path(java.lang.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 appendthis
default HttpUrlBuilder maybePath(java.lang.String path)
null
.
Has the same result as path(String)
, except that empty or null
values are ignored.
path
- the path to appendthis
HttpUrlBuilder encodedPath(java.lang.String path)
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)
path
- the path to appendthis
default HttpUrlBuilder maybeEncodedPath(java.lang.String path)
null
.
Has the same result as encodedPath(String)
, except that empty or null
values are ignored.
path
- the path to appendthis
HttpUrlBuilder segment(java.lang.String pathSegment, java.lang.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 argumentsthis
HttpUrlBuilder params(java.lang.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 listthis
default HttpUrlBuilder params(Action<? super com.google.common.collect.ImmutableMultimap.Builder<java.lang.String,java.lang.Object>> params) throws java.lang.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 paramsthis
java.lang.Exception
- any thrown by params
HttpUrlBuilder params(java.util.Map<java.lang.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 builtthis
HttpUrlBuilder params(com.google.common.collect.Multimap<java.lang.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 builtthis
HttpUrlBuilder params(MultiValueMap<java.lang.String,?> params)
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.
params
- a multi value map of query params to add to the URL being builtthis
HttpUrlBuilder fragment(java.lang.String fragment)
fragment
- string of the fragmentthis
java.net.URI build()