com.gwtplatform.mvp.client.proxy
Class ParameterTokenFormatter

java.lang.Object
  com.gwtplatform.mvp.client.proxy.ParameterTokenFormatter

All Implemented Interfaces:

TokenFormatter

public class ParameterTokenFormatter
extends Object
implements TokenFormatter

Formats tokens from String values to PlaceRequest and PlaceRequest hierarchies and vice-versa. The default implementation uses:

• '/' to separate PlaceRequests in a hierarchy;
• ';' to separate parameters in a PlaceRequest;
• '=' to separate the parameter name from its value;
• '\' to escape separators inside parameters names and values in a PlaceRequest.

These symbols cannot be used in a name token. If one of the separating symbol is encountered in a parameter or a value it is escaped using the '\' character by replacing '/' with '\0', ';' with '\1', '=' with '\2' and '\' with '\3'.

Before decoding a String URL fragment into a PlaceRequest or a PlaceRequest hierarchy, ParameterTokenFormatter will first pass the String through URL.decodeQueryString(String) so that if the URL was URL-encoded by some user agent, like a mail user agent, it is still parsed correctly.

For example, ParameterTokenFormatter would parse any of the following:

 nameToken1%3Bparam1.1%3Dvalue1.1%3Bparam1.2%3Dvalue1.2%2FnameToken2%2FnameToken3%3Bparam3.1%3Dvalue%03%11
 nameToken1;param1.1=value1.1;param1.2=value1.2/nameToken2/nameToken3;param3.1=value\03\21
 

Into the following hierarchy of PlaceRequest:

 {
   { "nameToken1", { {"param1.1", "value1.1"}, {"parame1.2","value1.2"} },
     "nameToken2", {},
     "nameToken3", { {"param3.1", "value/3=1"} } }
 }
 

If you want to use different symbols as separator, use the ParameterTokenFormatter(String, String, String) constructor.

Author:

Philippe Beaudoin, Yannis Gonianakis, Daniel Colchete

Field Summary

protected static String	DEFAULT_HIERARCHY_SEPARATOR
protected static String	DEFAULT_PARAM_SEPARATOR
protected static String	DEFAULT_VALUE_SEPARATOR
protected static char	ESCAPE_CHARACTER
protected static String	ESCAPED_ESCAPE_CHAR
protected static String	ESCAPED_HIERARCHY_SEPARATOR
protected static String	ESCAPED_PARAM_SEPARATOR
protected static String	ESCAPED_VALUE_SEPARATOR

Constructor Summary

ParameterTokenFormatter()
Builds a ParameterTokenFormatter using the default separators and escape character.

ParameterTokenFormatter(String hierarchySeparator, String paramSeparator, String valueSeparator)
This constructor makes it possible to use custom separators in your token formatter.

Method Summary

String	toHistoryToken(List<PlaceRequest> placeRequestHierarchy) Converts a place request hierarchy (a list of PlaceRequest) into a history token.
PlaceRequest	toPlaceRequest(String placeToken) Converts a place token into a PlaceRequest.
List<PlaceRequest>	toPlaceRequestHierarchy(String historyToken) Converts a history token into a place request hierarchy (a list of PlaceRequest).
String	toPlaceToken(PlaceRequest placeRequest) Converts a PlaceRequest into a place token.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_HIERARCHY_SEPARATOR

protected static final String DEFAULT_HIERARCHY_SEPARATOR

See Also:

Constant Field Values

DEFAULT_PARAM_SEPARATOR

protected static final String DEFAULT_PARAM_SEPARATOR

See Also:

Constant Field Values

DEFAULT_VALUE_SEPARATOR

protected static final String DEFAULT_VALUE_SEPARATOR

See Also:

Constant Field Values

ESCAPE_CHARACTER

protected static final char ESCAPE_CHARACTER

See Also:

Constant Field Values

ESCAPED_HIERARCHY_SEPARATOR

protected static final String ESCAPED_HIERARCHY_SEPARATOR

See Also:

Constant Field Values

ESCAPED_PARAM_SEPARATOR

protected static final String ESCAPED_PARAM_SEPARATOR

See Also:

Constant Field Values

ESCAPED_VALUE_SEPARATOR

protected static final String ESCAPED_VALUE_SEPARATOR

See Also:

Constant Field Values

ESCAPED_ESCAPE_CHAR

protected static final String ESCAPED_ESCAPE_CHAR

See Also:

Constant Field Values

Constructor Detail

ParameterTokenFormatter

@Inject
public ParameterTokenFormatter()

Builds a ParameterTokenFormatter using the default separators and escape character.

ParameterTokenFormatter

public ParameterTokenFormatter(String hierarchySeparator,
                               String paramSeparator,
                               String valueSeparator)

This constructor makes it possible to use custom separators in your token formatter. The separators must be 1-letter strings, they must all be different from one another, and they must be encoded when ran through URL.encodeQueryString(String)).

Parameters:

hierarchySeparator - The symbol used to separate PlaceRequest in a hierarchy. Must be a 1-character string and can't be %.

paramSeparator - The symbol used to separate parameters in a PlaceRequest. Must be a 1-character string and can't be %.

valueSeparator - The symbol used to separate the parameter name from its value. Must be a 1-character string and can't be %.

Method Detail

toHistoryToken

public String toHistoryToken(List<PlaceRequest> placeRequestHierarchy)
                      throws TokenFormatException

Description copied from interface: TokenFormatter

Converts a place request hierarchy (a list of PlaceRequest) into a history token. The history token will not be fully query encoded, it may still contain some unescaped separators. However, these separators can be encoded and it will still work, making the scheme robust to systems that force encoding these characters like some email apps.

Specified by:

toHistoryToken in interface TokenFormatter

Parameters:

placeRequestHierarchy - The place request hierarchy.

Returns:

The history token, URL encoded.

Throws:

TokenFormatException - if there is an error converting.

toPlaceRequest

public PlaceRequest toPlaceRequest(String placeToken)
                            throws TokenFormatException

Description copied from interface: TokenFormatter

Converts a place token into a PlaceRequest. A place token is different than a history token, since the history token can contain a hierarchy of different place requests.

Specified by:

toPlaceRequest in interface TokenFormatter

Parameters:

placeToken - The place token.

Returns:

The place request.

Throws:

TokenFormatException - if there is an error converting.

toPlaceRequestHierarchy

public List<PlaceRequest> toPlaceRequestHierarchy(String historyToken)
                                           throws TokenFormatException

Description copied from interface: TokenFormatter

Converts a history token into a place request hierarchy (a list of PlaceRequest).

Specified by:

toPlaceRequestHierarchy in interface TokenFormatter

Parameters:

historyToken - The history token.

Returns:

The place request hierarchy.

Throws:

TokenFormatException - if there is an error converting.

toPlaceToken

public String toPlaceToken(PlaceRequest placeRequest)
                    throws TokenFormatException

Description copied from interface: TokenFormatter

Converts a PlaceRequest into a place token. A place token is different than a history token, since the history token can contain a hierarchy of different place requests. The history token will not be fully query encoded, it may still contain some unescaped separators. However, these separators can be encoded and it will still work, making the scheme robust to systems that force encoding these characters like some email apps.

Specified by:

toPlaceToken in interface TokenFormatter

Parameters:

placeRequest - The place request.

Returns:

The place token, URL encoded.

Throws:

TokenFormatException - if there is an error converting.