English | Site Directory

Android - An Open Handset Alliance Project

android.net
public class

android.net.UrlQuerySanitizer

java.lang.Object
android.net.UrlQuerySanitizer

Sanitizes the Query portion of a URL. Simple example: UrlQuerySanitizer sanitizer = new UrlQuerySanitizer(); sanitizer.setAllowUnregisteredParamaters(true); sanitizer.parseUrl("http://example.com/?name=Joe+User"); String name = sanitizer.getValue("name")); // name now contains "Joe_User" Register ValueSanitizers to customize the way individual parameters are sanitized: UrlQuerySanitizer sanitizer = new UrlQuerySanitizer(); sanitizer.registerParamater("name", UrlQuerySanitizer.createSpaceLegal()); sanitizer.parseUrl("http://example.com/?name=Joe+User"); String name = sanitizer.getValue("name")); // name now contains "Joe User". (The string is first decoded, which // converts the '+' to a ' '. Then the string is sanitized, which // converts the ' ' to an '_'. (The ' ' is converted because the default unregistered parameter sanitizer does not allow any special characters, and ' ' is a special character.) There are several ways to create ValueSanitizers. In order of increasing sophistication:

  1. Call one of the UrlQuerySanitizer.createXXX() methods.
  2. Construct your own instance of UrlQuerySanitizer.IllegalCharacterValueSanitizer.
  3. Subclass UrlQuerySanitizer.ValueSanitizer to define your own value sanitizer.

Nested Classes
UrlQuerySanitizer.IllegalCharacterValueSanitizer Sanitize values based on which characters they contain. 
UrlQuerySanitizer.ParameterValuePair A simple tuple that holds parameter-value pairs. 
UrlQuerySanitizer.ValueSanitizer A functor used to sanitize a single query value. 

Summary

Public Constructors

          UrlQuerySanitizer()
Constructs a UrlQuerySanitizer.
          UrlQuerySanitizer(String url)
Constructs a UrlQuerySanitizer and parse a URL.

Public Methods

    final  static  ValueSanitizer  getAllButNulAndAngleBracketsLegal()
Return a value sanitizer that allows any special characters except angle brackets ('<' and '>') and Nul ('\0').
    final  static  ValueSanitizer  getAllButNulLegal()
Return a value sanitizer that allows everything except Nul ('\0') characters.
    final  static  ValueSanitizer  getAllButWhitespaceLegal()
Return a value sanitizer that allows everything except Nul ('\0') characters, space (' '), and other whitespace characters.
    final  static  ValueSanitizer  getAllIllegal()
Return a value sanitizer that does not allow any special characters, and also does not allow script URLs.
        boolean  getAllowUnregisteredParamaters()
Get whether or not unregistered parameters are allowed.
    final  static  ValueSanitizer  getAmpAndSpaceLegal()
Return a value sanitizer that does not allow any special characters except ampersand ('&') and space (' ').
    final  static  ValueSanitizer  getAmpLegal()
Return a value sanitizer that does not allow any special characters except ampersand ('&').
        ValueSanitizer  getEffectiveValueSanitizer(String parameter)
Get the effective value sanitizer for a parameter.
        List  getParameterList()
An array list of all of the parameter value pairs in the sanitized query, in the order they appeared in the query.
        Set  getParameterSet()
Get a set of all of the parameters found in the sanitized query.
        boolean  getPreferFirstRepeatedParameter()
Get whether or not the first occurrence of a repeated parameter is preferred.
    final  static  ValueSanitizer  getSpaceLegal()
Return a value sanitizer that does not allow any special characters except space (' ').
        ValueSanitizer  getUnregisteredParameterValueSanitizer()
Get the current value sanitizer used when processing unregistered parameter values.
    final  static  ValueSanitizer  getUrlAndSpaceLegal()
Return a value sanitizer that allows all the characters used by encoded URLs and allows spaces, which are not technically legal in encoded URLs, but commonly appear anyway.
    final  static  ValueSanitizer  getUrlLegal()
Return a value sanitizer that allows all the characters used by encoded URLs.
        String  getValue(String parameter)
Get the value for a parameter in the current sanitized query.
        ValueSanitizer  getValueSanitizer(String parameter)
Get the value sanitizer for a parameter.
        boolean  hasParameter(String parameter)
Check if a parameter exists in the current sanitized query.
        void  parseQuery(String query)
Parse a query.
        void  parseUrl(String url)
Parse the query parameters out of an encoded URL.
        void  registerParameter(String parameter, ValueSanitizer valueSanitizer)
Register a value sanitizer for a particular parameter.
        void  registerParameters(String[] parameters, ValueSanitizer valueSanitizer)
Register a value sanitizer for an array of parameters.
        void  setAllowUnregisteredParamaters(boolean allowUnregisteredParamaters)
Set whether or not unregistered parameters are allowed.
        void  setPreferFirstRepeatedParameter(boolean preferFirstRepeatedParameter)
Set whether or not the first occurrence of a repeated parameter is preferred.
        void  setUnregisteredParameterValueSanitizer(ValueSanitizer sanitizer)
Set the value sanitizer used when processing unregistered parameter values.
        String  unescape(String string)
Unescape an escaped string.

Protected Methods

        void  addSanitizedEntry(String parameter, String value)
Record a sanitized parameter-value pair.
        void  clear()
Clear the existing entries.
        int  decodeHexDigit(char c)
Convert a character that represents a hexidecimal digit into an integer.
        boolean  isHexDigit(char c)
Test if a character is a hexidecimal digit.
        void  parseEntry(String parameter, String value)
Parse an escaped parameter-value pair.
Methods inherited from class java.lang.Object

Details

Public Constructors

public UrlQuerySanitizer()

Constructs a UrlQuerySanitizer.

Defaults:

  • unregistered parameters are not allowed.
  • the last instance of a repeated parameter is preferred.
  • The default value sanitizer is an AllIllegal value sanitizer.

public UrlQuerySanitizer(String url)

Constructs a UrlQuerySanitizer and parse a URL. This constructor is provided for convenience when the default parsing behavior is acceptable.

Because the URL is parsed before the constructor returns, there isn't a chance to configure the sanitizer to change the parsing behavior.

UrlQuerySanitizer sanitizer = new UrlQuerySanitizer(myUrl); String name = sanitizer.getValue("name");

Defaults:

  • unregistered parameters are allowed.
  • the last instance of a repeated parameter is preferred.
  • The default value sanitizer is an AllIllegal value sanitizer.

Public Methods

public static final ValueSanitizer getAllButNulAndAngleBracketsLegal()

Return a value sanitizer that allows any special characters except angle brackets ('<' and '>') and Nul ('\0'). Allows script URLs.

Returns

  • a value sanitizer

public static final ValueSanitizer getAllButNulLegal()

Return a value sanitizer that allows everything except Nul ('\0') characters. Script URLs are allowed.

Returns

  • a value sanitizer

public static final ValueSanitizer getAllButWhitespaceLegal()

Return a value sanitizer that allows everything except Nul ('\0') characters, space (' '), and other whitespace characters. Script URLs are allowed.

Returns

  • a value sanitizer

public static final ValueSanitizer getAllIllegal()

Return a value sanitizer that does not allow any special characters, and also does not allow script URLs.

Returns

  • a value sanitizer

public boolean getAllowUnregisteredParamaters()

Get whether or not unregistered parameters are allowed. If not allowed, they will be dropped when a query is parsed.

Returns

  • true if unregistered parameters are allowed.

See Also

public static final ValueSanitizer getAmpAndSpaceLegal()

Return a value sanitizer that does not allow any special characters except ampersand ('&') and space (' '). Does not allow script URLs.

Returns

  • a value sanitizer

public static final ValueSanitizer getAmpLegal()

Return a value sanitizer that does not allow any special characters except ampersand ('&'). Does not allow script URLs.

Returns

  • a value sanitizer

public ValueSanitizer getEffectiveValueSanitizer(String parameter)

Get the effective value sanitizer for a parameter. Like getValueSanitizer, except if there is no value sanitizer registered for a parameter, and unregistered paramaters are allowed, then the default value sanitizer is returned.

Parameters

parameter an unescaped parameter

Returns

  • the effective value sanitizer for a parameter.

public List getParameterList()

An array list of all of the parameter value pairs in the sanitized query, in the order they appeared in the query. May contain duplicate parameters.

Note: Do not modify this list. Treat it as a read-only list.

public Set getParameterSet()

Get a set of all of the parameters found in the sanitized query.

Note: Do not modify this set. Treat it as a read-only set.

Returns

  • all the parameters found in the current query.

public boolean getPreferFirstRepeatedParameter()

Get whether or not the first occurrence of a repeated parameter is preferred.

Returns

  • true if the first occurrence of a repeated parameter is preferred.

See Also

public static final ValueSanitizer getSpaceLegal()

Return a value sanitizer that does not allow any special characters except space (' '). Does not allow script URLs.

Returns

  • a value sanitizer

public ValueSanitizer getUnregisteredParameterValueSanitizer()

Get the current value sanitizer used when processing unregistered parameter values.

Note: The default unregistered parameter value sanitizer is one that doesn't allow any special characters, similar to what is returned by calling createAllIllegal.

Returns

  • the current ValueSanitizer used to sanitize unregistered parameter values.

public static final ValueSanitizer getUrlAndSpaceLegal()

Return a value sanitizer that allows all the characters used by encoded URLs and allows spaces, which are not technically legal in encoded URLs, but commonly appear anyway. Does not allow script URLs.

Returns

  • a value sanitizer

public static final ValueSanitizer getUrlLegal()

Return a value sanitizer that allows all the characters used by encoded URLs. Does not allow script URLs.

Returns

  • a value sanitizer

public String getValue(String parameter)

Get the value for a parameter in the current sanitized query. Returns null if the parameter does not exit.

Parameters

parameter the unencoded name of a parameter.

Returns

  • the sanitized unencoded value of the parameter, or null if the parameter does not exist.

public ValueSanitizer getValueSanitizer(String parameter)

Get the value sanitizer for a parameter. Returns null if there is no value sanitizer registered for the parameter.

Parameters

parameter the unescaped parameter

Returns

  • the currently registered value sanitizer for this parameter.

See Also

public boolean hasParameter(String parameter)

Check if a parameter exists in the current sanitized query.

Parameters

parameter the unencoded name of a parameter.

Returns

  • true if the paramater exists in the current sanitized queary.

public void parseQuery(String query)

Parse a query. A query string is any number of parameter-value clauses separated by any non-zero number of ampersands. A parameter-value clause is a parameter followed by an equal sign, followed by a value. If the equal sign is missing, the value is assumed to be the empty string.

Parameters

query the query to parse.

public void parseUrl(String url)

Parse the query parameters out of an encoded URL. Works by extracting the query portion from the URL and then calling parseQuery(). If there is no query portion it is treated as if the query portion is an empty string.

Parameters

url the encoded URL to parse.

public void registerParameter(String parameter, ValueSanitizer valueSanitizer)

Register a value sanitizer for a particular parameter. Can also be used to replace or remove an already-set value sanitizer.

Registering a non-null value sanitizer for a particular parameter makes that parameter a registered parameter.

Parameters

parameter an unencoded parameter name
valueSanitizer the value sanitizer to use for a particular parameter. May be null in order to unregister that parameter.

See Also

public void registerParameters(String[] parameters, ValueSanitizer valueSanitizer)

Register a value sanitizer for an array of parameters.

Parameters

parameters An array of unencoded parameter names.

See Also

public void setAllowUnregisteredParamaters(boolean allowUnregisteredParamaters)

Set whether or not unregistered parameters are allowed. If they are not allowed, then they will be dropped when a query is sanitized.

Defaults to false.

Parameters

allowUnregisteredParamaters true to allow unregistered parameters.

See Also

public void setPreferFirstRepeatedParameter(boolean preferFirstRepeatedParameter)

Set whether or not the first occurrence of a repeated parameter is preferred. True means the first repeated parameter is preferred. False means that the last repeated parameter is preferred.

The preferred parameter is the one that is returned when getParameter is called.

defaults to false.

Parameters

preferFirstRepeatedParameter True if the first repeated parameter is preferred.

See Also

public void setUnregisteredParameterValueSanitizer(ValueSanitizer sanitizer)

Set the value sanitizer used when processing unregistered parameter values.

Parameters

sanitizer set the ValueSanitizer used to sanitize unregistered parameter values.

public String unescape(String string)

Unescape an escaped string.
  • '+' characters are replaced by ' ' characters.
  • Valid "%xx" escape sequences are replaced by the corresponding unescaped character.
  • Invalid escape sequences such as %1z", are passed through unchanged.

      Parameters

      string the escaped string

      Returns

      • the unescaped string.

Protected Methods

protected void addSanitizedEntry(String parameter, String value)

Record a sanitized parameter-value pair. Override if you want to do additional filtering or validation.

Parameters

parameter an unescaped parameter
value a sanitized unescaped value

protected void clear()

Clear the existing entries. Called to get ready to parse a new query string.

protected int decodeHexDigit(char c)

Convert a character that represents a hexidecimal digit into an integer. If the character is not a hexidecimal digit, then -1 is returned. Both upper case and lower case hex digits are allowed.

Parameters

c the hexidecimal digit.

Returns

  • the integer value of the hexidecimal digit.

protected boolean isHexDigit(char c)

Test if a character is a hexidecimal digit. Both upper case and lower case hex digits are allowed.

Parameters

c the character to test

Returns

  • true if c is a hex digit.

protected void parseEntry(String parameter, String value)

Parse an escaped parameter-value pair. The default implementation unescapes both the parameter and the value, then looks up the effective value sanitizer for the parameter and uses it to sanitize the value. If all goes well then addSanitizedValue is called with the unescaped parameter and the sanitized unescaped value.

Parameters

parameter an escaped parameter
value an unsanitzied escaped value
Build m5-rc15i - 10 Jun 2008 13:54