com.atlassian.jira.util

Class UrlBuilder

java.lang.Object

com.atlassian.jira.util.UrlBuilder

@NotThreadSafe
@PublicApi
public final class UrlBuilder
extends Object

Builds 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

Constructors

Constructor and Description
UrlBuilder(boolean querySnippet) Creates a builder with a blank URL.
UrlBuilder(String urlFragment) Creates a builder with the specified URL fragment.
UrlBuilder(String urlFragment, boolean querySnippet) Creates a builder with the specified URL fragment.
UrlBuilder(String urlFragment, String encoding, boolean querySnippet) Creates a builder with the specified URL fragment.
UrlBuilder(UrlBuilder source) Creates a copy of the passed builder.

Method Summary

Methods

Modifier and Type	Method and Description
UrlBuilder	addAnchor(String value) Add the passed anchor value to the URL while URL encoding it.
UrlBuilder	addParameter(String name, Object value) Adds the passed parameter to the URL while URL encoding them.
UrlBuilder	addParameter(String name, String value) Adds the parameter to the URL while URL encoding them.
UrlBuilder	addParametersFromMap(Map<?,?> params) Add multiple parameters from a map safely.
UrlBuilder	addParameterUnsafe(String name, String value) Adds the parameter to the URL without URL encoding them.
UrlBuilder	addPath(String path) URL encodes and adds the given path to the URL.
UrlBuilder	addPaths(String paths) URL encodes and adds the given paths to the URL.
UrlBuilder	addPathUnsafe(String path) Adds the given path to the URL.
URI	asURI() Returns the URL as a URI.
String	asUrlString() Returns the URL as a String.
String	toString() Returns the same thing as asUrlString(), to avoid confusion.

Methods inherited from class java.lang.Object

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

Constructor Detail

UrlBuilder

public UrlBuilder(boolean querySnippet)

Creates a builder with a blank URL.

Parameters:

querySnippet - whether or not this URL is complete or just a query snippet

Throws:

IllegalArgumentException - if the base url is null.

UrlBuilder

public UrlBuilder(UrlBuilder source)

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

IllegalArgumentException - if source is null.

UrlBuilder

public UrlBuilder(String urlFragment)

Creates a builder with the specified URL fragment. The URL will be used as the start of the URL generated by this builder.

Parameters:

urlFragment - the URL fragment for the builder. This parameter will not be escaped in the resulting URL.

Throws:

IllegalArgumentException - if urlFragment is null.

UrlBuilder

public UrlBuilder(String urlFragment,
          boolean querySnippet)

Creates a builder with the specified URL fragment. The URL will be used as the start of the URL generated by this builder.

Parameters:

urlFragment - the URL or query snippet for the builder. This parameter will not be escaped in the resulting URL.

querySnippet - whether or not this URL is complete or just a query snippet

Throws:

IllegalArgumentException - if the urlFragment is null

UrlBuilder

public UrlBuilder(String urlFragment,
          @Nullable
          String encoding,
          boolean querySnippet)

Creates a builder with the specified URL fragment. The URL will be used as the start of the URL generated by this builder.

Parameters:

urlFragment - the URL fragment for the builder. This parameter will not be escaped in the resulting URL.

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

IllegalArgumentException - if urlFragment is null

Method Detail

addPathUnsafe

public UrlBuilder addPathUnsafe(String path)

Adds the given path to the URL. If needed, a '/' will be added between the existing URL and the given path. If you use this method, you must ensure that the parameters are already safe. Otherwise, use addPath(String).

Parameters:

path - the path to add to the URL. This parameter name is not escaped before it is added to the URL.

Returns:

builder so that calls may be chained

addPath

public UrlBuilder addPath(String path)

URL encodes and adds the given path to the URL. If needed a '/' will be added between the existing URL and the given path.

Parameters:

path - path to be encoded and added to the URL. The path cannot be blank.

Returns:

this builder so that calls may be chained

Throws:

IllegalArgumentException - if path is blank

addPaths

public UrlBuilder addPaths(String paths)

URL encodes and adds the given paths to the URL. If needed a '/' will be added between the existing URL and the given paths. The paths in between the path separator ('/') will be encoded.

Parameters:

paths - paths to be encoded and added to the URL. E.g. "/one/two/three". Cannot be blank.

Returns:

this builder so that calls may be chained

Throws:

IllegalArgumentException - if paths is blank

addParameterUnsafe

public UrlBuilder addParameterUnsafe(String name,
                            String value)

Adds the parameter to the URL without URL encoding them. This is UNSAFE as it may allow XSS attacks. If you use this method, 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:

IllegalArgumentException - if name is blank

addParameter

public UrlBuilder addParameter(String name,
                      String value)

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

IllegalArgumentException - if name is blank

addParameter

public UrlBuilder addParameter(String name,
                      Object value)

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

IllegalArgumentException - if name is blank

addAnchor

public UrlBuilder addAnchor(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:

IllegalArgumentException - if name is blank

addParametersFromMap

public UrlBuilder addParametersFromMap(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 String asUrlString()

Returns the URL as a String.

Returns:

URL as a String

asURI

public URI asURI()

Returns the URL as a URI.

Returns:

URL as a URI

toString

public String toString()

Returns the same thing as asUrlString(), to avoid confusion.

Overrides:

toString in class Object

Returns:

the same thing as asUrlString()