org.zkoss.web.servlet.http

Class Encodes

java.lang.Object

org.zkoss.web.servlet.http.Encodes

public class Encodes
extends Object

Encoding utilities for servlets.

Author:

tomyeh

See Also:

Https

Nested Class Summary

Nested Classes

Modifier and Type	Class and 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 and Description
protected	Encodes()

Method Summary

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

UnsupportedEncodingException

See Also:

encodeURIComponent(java.lang.String)

encodeURIComponent

public static final String encodeURIComponent(String s)
                                       throws 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:

UnsupportedEncodingException

See Also:

addToQueryString(StringBuffer,String,Object), encodeURI(java.lang.String)

addToQueryString

public static final StringBuffer addToQueryString(StringBuffer sb,
                                                  Map params)
                                           throws 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:

UnsupportedEncodingException

addToQueryString

public static final StringBuffer addToQueryString(StringBuffer sb,
                                                  String name,
                                                  Object value)
                                           throws 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:

UnsupportedEncodingException

setToQueryString

public static final String setToQueryString(String str,
                                            String name,
                                            Object value)
                                     throws 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:

UnsupportedEncodingException

See Also:

addToQueryString(java.lang.StringBuffer, java.util.Map)

setToQueryString

public static final StringBuffer setToQueryString(StringBuffer sb,
                                                  String name,
                                                  Object value)
                                           throws 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:

UnsupportedEncodingException

See Also:

addToQueryString(java.lang.StringBuffer, java.util.Map)

setToQueryString

public static final String setToQueryString(String str,
                                            Map params)
                                     throws 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:

UnsupportedEncodingException

See Also:

addToQueryString(java.lang.StringBuffer, java.util.Map)

setToQueryString

public static final StringBuffer setToQueryString(StringBuffer sb,
                                                  Map params)
                                           throws 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:

UnsupportedEncodingException

See Also:

addToQueryString(java.lang.StringBuffer, java.util.Map)

containsQuery

public static final boolean containsQuery(String str,
                                          String name)

Tests whether a parameter exists in the query string.

removeFromQueryString

public static final String removeFromQueryString(String str,
                                                 String name)
                                          throws 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:

UnsupportedEncodingException

See Also:

addToQueryString(java.lang.StringBuffer, java.util.Map)

removeFromQueryString

public static final StringBuffer removeFromQueryString(StringBuffer sb,
                                                       String name)
                                                throws UnsupportedEncodingException

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

Throws:

UnsupportedEncodingException

See Also:

addToQueryString(java.lang.StringBuffer, java.util.Map)

encodeURL

public static final String encodeURL(javax.servlet.ServletContext ctx,
                                     javax.servlet.ServletRequest request,
                                     javax.servlet.ServletResponse response,
                                     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)