net.sf.kdgcommons.html

Class URLBuilder

java.lang.Object

net.sf.kdgcommons.html.URLBuilder

public final class URLBuilder
extends Object

A utility class for building HTML URLs that allows progressive build-out of the URL and deals with encoding and formatting.

Although this class supports various types of URLs, it exists primarily to build HTTP and HTTPS URLs, and to be convertable to a java.net.URL. To that end, it assumes that URLs will follow the format protocol://host:port/path?query, where :port is optional.

If you omit the hostname, this class will build "relative" URLs, which are useful for inserting into href attributes. If you omit the path, it will use the default path "/".

All public methods follow the Builder pattern, so that you can string calls together.

Constructor Summary

Constructors

Constructor and Description
URLBuilder() Creates a builder where the path is "/".
URLBuilder(String path) Creates a builder that specifies an explicit path (which may or may not contain hostname and protocol components).
URLBuilder(String protocol, String host, String path) Creates a builder from basic components.

Method Summary

Modifier and Type	Method and Description
URLBuilder	appendOptionalParameter(String name, String value) Appends a query parameter, escaping as needed.
URLBuilder	appendParameter(String name, String value) Appends a query parameter, escaping as needed.
URLBuilder	appendPath(String pathElement) Appends an element to the path, escaping any reserved characters.
String	toString() Returns the string value of this URL.

Methods inherited from class java.lang.Object

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

Constructor Detail

URLBuilder

public URLBuilder()

Creates a builder where the path is "/". Not terribly useful, except for testing.

URLBuilder

public URLBuilder(String path)

Creates a builder that specifies an explicit path (which may or may not contain hostname and protocol components). A blank path will be replaced by "/", but otherwise the passed path is unchanged.

URLBuilder

public URLBuilder(String protocol,
                  String host,
                  String path)

Creates a builder from basic components.

Parameters:

protocol - The protocol, sans colon and separator (eg, "http", not "http://"). If null, will default to HTTP.

host - The hostname, with optional port. May be null, to create local URLs (in which case the protocol will be omitted).

path - The context path. This is considered an absolute path from the host's root, so will be prepended with a '/' if it is not already; null or empty paths will be replaced by "/". Since this path may contain multiple slash-separated components, it will not be URL-escaped; see appendPath(java.lang.String) if you need to escape path components.

Method Detail

appendPath

public URLBuilder appendPath(String pathElement)

Appends an element to the path, escaping any reserved characters.

appendParameter

public URLBuilder appendParameter(String name,
                                  String value)

Appends a query parameter, escaping as needed. A null value is treated as an empty string (so will appear as name=).

appendOptionalParameter

public URLBuilder appendOptionalParameter(String name,
                                          String value)

Appends a query parameter, escaping as needed. If passed value is null, does not append anything.

toString

public String toString()

Returns the string value of this URL. This method will rebuild the URL on each call, reflecting the state of the builder as-of the call.

Overrides:

toString in class Object