Package org.zkoss.web.servlet

## Class Charsets

- java.lang.Object
- - org.zkoss.web.servlet.Charsets

-     public class Charsets
      extends java.lang.Object

  Utilities to handle characters
  Author:
    tomyeh

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Charsets()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `cleanup​(javax.servlet.ServletRequest request, java.lang.Object old)` | Cleans up what has been set in `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)`.
    `static java.util.Locale` | `getPreferredLocale​(javax.servlet.http.HttpSession sess, javax.servlet.ServletRequest request)` | Returns the preferred locale of the specified request.
    `static java.util.Locale` | `getPreferredLocale​(javax.servlet.ServletRequest request)` | Returns the preferred locale of the specified request.
    `static java.lang.String` | `getURICharset()` | Returns the charset used to encode URI and query string.
    `static boolean` | `hasSetup​(javax.servlet.ServletRequest request)` | Returns whether the specified request has been set up, i.e., `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)` is called
    `static void` | `markSetup​(javax.servlet.ServletRequest request, boolean setup)` | Marks the specified request whether it has been set up, i.e., `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)` is called.
    `static void` | `setPreferredLocale​(javax.servlet.http.HttpSession hsess, java.util.Locale locale)` | Sets the preferred locale for the specified session.
    `static void` | `setPreferredLocale​(javax.servlet.ServletContext ctx, java.util.Locale locale)` | Sets the preferred locale for the specified servlet context.
    `static java.lang.Object` | `setup​(javax.servlet.http.HttpSession sess, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String charset)` | Sets up the charset for the request and response based on `getPreferredLocale(HttpSession,ServletRequest)`.
    `static java.lang.Object` | `setup​(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String charset)` | Sets up the charset for the request and response based on `getPreferredLocale(HttpSession,ServletRequest)`.

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

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

- - ### Constructor Detail

    - #### Charsets

          public Charsets()

  - ### Method Detail

    - #### getURICharset

          public static final java.lang.String getURICharset()

      Returns the charset used to encode URI and query string.

    - #### setup

          public static final java.lang.Object setup​(javax.servlet.http.HttpSession sess,
                                                     javax.servlet.ServletRequest request,
                                                     javax.servlet.ServletResponse response,
                                                     java.lang.String charset)

      Sets up the charset for the request and response based on `getPreferredLocale(HttpSession,ServletRequest)`. After setting up, you shall invoke `cleanup(javax.servlet.ServletRequest, java.lang.Object)` before exiting.

           final Object old = setup(request, response, null);
           try {
                    ....
           } finally {
              cleanup(request, old);
           }

           It is OK to call this method multiple time, since it is smart
           enough to ignore redundant calls.

           CharsetFilter actually use this method to setup
           the proper charset and locale. By mapping CharsetFilter to
           all servlets, the encoding charset could be prepared correctly.
           However, if you are writing libraries to be as independent of
           web.xml as possible, you might choose to invoke this method directly.

      Parameters:
        `sess` - the session to look for the preferred locale. Ignored if null.
        `charset` - the response's charset. If null or empty, response.setCharacterEncoding won't be called, i.e., the container's default is used.
      Returns:
        an object that must be passed to `cleanup(javax.servlet.ServletRequest, java.lang.Object)`

    - #### setup

          public static final java.lang.Object setup​(javax.servlet.ServletRequest request,
                                                     javax.servlet.ServletResponse response,
                                                     java.lang.String charset)

      Sets up the charset for the request and response based on `getPreferredLocale(HttpSession,ServletRequest)`. It is the same as setup(request.getSession(false), request, response, charset);

    - #### cleanup

          public static final void cleanup​(javax.servlet.ServletRequest request,
                                           java.lang.Object old)

      Cleans up what has been set in `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)`. Some invocation are not undo-able, so this method only does the basic cleanups.
      Parameters:
        `old` - the value must be the one returned by the last call to `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)`.

    - #### hasSetup

          public static final boolean hasSetup​(javax.servlet.ServletRequest request)

      Returns whether the specified request has been set up, i.e., `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)` is called

      It is rarely needed to call this method, because it is called automatically by `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)`.

    - #### markSetup

          public static final void markSetup​(javax.servlet.ServletRequest request,
                                             boolean setup)

      Marks the specified request whether it has been set up, i.e., `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)` is called.

      It is rarely needed to call this method, because it is called automatically by `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)`.

    - #### getPreferredLocale

          public static final java.util.Locale getPreferredLocale​(javax.servlet.http.HttpSession sess,
                                                                  javax.servlet.ServletRequest request)

      Returns the preferred locale of the specified request. You rarely need to invoke this method directly, because it is done automatically by `setup(javax.servlet.http.HttpSession, javax.servlet.ServletRequest, javax.servlet.ServletResponse, java.lang.String)`.
      1. It checks whether any attribute stored in HttpSession called `Attributes.PREFERRED_LOCALE`. If so, return it.
      2. If not found, it checks if the servlet context has the attribute called `Attributes.PREFERRED_LOCALE`. If so, return it.
      3. If not found, it checks if the library property called `Attributes.PREFERRED_LOCALE` is defined. If so, return it.
      4. Otherwise, use ServletRequest.getLocale().
      Parameters:
        `sess` - the session to look for the preferred locale. Ignored if null.

    - #### getPreferredLocale

          public static final java.util.Locale getPreferredLocale​(javax.servlet.ServletRequest request)

      Returns the preferred locale of the specified request. It is the same as getPreferredLocale(request.getSession(false), request).

    - #### setPreferredLocale

          public static final void setPreferredLocale​(javax.servlet.http.HttpSession hsess,
                                                      java.util.Locale locale)

      Sets the preferred locale for the specified session. It is the default locale for the whole Web session.

      Default: null (no preferred locale -- depending on browser's setting).

      Parameters:
        `locale` - the preferred Locale. If null, it means no preferred locale
      Since:
        3.6.3
      See Also:
        `getPreferredLocale(HttpSession,ServletRequest)`

    - #### setPreferredLocale

          public static final void setPreferredLocale​(javax.servlet.ServletContext ctx,
                                                      java.util.Locale locale)

      Sets the preferred locale for the specified servlet context. It is the default locale for the whole Web application.

      Default: null (no preferred locale -- depending on browser's setting).

      Parameters:
        `locale` - the preferred Locale. If null, it means no preferred locale
      Since:
        3.6.3
      See Also:
        `getPreferredLocale(HttpSession,ServletRequest)`