net.sourceforge.stripes.util
Class UrlBuilder

java.lang.Object
  extended by net.sourceforge.stripes.util.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.

Since:
Stripes 1.1.2
Author:
Tim Fennell

Constructor Summary
protected UrlBuilder(Locale locale, boolean isForPage)
          Sets the locale and sets the parameter separator based on the value of isForPage.
  UrlBuilder(Locale locale, Class<? extends ActionBean> beanType, boolean isForPage)
          Constructs a UrlBuilder that references an ActionBean.
  UrlBuilder(Locale locale, String url, boolean isForPage)
          Constructs a UrlBuilder with the path to a resource.
  UrlBuilder(String url, boolean isForPage)
          Deprecated. As of Stripes 1.5, this constructor has been replaced by UrlBuilder(Locale, String, boolean).
 
Method Summary
 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 using an appropriate Formatter.
 String getAnchor()
          Gets the anchor, if any, that will be appended to the URL.
protected  String getBaseURL(String baseUrl, Collection<net.sourceforge.stripes.util.UrlBuilder.Parameter> parameters)
          Get the base URL (without a query string).
 String getEvent()
          Get the name of the event to be executed by this URL.
protected  Formatter getFormatter(Object value)
          Tries to get a formatter for the given value using the FormatterFactory.
 String getParameterSeparator()
          Returns the string that will be used to separate parameters in the query string.
protected  Map<String,ValidationMetadata> getValidationMetadata()
          Get a map of property names to ValidationMetadata for the ActionBean class bound to the URL being built.
 UrlBuilder setAnchor(String anchor)
          Sets the anchor, if any, that will be appended to the URL.
 UrlBuilder setEvent(String event)
          Set the name of the event to be executed by this 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

@Deprecated
public UrlBuilder(String url,
                             boolean isForPage)
Deprecated. As of Stripes 1.5, this constructor has been replaced by UrlBuilder(Locale, String, boolean).

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:
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

public UrlBuilder(Locale locale,
                  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:
locale - the locale to use when formatting parameters with a Formatter
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

public UrlBuilder(Locale locale,
                  Class<? extends ActionBean> beanType,
                  boolean isForPage)
Constructs a UrlBuilder that references an ActionBean. 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:
locale - the locale to use when formatting parameters with a Formatter
beanType - ActionBean class for which the URL will be built
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(Locale locale,
                     boolean isForPage)
Sets the locale and sets the parameter separator based on the value of isForPage.

Parameters:
locale - the locale to use when formatting parameters with a Formatter
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

getEvent

public String getEvent()
Get the name of the event to be executed by this URL.


setEvent

public UrlBuilder setEvent(String event)
Set the name of the event to be executed by this URL. A default event name can be defined for an ActionBean using either DefaultHandler or by assigning a default value to the $event parameter in a clean URL. If event is null then the default event name will be ignored and no event parameter will be added to the URL.

Parameters:
event - the event name

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 using an appropriate Formatter. If no formatter is available for the object, then this method will call toString() on the object. A null value will be formatted as an empty string.

Parameters:
value - the object to be formatted
Returns:
the formatted value

getFormatter

protected Formatter getFormatter(Object value)
Tries to get a formatter for the given value using the FormatterFactory. Returns null if there is no Configuration or FormatterFactory available (e.g. in a test environment) or if there is no Formatter configured for the value's type.

Parameters:
value - the object to be formatted
Returns:
a formatter, if one can be found; null otherwise

getValidationMetadata

protected Map<String,ValidationMetadata> getValidationMetadata()
Get a map of property names to ValidationMetadata for the ActionBean class bound to the URL being built. If the URL does not point to an ActionBean class or no validation metadata exists for the ActionBean class then an empty map will be returned.

Returns:
a map of ActionBean property names to their validation metadata
See Also:
ValidationMetadataProvider.getValidationMetadata(Class)

build

protected String build()
Build and return the URL


getBaseURL

protected String getBaseURL(String baseUrl,
                            Collection<net.sourceforge.stripes.util.UrlBuilder.Parameter> parameters)
Get the base URL (without a query string). If a UrlBinding exists for the URL or ActionBean type that was passed into the constructor, then this method will return the base URL after appending any URI parameters that have been added with a call to addParameter(String, Object[]) or addParameters(Map). Otherwise, it returns the original base URL.

Parameters:
baseUrl - The base URL to start with. In many cases, this value will be returned unchanged.
parameters - The query parameters. Any parameters that should not be appended to the query string by build() (e.g., because they are embedded in the URL) should be removed from the collection before this method returns.
Returns:
the base URL, without a query string
See Also:
UrlBuilder(Locale, Class, boolean), UrlBuilder(Locale, String, boolean)


? Copyright 2005-2006, Stripes Development Team.