Package 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 Details

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

  • Method Details

    • createURL

      @Nonnull public static URL createURL(String urlString)
      Creates a URL from the given string. Convenience wrapper that handles checked exceptions.
      Parameters:
      urlString - the string to be turned into a URL
      Returns:
      the created URL
      Throws:
      IllegalArgumentException - if the given string is malformed
      See Also:

    • 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()