com.manydesigns.elements.servlet

Class UrlBuilder

java.lang.Object

com.manydesigns.elements.servlet.UrlBuilder

public class UrlBuilder
extends Object

Simple class that encapsulates the process of building up a URL from a path fragment and a zero or more parameters. Parameters can be single valued, array valued or collection valued. In the case of arrays and collections, each value in the array or collection will be added as a separate URL parameter (with the same name). The assembled URL can then be retrieved by calling toString().

While not immediately obvious, it is possible to add a single parameter with multiple values by invoking the addParameter() method that uses varargs, and supplying a Collection as the single parameter value to the method.

Author:

Tim Fennell

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	UrlBuilder(Charset charset, boolean isForPage) Sets the locale and sets the parameter separator based on the value of isForPage.
	UrlBuilder(Charset charset, String url, boolean isForPage) Constructs a UrlBuilder with the path to a resource.

Method Summary

Modifier and Type	Method and Description
UrlBuilder	addParameter(String name, Object... values) Appends one or more values of a parameter to the URL.
UrlBuilder	addParameters(Map<? extends Object,? extends Object> parameters) Appends one or more parameters to the URL.
protected String	build() Build and return the URL
protected String	format(Object value) Attempts to format an object.
String	getAnchor() Gets the anchor, if any, that will be appended to the URL.
String	getParameterSeparator() Returns the string that will be used to separate parameters in the query string.
UrlBuilder	setAnchor(String anchor) Sets the anchor, if any, that will be appended to the URL.
void	setParameterSeparator(String parameterSeparator) Sets the string that will be used to separate parameters.
String	toString() Returns the URL composed thus far as a String.

Methods inherited from class java.lang.Object

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

Constructor Detail

UrlBuilder

public UrlBuilder(Charset charset,
                  String url,
                  boolean isForPage)

Constructs a UrlBuilder with the path to a resource. Parameters can be added later using addParameter(). If the link is to be used in a page then the ampersand character usually used to separate parameters will be escaped using the XML entity for ampersand.

Parameters:

charset - the Charset to use when formatting URLs

url - the path part of the URL

isForPage - true if the URL is to be embedded in a page (e.g. in an anchor of img tag), false if for some other purpose.

UrlBuilder

protected UrlBuilder(Charset charset,
                     boolean isForPage)

Sets the locale and sets the parameter separator based on the value of isForPage.

Parameters:

charset - the Charset to use when formatting URLs

isForPage - true if the URL is to be embedded in a page (e.g. in an anchor of img tag), false if for some other purpose.

Method Detail

getParameterSeparator

public String getParameterSeparator()

Returns the string that will be used to separate parameters in the query string. Will usually be either '&' for query strings that will be embedded in HTML pages and '&' otherwise.

setParameterSeparator

public void setParameterSeparator(String parameterSeparator)

Sets the string that will be used to separate parameters. By default the values is a single ampersand character. If the URL is to be embedded in a page the value should be set to the XML ampersand entity.

addParameter

public UrlBuilder addParameter(String name,
                               Object... values)

Appends one or more values of a parameter to the URL. Checks to see if each value is null, and if so generates a parameter with no value. URL Encodes the parameter values to make sure that it is safe to insert into the URL.

If any parameter value passed is a Collection or an Array then this method is called recursively with the contents of the collection or array. As a result you can pass arbitrarily nested arrays and collections to this method and it will recurse through them adding all scalar values as parameters to the URL.

.

Parameters:

name - the name of the request parameter being added

values - one or more values for the parameter supplied

addParameters

public UrlBuilder addParameters(Map<? extends Object,? extends Object> parameters)

Appends one or more parameters to the URL. Various assumptions are made about the Map parameter. Firstly, that the keys are all either Strings, or objects that can be safely toString()'d to yield parameter names. Secondly that the values either toString() to form a single parameter value, or are arrays or collections that contain toString()'able objects.

Parameters:

parameters - a non-null Map as described above

getAnchor

public String getAnchor()

Gets the anchor, if any, that will be appended to the URL. E.g. if this method returns 'input' then the URL will be terminated with '#input' in order to instruct the browser to navigate to the HTML anchor called 'input' when accessing the URL.

Returns:

the anchor (if any) without the leading pound sign, or null

setAnchor

public UrlBuilder setAnchor(String anchor)

Sets the anchor, if any, that will be appended to the URL. E.g. if supplied with 'input' then the URL will be terminated with '#input' in order to instruct the browser to navigate to the HTML anchor called 'input' when accessing the URL.

Parameters:

anchor - the anchor with or without the leading pound sign, or null to disable

toString

public String toString()

Returns the URL composed thus far as a String. All paramter values will have been URL encoded and appended to the URL before returning it.

Overrides:

toString in class Object

format

protected String format(Object value)

Attempts to format an object. A null value will be formatted as an empty string.

Parameters:

value - the object to be formatted

Returns:

the formatted value

build

protected String build()

Build and return the URL