org.zkoss.web.servlet.http
Class Encodes

java.lang.Object
  extended by 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
static interface Encodes.URLEncoder
          The URL encoder used to encode URL by including the session ID, and servlet context path.
 
Constructor Summary
protected Encodes()
           
 
Method Summary
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 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 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.util.Map params)
          Sets a map of parameters (name=value) to a query 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.String setToQueryString(java.lang.String str, 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.
 
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)


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo