Package org.zkoss.web.servlet.http

## Class Encodes

- java.lang.Object
- - org.zkoss.web.servlet.http.Encodes

-     public class Encodes
      extends java.lang.Object

  Encoding utilities for servlets.
  Author:
    tomyeh
  See Also:
    `Https`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `Encodes.URLEncoder` | The URL encoder used to encode URL by including the session ID, and servlet context path.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Encodes()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.StringBuffer` | `addToQueryString​(java.lang.StringBuffer sb, java.lang.String name, java.lang.Object value)` | Appends a parameter (name=value) to a query string.
    `static java.lang.StringBuffer` | `addToQueryString​(java.lang.StringBuffer sb, java.util.Map params)` | /** Appends a map of parameters (name=value) to a query string.
    `static boolean` | `containsQuery​(java.lang.String str, java.lang.String name)` | Tests whether a parameter exists in the query string.
    `static java.lang.String` | `encodeURI​(java.lang.String s)` | Does the HTTP encoding for the URI location.
    `static java.lang.String` | `encodeURIComponent​(java.lang.String s)` | Does the HTTP encoding for an URI query parameter.
    `static java.lang.String` | `encodeURL​(javax.servlet.ServletContext ctx, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String uri)` | Encodes an URL.
    `static java.lang.StringBuffer` | `removeFromQueryString​(java.lang.StringBuffer sb, java.lang.String name)` | Remove all name/value pairs of the specified name from a string.
    `static java.lang.String` | `removeFromQueryString​(java.lang.String str, java.lang.String name)` | Remove all name/value pairs of the specified name from a string.
    `static java.lang.StringBuffer` | `setToQueryString​(java.lang.StringBuffer sb, java.lang.String name, java.lang.Object value)` | Sets the parameter (name=value) to a query string.
    `static java.lang.StringBuffer` | `setToQueryString​(java.lang.StringBuffer sb, java.util.Map params)` | Sets a map of parameters (name=value) to a query string.
    `static java.lang.String` | `setToQueryString​(java.lang.String str, java.lang.String name, java.lang.Object value)` | Sets the parameter (name=value) to a query string.
    `static java.lang.String` | `setToQueryString​(java.lang.String str, java.util.Map params)` | Sets a map of parameters (name=value) to a query string.

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

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

- - ### Constructor Detail

    - #### Encodes

          protected Encodes()

  - ### Method Detail

    - #### encodeURI

          public static final java.lang.String encodeURI​(java.lang.String s)
                                                  throws java.io.UnsupportedEncodingException

      Does the HTTP encoding for the URI location. For example, '%' is translated to '%25'.

      Since `encodeURL(ServletContext, ServletRequest, ServletResponse, String)` will invoke this method automatically, you rarely need this method.

      Parameters:
        `s` - the string to encode; null is OK
      Returns:
        the encoded string or null if s is null
      Throws:
        `java.io.UnsupportedEncodingException`
      See Also:
        `encodeURIComponent(java.lang.String)`

    - #### encodeURIComponent

          public static final java.lang.String encodeURIComponent​(java.lang.String s)
                                                           throws java.io.UnsupportedEncodingException

      Does the HTTP encoding for an URI query parameter. For example, '/' is translated to '%2F'. Both name and value must be encoded separately. Example, `encodeURIComponent(name) + '=' + encodeURIComponent(value)`.

      Since `encodeURL(ServletContext, ServletRequest, ServletResponse, String)` will not invoke this method automatically, you'd better to encode each query parameter by this method or `addToQueryString(StringBuffer,Map)`.

      Parameters:
        `s` - the string to encode; null is OK
      Returns:
        the encoded string or null if s is null
      Throws:
        `java.io.UnsupportedEncodingException`
      See Also:
        `addToQueryString(StringBuffer,String,Object)`, `encodeURI(java.lang.String)`

    - #### addToQueryString

          public static final java.lang.StringBuffer addToQueryString​(java.lang.StringBuffer sb,
                                                                      java.util.Map params)
                                                               throws java.io.UnsupportedEncodingException

      /** Appends a map of parameters (name=value) to a query string. It returns the query string preceding with '?' if any parameter exists, or an empty string if no parameter at all. Thus, you could do

      `request.getRequestDispatcher(
      addToQueryStirng(new StringBuffer(uri), params).toString());`

      Since RequestDispatcher.include and forward do not allow wrapping the request and response -- see spec and the implementation of both Jetty and Catalina, we have to use this method to pass the parameters.

      Parameters:
        `params` - a map of parameters; format: (String, Object) or (String, Object[]); null is OK
      Throws:
        `java.io.UnsupportedEncodingException`

    - #### addToQueryString

          public static final java.lang.StringBuffer addToQueryString​(java.lang.StringBuffer sb,
                                                                      java.lang.String name,
                                                                      java.lang.Object value)
                                                               throws java.io.UnsupportedEncodingException

      Appends a parameter (name=value) to a query string. This method automatically detects whether other query is already appended. If so, & is used instead of ?.

      The query string might contain servlet path and other parts. This method starts the searching from the first '?'. If the query string doesn't contain '?', it is assumed to be a string without query's name/value pairs.

      Parameters:
        `value` - the value. If it is null, only name is appended. If it is an array of objects, multiple pairs of name=value[j] will be appended.
      Throws:
        `java.io.UnsupportedEncodingException`

    - #### setToQueryString

          public static final java.lang.String setToQueryString​(java.lang.String str,
                                                                java.lang.String name,
                                                                java.lang.Object value)
                                                         throws java.io.UnsupportedEncodingException

      Sets the parameter (name=value) to a query string. If the name already exists in the query string, it will be removed first. If your name has appeared in the string, it will replace your new value to the query string. Otherwise, it will append the name/value to the new string.

      The query string might contain servlet path and other parts. This method starts the searching from the first '?'. If the query string doesn't contain '?', it is assumed to be a string without query's name/value pairs.

      Parameters:
        `str` - The query string like xxx?xxx=xxx&xxx=xxx or null.
        `name` - The get parameter name.
        `value` - The value associated with the get parameter name.
      Returns:
        The new or result query string with your name/value.
      Throws:
        `java.io.UnsupportedEncodingException`
      See Also:
        `addToQueryString(java.lang.StringBuffer, java.util.Map)`

    - #### setToQueryString

          public static final java.lang.StringBuffer setToQueryString​(java.lang.StringBuffer sb,
                                                                      java.lang.String name,
                                                                      java.lang.Object value)
                                                               throws java.io.UnsupportedEncodingException

      Sets the parameter (name=value) to a query string. If the name already exists in the query string, it will be removed first.
      Throws:
        `java.io.UnsupportedEncodingException`
      See Also:
        `addToQueryString(java.lang.StringBuffer, java.util.Map)`

    - #### setToQueryString

          public static final java.lang.String setToQueryString​(java.lang.String str,
                                                                java.util.Map params)
                                                         throws java.io.UnsupportedEncodingException

      Sets a map of parameters (name=value) to a query string. If the name already exists in the query string, it will be removed first.
      Throws:
        `java.io.UnsupportedEncodingException`
      See Also:
        `addToQueryString(java.lang.StringBuffer, java.util.Map)`

    - #### setToQueryString

          public static final java.lang.StringBuffer setToQueryString​(java.lang.StringBuffer sb,
                                                                      java.util.Map params)
                                                               throws java.io.UnsupportedEncodingException

      Sets a map of parameters (name=value) to a query string. If the name already exists in the query string, it will be removed first.
      Throws:
        `java.io.UnsupportedEncodingException`
      See Also:
        `addToQueryString(java.lang.StringBuffer, java.util.Map)`

    - #### containsQuery

          public static final boolean containsQuery​(java.lang.String str,
                                                    java.lang.String name)

      Tests whether a parameter exists in the query string.

    - #### removeFromQueryString

          public static final java.lang.String removeFromQueryString​(java.lang.String str,
                                                                     java.lang.String name)
                                                              throws java.io.UnsupportedEncodingException

      Remove all name/value pairs of the specified name from a string.

      The query string might contain servlet path and other parts. This method starts the searching from the last '?'. If the query string doesn't contain '?', it is assumed to be a string without query's name/value pairs.

      Throws:
        `java.io.UnsupportedEncodingException`
      See Also:
        `addToQueryString(java.lang.StringBuffer, java.util.Map)`

    - #### removeFromQueryString

          public static final java.lang.StringBuffer removeFromQueryString​(java.lang.StringBuffer sb,
                                                                           java.lang.String name)
                                                                    throws java.io.UnsupportedEncodingException

      Remove all name/value pairs of the specified name from a string.
      Throws:
        `java.io.UnsupportedEncodingException`
      See Also:
        `addToQueryString(java.lang.StringBuffer, java.util.Map)`

    - #### encodeURL

          public static final java.lang.String encodeURL​(javax.servlet.ServletContext ctx,
                                                         javax.servlet.ServletRequest request,
                                                         javax.servlet.ServletResponse response,
                                                         java.lang.String uri)
                                                  throws javax.servlet.ServletException

      Encodes an URL. It resolves "*" contained in URI, if any, to the proper Locale, and the browser code. Refer to `Servlets.locate(ServletContext, ServletRequest, String, Locator)` for details.

      In additions, if uri starts with "/", the context path, e.g., /zkdemo, is prefixed. In other words, "/ab/cd" means it is relevant to the servlet context path (say, "/zkdemo").

      If uri starts with "~abc/", it means it is relevant to a foreign Web context called /abc. And, it will be converted to "/abc/" first (without prefix request.getContextPath()).

      Finally, the uri is encoded by HttpServletResponse.encodeURL.

      This method invokes `encodeURI(java.lang.String)` for any characters before '?'. However, it does NOT encode any character after '?'. Thus, you might have to invoke `encodeURIComponent(java.lang.String)` or `addToQueryString(StringBuffer,Map)` to encode the query parameters.

      ### The URL Prefix and Encoder

      In a sophisticated environment, e.g., Reverse Proxy, the encoded URL might have to be prefixed with some special prefix. To do that, you can implement `Encodes.URLEncoder`, and then specify the class with the library property called `org.zkoss.web.servlet.http.URLEncoder`. When `encodeURL(javax.servlet.ServletContext, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)` encodes an URL, it will invoke `Encodes.URLEncoder.encodeURL(javax.servlet.ServletContext, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String, org.zkoss.web.servlet.http.Encodes.URLEncoder)` such you can do customized encoding, such as insert a special prefix.

      Parameters:
        `request` - the request; never null
        `response` - the response; never null
        `uri` - it must be null, empty or starts with "/". It might contain "*" for current browser code and Locale.
        `ctx` - the servlet context; used only if "*" is contained in uri
      Throws:
        `IndexOutOfBoundException` - if uri is empty
        `javax.servlet.ServletException`
      See Also:
        `Servlets.locate(javax.servlet.ServletContext, javax.servlet.ServletRequest, java.lang.String, org.zkoss.util.resource.Locator)`, `Servlets.generateURI(java.lang.String, java.util.Map, int)`