com.atlassian.jira.util
Class UrlBuilder

java.lang.Object
  com.atlassian.jira.util.UrlBuilder

@NotThreadSafe
public final class UrlBuilder
extends java.lang.Object

Build a URL from parameters.

NOTE: This class does not HTML escape the URLS. Be very careful if using this class to output a URL on the UI.

Since:

v4.0

Constructor Summary

UrlBuilder(boolean snippet)
Create a builder with a blank URL.

UrlBuilder(java.lang.String baseUrl)
Create a builder with the specified base URL.

UrlBuilder(java.lang.String baseUrl, boolean snippet)
Create a builder with the specified base URL.

UrlBuilder(java.lang.String baseUrl, java.lang.String encoding, boolean snippet)
Create a builder with the specified base URL.

UrlBuilder(UrlBuilder source)
Create a copy of the passed builder.

Method Summary

UrlBuilder	addAnchor(java.lang.String value) Add the passed anchor value to the URL while URL encoding it.
UrlBuilder	addParameter(java.lang.String name, java.lang.String value) Add the passed parameter to the URL while URL encoding them.
UrlBuilder	addParametersFromMap(java.util.Map<?,?> params) Add multiple parameters from a map safely.
UrlBuilder	addParameterUnsafe(java.lang.String name, java.lang.String value) Add the passed parameter to the URL without URL encoding them.
java.lang.String	asUrlString()

Methods inherited from class java.lang.Object

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

Constructor Detail

UrlBuilder

public UrlBuilder(boolean snippet)

Create a builder with a blank URL.

Parameters:

snippet - whether or not this Url is complete or just a query snippet

Throws:

java.lang.IllegalArgumentException - if the base url is null.

UrlBuilder

public UrlBuilder(UrlBuilder source)

Create a copy of the passed builder. The state of the two builders will be independent after the copy.

Parameters:

source - the builder to copy, cannot be null.

Throws:

java.lang.IllegalArgumentException - if source is null.

UrlBuilder

public UrlBuilder(java.lang.String baseUrl)

Create a builder with the specified base URL. The base URL will be used as the start or the URL generated by this builder.

Parameters:

baseUrl - the basedUrl for the builder. This parameter will not be escaped in the resulting URL.

Throws:

java.lang.IllegalArgumentException - if the base url is null.

UrlBuilder

public UrlBuilder(java.lang.String baseUrl,
                  boolean snippet)

Create a builder with the specified base URL. The base URL will be used as the start or the URL generated by this builder.

Parameters:

baseUrl - the basedUrl for the builder. This parameter will not be escaped in the resulting URL.

snippet - whether or not this Url is complete or just a query snippet

Throws:

java.lang.IllegalArgumentException - if the base url is null.

UrlBuilder

public UrlBuilder(java.lang.String baseUrl,
                  java.lang.String encoding,
                  boolean snippet)

Create a builder with the specified base URL. The base URL will be used as the start or the URL generated by this builder.

Parameters:

baseUrl - the basedUrl for the builder. This parameter will not be escaped in the resulting URL.

snippet - whether or not this Url is complete or just a query snippet.

encoding - the character encoding to use for parameter names and values. Can be left null (recommended) to indicate JIRA default encoding.

Throws:

java.lang.IllegalArgumentException - if the base url is null.

Method Detail

addParameterUnsafe

public UrlBuilder addParameterUnsafe(java.lang.String name,
                                     java.lang.String value)

Add the passed parameter to the URL without URL encoding them. This is UNSAFE as it may allow XSS attacks. If you use this mehtod, you must ensure that the parameters are already safe.

Parameters:

name - the name of the parameter. This parameter name is not escaped before it is added to the URL. This value cannot be blank.

value - the value of the parameter. This value is not escaped before it is added to the URL.

Returns:

this builder so that calls may be chained.

Throws:

java.lang.IllegalArgumentException - if name is blank.

addParameter

public UrlBuilder addParameter(java.lang.String name,
                               java.lang.String value)

Add the passed parameter to the URL while URL encoding them.

Parameters:

name - the name of the parameter.This value cannot be blank.

value - the value of the parameter.

Returns:

this builder so that calls may be changed.

Throws:

java.lang.IllegalArgumentException - if name is blank.

addAnchor

public UrlBuilder addAnchor(java.lang.String value)

Add the passed anchor value to the URL while URL encoding it. The result will be something like #myAnchor. Note that to be compliant with standards, you will want to call this only after adding all your parameters.

Parameters:

value - the value of the anchor.

Returns:

this builder so that calls may be changed.

Throws:

java.lang.IllegalArgumentException - if name is blank.

addParametersFromMap

public UrlBuilder addParametersFromMap(java.util.Map<?,?> params)

Add multiple parameters from a map safely. Any keys which are null or blank will be ignored. The parameters will be added in order as given by the passed map's entrySet.

Parameters:

params - map containing parameters to add. Must not be null.

Returns:

this builder

asUrlString

public java.lang.String asUrlString()