com.endeca.util

Class UrlBuilder

java.lang.Object

com.endeca.util.UrlBuilder

public class UrlBuilder
extends java.lang.Object

A generic toolkit for manipulating and generating URL query strings. UrlBuilder takes a query string in a constructor as the base query to work with. The toString method called immediately after the constructor will return the original input URL. The remove and add parameter methods are evaluated in order. This means that a remove parameter after an add parameter will delete the parameter you just added.

This toolkit attempts to preserve whatever input URL parameters are input to the system as long as they follow the structure of an ampersand (&) delimited, x-www-form-urlencoded parameter value pairs. In the case of multiple parameters with the same name, the multiple pairs will be preserved on output; however, a remove or add with the same name will remove or overwrite all keys with that name. An append, on the other hand, will preserve the previous parameters. An append adds parameters without affecting the previous parameter list. This class is taken somewhat wholesale from the old MDEX6 API jar (endeca-navigation.jar), renamed (from UrlBuilder), and fixed to use generics and java.net.UrlEncoder instead of the home grown encoder it used to use.

Constructor Summary

Constructors

Constructor and Description
UrlBuilder(java.lang.String queryString, java.lang.String encoding) Constructor where the start URL will be the one specified in this constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	addParam(java.lang.String key, java.lang.String value) Manipulates the resultant URL by adding this key/value pair.
void	addParams(java.util.Collection<java.lang.String> c) Bulk add of parameter key/value pairs.
void	appendParam(java.lang.String key, java.lang.String value) Manipulates the resultant URL by adding a key/value pair.
void	appendParams(java.util.Collection<java.lang.String> c) Bulk append of parameter key/value pairs.
java.lang.String	getBaseUrl()
void	removeParam(java.lang.String key) Removes any key/value parameter pair from the outputted URL.
void	removeParams(java.util.Collection<java.lang.String> c) Removes any key/value parameter with the keys specified in the collection.
void	setBaseUrl(java.lang.String baseUrl)
java.lang.String	toString() The output method on this class.

Methods inherited from class java.lang.Object

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

Constructor Detail

UrlBuilder

public UrlBuilder(java.lang.String queryString,
          java.lang.String encoding)

Constructor where the start URL will be the one specified in this constructor. This URL is the base with which this UrlBuilder manipulates. The URL form is of a URL query string, which means everything in a URL after the ? character and of the form where the query is made up of key/value pairs delimited by the & character and each pair is delimited by the = character and the keys and values are x-www-form-urlencoded.

Parameters:

queryString - the base query string with which this class manipulates.

encoding - the character encoding in which the URL is encoded.

Method Detail

appendParam

public void appendParam(java.lang.String key,
               java.lang.String value)

Manipulates the resultant URL by adding a key/value pair. This method will NOT overwrite existing parameters with the same key nor any other parameter that was previously added by this method with the same key. In addition, it is assumed that value is decoded and will encode the value as x-www-form-urlencoded on output. Values that are null or equal to "" will be skipped so that this method can be called without having to check if the value is present.

Parameters:

key - key name of the pair to be added.

value - the value to be added to the output URL where the value is decoded.

appendParams

public void appendParams(java.util.Collection<java.lang.String> c)

Bulk append of parameter key/value pairs. Each member of the collection must be of the form:

(String)key=value

where key is the key name of the pair to be added and value is in x-www-form-urlencoded form. The semantics of these are the same as individual calls to the appendParam method except that the values are encoded.

Parameters:

c - Collection of key/value pairs.

addParam

public void addParam(java.lang.String key,
            java.lang.String value)

Manipulates the resultant URL by adding this key/value pair. This method will overwrite ANY of the original parameters with the same key and any other parameter that was previously added by this method with the same key. In addition, it is assumed that value is decoded and will encode the value as x-www-form-urlencoded on output. Values that are null or equal to "" will be skipped so that this method can be called without having to check if the value is present.

Parameters:

key - key name of the pair to be added.

value - the value to be added to the output URL where the value is decoded.

addParams

public void addParams(java.util.Collection<java.lang.String> c)

Bulk add of parameter key/value pairs. Each member of the collection must be of the form:

(String)key=value

where key is the key name of the pair to be added and value is in x-www-form-urlencoded form. The semantics of these are the same as individual calls to the addParam method except that the values are encoded.

Parameters:

c - Collection of key value pairs.

removeParam

public void removeParam(java.lang.String key)

Removes any key/value parameter pair from the outputted URL. This removes any parameter that was previously created either from the initial query string specified in the constructor or any parameter added from an addParam call. In the case of multiple parameters with the same name, this method will remove all pairs with the same name.

Parameters:

key - parameter pair to remove with the parameter name key

removeParams

public void removeParams(java.util.Collection<java.lang.String> c)

Removes any key/value parameter with the keys specified in the collection. Same semantics as the removeParam method except that it is batch-applied with the Collection c. Each element of Collection c must be able to be casted as a String and be non-null.

toString

public java.lang.String toString()

The output method on this class. The toString method will output a query string format of the input URL and subsequent add and remove calls. A call to this method does not invalidate the class but merely generates a snapshot output.

Overrides:

toString in class java.lang.Object

Returns:

The URL query string output of this class, where key/value pairs are delimited by ampersand (&), the pairs are delimited by the = character, and the values are x-www-form-urlencoded.

setBaseUrl

public void setBaseUrl(java.lang.String baseUrl)

getBaseUrl

public java.lang.String getBaseUrl()