com.atlassian.jira.util
Class UrlBuilder

java.lang.Object
  extended by 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
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
 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()


Copyright © 2002-2014 Atlassian. All Rights Reserved.