com.palominolabs.http.url

Class UrlBuilder

java.lang.Object

com.palominolabs.http.url.UrlBuilder

@NotThreadSafe
public final class UrlBuilder
extends java.lang.Object

Builder for urls with url-encoding applied to path, query param, etc. Escaping rules are from RFC 3986, RFC 1738 and the HTML 4 spec (http://www.w3.org/TR/html401/interact/forms.html#form-content-type). This means that this diverges from the canonical URI/URL rules for the sake of being what you want to actually make HTTP-useful URLs.

Method Summary

Modifier and Type	Method and Description
UrlBuilder	clearQuery() Clear the unstructured query and any query params.
UrlBuilder	forceTrailingSlash() Force the generated URL to have a trailing slash at the end of the path.
static UrlBuilder	forHost(java.lang.String scheme, java.lang.String host) Create a URL with an null port and UTF-8 encoding.
static UrlBuilder	forHost(java.lang.String scheme, java.lang.String host, int port)
UrlBuilder	fragment(java.lang.String fragment) Set the fragment.
static UrlBuilder	fromUrl(java.net.URL url) Calls fromUrl(URL, CharsetDecoder) with a UTF-8 CharsetDecoder.
static UrlBuilder	fromUrl(java.net.URL url, java.nio.charset.CharsetDecoder charsetDecoder) Create a UrlBuilder initialized with the contents of a URL.
UrlBuilder	matrixParam(java.lang.String name, java.lang.String value) Add a matrix param to the last added path segment.
UrlBuilder	pathSegment(java.lang.String segment) Add a path segment.
UrlBuilder	pathSegments(java.lang.String... segments) Add multiple path segments.
UrlBuilder	queryParam(java.lang.String name, java.lang.String value) Add an HTML query parameter.
java.lang.String	toUrlString() Encode the current builder state into a URL string.
UrlBuilder	unstructuredQuery(java.lang.String query) Set the complete query string of arbitrary structure.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

forHost

public static UrlBuilder forHost(@Nonnull
                                 java.lang.String scheme,
                                 @Nonnull
                                 java.lang.String host)

Create a URL with an null port and UTF-8 encoding.

Parameters:

scheme - scheme (e.g. http)

host - host in any of the valid syntaxes: reg-name (a dns name), ipv4 literal (1.2.3.4), ipv6 literal ([::1]), excluding IPvFuture since no one uses that in practice

Returns:

a url builder

See Also:

forHost(String scheme, String host, int port)

forHost

public static UrlBuilder forHost(@Nonnull
                                 java.lang.String scheme,
                                 @Nonnull
                                 java.lang.String host,
                                 int port)

Parameters:

scheme - scheme (e.g. http)

host - host in any of the valid syntaxes: reg-name ( a dns name), ipv4 literal (1.2.3.4), ipv6 literal ([::1]), excluding IPvFuture since no one uses that in practice

port - port

Returns:

a url builder

fromUrl

@Nonnull
public static UrlBuilder fromUrl(@Nonnull
                                          java.net.URL url)
                                   throws java.nio.charset.CharacterCodingException

Calls fromUrl(URL, CharsetDecoder) with a UTF-8 CharsetDecoder. The same semantics about the query string apply.

Parameters:

url - url to initialize builder with

Returns:

a UrlBuilder containing the host, path, etc. from the url

Throws:

java.nio.charset.CharacterCodingException - if char decoding fails

See Also:

fromUrl(URL, CharsetDecoder)

fromUrl

@Nonnull
public static UrlBuilder fromUrl(@Nonnull
                                          java.net.URL url,
                                          @Nonnull
                                          java.nio.charset.CharsetDecoder charsetDecoder)
                                   throws java.nio.charset.CharacterCodingException

Create a UrlBuilder initialized with the contents of a URL. The query string will be parsed into HTML4 query params if it can be separated into a &-separated sequence of key=value pairs. The sequence of query params can then be appended to by continuing to call queryParam(String, String). The concept of query params is only part of the HTML spec (and common HTTP usage), though, so it's perfectly legal to have a query string that is in some other form. To represent this case, if the aforementioned param-parsing attempt fails, the query string will be treated as just a monolithic, unstructured, string. In this case, calls to queryParam(String, String) on the resulting instance will throw IllegalStateException, and only calls to unstructuredQuery(String)}, which replaces the entire query string, are allowed.

Parameters:

url - url to initialize builder with

charsetDecoder - the decoder to decode encoded bytes with (except for reg names, which are always UTF-8)

Returns:

a UrlBuilder containing the host, path, etc. from the url

Throws:

java.nio.charset.CharacterCodingException - if decoding percent-encoded bytes fails and charsetDecoder is configured to report errors

See Also:

fromUrl(URL, CharsetDecoder)

pathSegment

@Nonnull
public UrlBuilder pathSegment(@Nonnull
                                       java.lang.String segment)

Add a path segment.

Parameters:

segment - a path segment

Returns:

this

pathSegments

@Nonnull
public UrlBuilder pathSegments(java.lang.String... segments)

Add multiple path segments. Equivalent to successive calls to pathSegment(String).

Parameters:

segments - path segments

Returns:

this

queryParam

@Nonnull
public UrlBuilder queryParam(@Nonnull
                                      java.lang.String name,
                                      @Nonnull
                                      java.lang.String value)

Add an HTML query parameter. Query parameters will be encoded in the order added. Using query strings to encode key=value pairs is not part of the URI/URL specification; it is specified by http://www.w3.org/TR/html401/interact/forms.html#form-content-type. If you use this method to build a query string, or created this builder from a url with a query string that can successfully be parsed into query param pairs, you cannot subsequently use unstructuredQuery(String). See fromUrl(URL, CharsetDecoder).

Parameters:

name - param name

value - param value

Returns:

this

unstructuredQuery

@Nonnull
public UrlBuilder unstructuredQuery(@Nonnull
                                             java.lang.String query)

Set the complete query string of arbitrary structure. This is useful when you want to specify a query string that is not of key=value format. If the query has previously been set via this method, subsequent calls will overwrite that query. If you use this method, or create a builder from a URL whose query is not parseable into query param pairs, you cannot subsequently use queryParam(String, String). See fromUrl(URL, CharsetDecoder).

Parameters:

query - Complete URI query, as specified by https://tools.ietf.org/html/rfc3986#section-3.4

Returns:

this

clearQuery

@Nonnull
public UrlBuilder clearQuery()

Clear the unstructured query and any query params. Since the query / query param situation is a little complicated, this method will let you remove all query information and start again from scratch. This may be useful when taking an existing url, parsing it into a builder, and then re-doing its query params, for instance.

Returns:

this

matrixParam

@Nonnull
public UrlBuilder matrixParam(@Nonnull
                                       java.lang.String name,
                                       @Nonnull
                                       java.lang.String value)

Add a matrix param to the last added path segment. If no segments have been added, the param will be added to the root. Matrix params will be encoded in the order added.

Parameters:

name - param name

value - param value

Returns:

this

fragment

@Nonnull
public UrlBuilder fragment(@Nonnull
                                    java.lang.String fragment)

Set the fragment.

Parameters:

fragment - fragment string

Returns:

this

forceTrailingSlash

@Nonnull
public UrlBuilder forceTrailingSlash()

Force the generated URL to have a trailing slash at the end of the path.

Returns:

this

toUrlString

public java.lang.String toUrlString()
                             throws java.nio.charset.CharacterCodingException

Encode the current builder state into a URL string.

Returns:

a well-formed URL string

Throws:

java.nio.charset.CharacterCodingException - if character encoding fails and the encoder is configured to report errors