UrlTag (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.servlet.tags

## Class UrlTag

- java.lang.Object
- - javax.servlet.jsp.tagext.TagSupport
  - - org.springframework.web.servlet.tags.RequestContextAwareTag
    - - org.springframework.web.servlet.tags.HtmlEscapingAwareTag
      - - org.springframework.web.servlet.tags.UrlTag

- All Implemented Interfaces:
    Serializable, IterationTag, JspTag, Tag, TryCatchFinally, ParamAware

      public class UrlTag
      extends HtmlEscapingAwareTag
      implements ParamAware

  JSP tag for creating URLs. Modeled after the JSTL c:url tag with backwards compatibility in mind.

  Enhancements to the JSTL functionality include:

  - URL encoded template URI variables
  - HTML/XML escaping of URLs
  - JavaScript escaping of URLs

  Template URI variables are indicated in the `'value'` attribute and marked by braces '{variableName}'. The braces and attribute name are replaced by the URL encoded value of a parameter defined with the spring:param tag in the body of the url tag. If no parameter is available the literal value is passed through. Params matched to template variables will not be added to the query string.

  Use of the spring:param tag for URI template variables is strongly recommended over direct EL substitution as the values are URL encoded. Failure to properly encode URL can leave an application vulnerable to XSS and other injection attacks.

  URLs can be HTML/XML escaped by setting the `'htmlEscape'` attribute to 'true'. Detects an HTML escaping setting, either on this tag instance, the page level, or the `web.xml` level. The default is 'false'. When setting the URL value into a variable, escaping is not recommended.

  Example usage:

      <spring:url value="/url/path/{variableName}">
         <spring:param name="variableName" value="more than JSTL c:url" />
       </spring:url>

  Results in: `/currentApplicationContext/url/path/more%20than%20JSTL%20c%3Aurl`
  Since:
    3.0
  Author:
    Scott Andrews
  See Also:
    `ParamTag`, Serialized Form

- - ### Field Summary

    - ### Fields inherited from class org.springframework.web.servlet.tags.RequestContextAwareTag

      `logger, REQUEST_CONTEXT_PAGE_ATTRIBUTE`

    - ### Fields inherited from class javax.servlet.jsp.tagext.TagSupport

      `id, pageContext`

    - ### Fields inherited from interface javax.servlet.jsp.tagext.IterationTag

      `EVAL_BODY_AGAIN`

    - ### Fields inherited from interface javax.servlet.jsp.tagext.Tag

      `EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UrlTag()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addParam(Param param)` Callback hook for nested spring:param tags to pass their value to the parent tag.
    `protected String` | `createQueryString(List<Param> params, Set<String> usedParams, boolean includeQueryStringDelimiter)` Build the query string from available parameters that have not already been applied as template params.
    `int` | `doEndTag()`
    `int` | `doStartTagInternal()` Called by doStartTag to perform the actual work.
    `protected String` | `replaceUriTemplateParams(String uri, List<Param> params, Set<String> usedParams)` Replace template markers in the URL matching available parameters.
    `void` | `setContext(String context)` Set the context path for the URL.
    `void` | `setJavaScriptEscape(String javaScriptEscape)` Set JavaScript escaping for this tag, as boolean value.
    `void` | `setScope(String scope)` Set the scope to export the URL variable to.
    `void` | `setValue(String value)` Sets the value of the URL
    `void` | `setVar(String var)` Set the variable name to expose the URL under.

    - ### Methods inherited from class org.springframework.web.servlet.tags.HtmlEscapingAwareTag

      `isDefaultHtmlEscape, isHtmlEscape, setHtmlEscape`

    - ### Methods inherited from class org.springframework.web.servlet.tags.RequestContextAwareTag

      `doCatch, doFinally, doStartTag, getRequestContext`

    - ### Methods inherited from class javax.servlet.jsp.tagext.TagSupport

      `doAfterBody, findAncestorWithClass, getId, getParent, getValue, getValues, release, removeValue, setId, setPageContext, setParent, setValue`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### UrlTag

          public UrlTag()

  - ### Method Detail

    - #### setValue

          public void setValue(String value)

      Sets the value of the URL

    - #### setContext

          public void setContext(String context)

      Set the context path for the URL. Defaults to the current context

    - #### setVar

          public void setVar(String var)

      Set the variable name to expose the URL under. Defaults to rendering the URL to the current JspWriter

    - #### setScope

          public void setScope(String scope)

      Set the scope to export the URL variable to. This attribute has no meaning unless var is also defined.

    - #### setJavaScriptEscape

          public void setJavaScriptEscape(String javaScriptEscape)
                                   throws JspException

      Set JavaScript escaping for this tag, as boolean value. Default is "false".
      Throws:
        `JspException`

    - #### addParam

          public void addParam(Param param)

      Description copied from interface: `ParamAware`
      Callback hook for nested spring:param tags to pass their value to the parent tag.
      Specified by:
        `addParam` in interface `ParamAware`
      Parameters:
        `param` - the result of the nested `spring:param` tag

    - #### doStartTagInternal

          public int doStartTagInternal()
                                 throws JspException

      Description copied from class: `RequestContextAwareTag`
      Called by doStartTag to perform the actual work.
      Specified by:
        `doStartTagInternal` in class `RequestContextAwareTag`
      Returns:
        same as TagSupport.doStartTag
      Throws:
        `JspException`
      See Also:
        `TagSupport.doStartTag()`

    - #### doEndTag

          public int doEndTag()
                       throws JspException

      Specified by:
        `doEndTag` in interface `Tag`
      Overrides:
        `doEndTag` in class `TagSupport`
      Throws:
        `JspException`

    - #### createQueryString

          protected String createQueryString(List<Param> params,
                                 Set<String> usedParams,
                                 boolean includeQueryStringDelimiter)
                                      throws JspException

      Build the query string from available parameters that have not already been applied as template params.

      The names and values of parameters are URL encoded.

      Parameters:
        `params` - the parameters to build the query string from
        `usedParams` - set of parameter names that have been applied as template params
        `includeQueryStringDelimiter` - true if the query string should start with a '?' instead of '&'
      Returns:
        the query string
      Throws:
        `JspException`

    - #### replaceUriTemplateParams

          protected String replaceUriTemplateParams(String uri,
                                        List<Param> params,
                                        Set<String> usedParams)
                                             throws JspException

      Replace template markers in the URL matching available parameters. The name of matched parameters are added to the used parameters set.

      Parameter values are URL encoded.

      Parameters:
        `uri` - the URL with template parameters to replace
        `params` - parameters used to replace template markers
        `usedParams` - set of template parameter names that have been replaced
      Returns:
        the URL with template parameters replaced
      Throws:
        `JspException`