io.mikael.urlbuilder

Class UrlBuilder

java.lang.Object

io.mikael.urlbuilder.UrlBuilder

public final class UrlBuilder
extends Object

Build and manipulate URLs easily. Instances of this class are immutable after their constructor returns. URL: http://www.ietf.org/rfc/rfc1738.txt URI: http://tools.ietf.org/html/rfc3986

Author:

Mikael Gueck gumi@iki.fi

Field Summary

Fields

Modifier and Type	Field and Description
String	fragment
String	hostName
String	path
Integer	port
Map<String,List<String>>	queryParameters
String	scheme
String	userInfo

Method Summary

Modifier and Type	Method and Description
UrlBuilder	addParameter(String key, String value) Adds a query parameter.
static UrlBuilder	empty() Construct an empty builder instance.
UrlBuilder	encodeAs(Charset charset) When percent-escaping the StringBuilder's output, use this character set.
UrlBuilder	encodeAs(String charsetName) When percent-escaping the StringBuilder's output, use this character set.
static UrlBuilder	fromString(String url) Construct a UrlBuilder from a full or partial URL string.
static UrlBuilder	fromString(String url, Charset inputEncoding) Construct a UrlBuilder from a full or partial URL string.
static UrlBuilder	fromString(String url, Decoder decoder) Construct a UrlBuilder from a full or partial URL string.
static UrlBuilder	fromString(String url, String inputEncoding) Construct a UrlBuilder from a full or partial URL string.
static UrlBuilder	fromUri(URI uri) Construct a UrlBuilder from a URI.
static UrlBuilder	fromUrl(URL url) Construct a UrlBuilder from a URL.
protected static UrlBuilder	of(Decoder decoder, Encoder encoder, String scheme, String userInfo, String hostName, Integer port, String path, UrlParameterMultimap queryParameters, String fragment)
UrlBuilder	removeParameter(String key, String value) Removes a query parameter for a key and value.
UrlBuilder	removeParameters(String key) Removes all query parameters with this key.
UrlBuilder	setParameter(String key, String value) Replaces a query parameter.
String	toString()
void	toString(Appendable out)
URI	toUri()
URI	toUriWithException()
URL	toUrl()
URL	toUrlWithException()
UrlBuilder	withDecoder(Decoder decoder)
UrlBuilder	withEncoder(Encoder encoder)
UrlBuilder	withFragment(String fragment) Sets the fragment/anchor.
UrlBuilder	withHost(String name) Set the host name.
UrlBuilder	withParameters(UrlParameterMultimap parameters) Sets the parameters.
UrlBuilder	withPath(String path) Set the decoded, non-url-encoded path.
UrlBuilder	withPath(String path, Charset encoding) Decodes and sets the path from a url-encoded string.
UrlBuilder	withPath(String path, String encoding) Decodes and sets the path from a url-encoded string.
UrlBuilder	withPort(Integer port) Set the port.
UrlBuilder	withQuery(String query) Decodes the input string, and sets the query string.
UrlBuilder	withQuery(String query, Charset encoding) Decodes the input string, and sets the query string.
UrlBuilder	withQuery(UrlParameterMultimap query) Sets the query parameters to a deep copy of the input parameter.
UrlBuilder	withScheme(String scheme) Set the protocol (or scheme), such as "http" or "https".
UrlBuilder	withUserInfo(String userInfo) Set the userInfo.

Methods inherited from class java.lang.Object

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

Field Detail

scheme

public final String scheme

userInfo

public final String userInfo

hostName

public final String hostName

port

public final Integer port

path

public final String path

queryParameters

public final Map<String,List<String>> queryParameters

fragment

public final String fragment

Method Detail

empty

public static UrlBuilder empty()

Construct an empty builder instance.

of

protected static UrlBuilder of(Decoder decoder,
                               Encoder encoder,
                               String scheme,
                               String userInfo,
                               String hostName,
                               Integer port,
                               String path,
                               UrlParameterMultimap queryParameters,
                               String fragment)

fromString

public static UrlBuilder fromString(String url)

Construct a UrlBuilder from a full or partial URL string. Assume that the query paremeters were percent-encoded, as the standard suggests, as UTF-8.

fromString

public static UrlBuilder fromString(String url,
                                    String inputEncoding)

Construct a UrlBuilder from a full or partial URL string. When percent-decoding the query parameters, assume that they were encoded with inputEncoding.

Throws:

NumberFormatException - if the input contains a invalid percent-encoding sequence (%ax) or a non-numeric port

fromString

public static UrlBuilder fromString(String url,
                                    Charset inputEncoding)

Construct a UrlBuilder from a full or partial URL string. When percent-decoding the query parameters, assume that they were encoded with inputEncoding.

Throws:

NumberFormatException - if the input contains a invalid percent-encoding sequence (%ax) or a non-numeric port

fromString

public static UrlBuilder fromString(String url,
                                    Decoder decoder)

Construct a UrlBuilder from a full or partial URL string. When percent-decoding the query parameters, use the supplied decoder.

Throws:

NumberFormatException - if the input contains a invalid percent-encoding sequence (%ax) or a non-numeric port

fromUri

public static UrlBuilder fromUri(URI uri)

Construct a UrlBuilder from a URI.

fromUrl

public static UrlBuilder fromUrl(URL url)

Construct a UrlBuilder from a URL.

Throws:

NumberFormatException - if the input contains a invalid percent-encoding sequence (%ax) or a non-numeric port

toString

public void toString(Appendable out)
              throws IOException

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object

toUriWithException

public URI toUriWithException()
                       throws URISyntaxException

Throws:

URISyntaxException

toUri

public URI toUri()
          throws RuntimeURISyntaxException

Throws:

RuntimeURISyntaxException

toUrlWithException

public URL toUrlWithException()
                       throws MalformedURLException

Throws:

MalformedURLException

toUrl

public URL toUrl()
          throws RuntimeMalformedURLException

Throws:

RuntimeMalformedURLException

withDecoder

public UrlBuilder withDecoder(Decoder decoder)

withEncoder

public UrlBuilder withEncoder(Encoder encoder)

encodeAs

public UrlBuilder encodeAs(Charset charset)

When percent-escaping the StringBuilder's output, use this character set.

encodeAs

public UrlBuilder encodeAs(String charsetName)

When percent-escaping the StringBuilder's output, use this character set.

withScheme

public UrlBuilder withScheme(String scheme)

Set the protocol (or scheme), such as "http" or "https".

withUserInfo

public UrlBuilder withUserInfo(String userInfo)

Set the userInfo. It's usually either of the form "username" or "username:password".

withHost

public UrlBuilder withHost(String name)

Set the host name. Accepts internationalized host names, and decodes them.

withPort

public UrlBuilder withPort(Integer port)

Set the port. Use null to denote the protocol's default port.

withPath

public UrlBuilder withPath(String path)

Set the decoded, non-url-encoded path.

withPath

public UrlBuilder withPath(String path,
                           Charset encoding)

Decodes and sets the path from a url-encoded string.

withPath

public UrlBuilder withPath(String path,
                           String encoding)

Decodes and sets the path from a url-encoded string.

withQuery

public UrlBuilder withQuery(UrlParameterMultimap query)

Sets the query parameters to a deep copy of the input parameter. Use null to remove the whole section.

withQuery

public UrlBuilder withQuery(String query)

Decodes the input string, and sets the query string.

withQuery

public UrlBuilder withQuery(String query,
                            Charset encoding)

Decodes the input string, and sets the query string.

withParameters

public UrlBuilder withParameters(UrlParameterMultimap parameters)

Sets the parameters.

addParameter

public UrlBuilder addParameter(String key,
                               String value)

Adds a query parameter. New parameters are added to the end of the query string.

setParameter

public UrlBuilder setParameter(String key,
                               String value)

Replaces a query parameter. Existing parameters with this name are removed, and the new one added to the end of the query string.

removeParameter

public UrlBuilder removeParameter(String key,
                                  String value)

Removes a query parameter for a key and value.

removeParameters

public UrlBuilder removeParameters(String key)

Removes all query parameters with this key.

withFragment

public UrlBuilder withFragment(String fragment)

Sets the fragment/anchor.