@NotThreadSafe @PublicApi public final class

UrlBuilder

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

@PublicApi

This class is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

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.

Summary

Public Constructors
UrlBuilder(boolean querySnippet)
Creates a builder with a blank URL.
UrlBuilder(UrlBuilder source)
Creates a copy of the passed builder.
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.
Public Methods
UrlBuilder addAnchor(String value)
Add the passed anchor value to the URL while URL encoding it.
UrlBuilder addParameter(String name, String value)
Adds the parameter to the URL while URL encoding them.
UrlBuilder addParameter(String name, Object value)
Adds the passed parameter to the URL while URL encoding them.
UrlBuilder addParameterUnsafe(String name, String value)
Adds the parameter to the URL without URL encoding them.
UrlBuilder addParametersFromMap(Map<?, ?> params)
Add multiple parameters from a map safely.
UrlBuilder addPath(String path)
URL encodes and adds the given path to the URL.
UrlBuilder addPathUnsafe(String path)
Adds the given path to the URL.
UrlBuilder addPaths(String paths)
URL encodes and adds the given paths 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.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

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.

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.

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.

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

public UrlBuilder (String urlFragment, 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.
encoding the character encoding to use for parameter names and values. Can be left null (recommended) to indicate JIRA default encoding.
querySnippet whether or not this URL is complete or just a query snippet.
Throws
IllegalArgumentException if urlFragment is null

Public Methods

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

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

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

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

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

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

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

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

public URI asURI ()

Returns the URL as a URI.

Returns
  • URL as a URI

public String asUrlString ()

Returns the URL as a String.

Returns
  • URL as a String

public String toString ()

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

Returns