public class

FastURLEncoder

extends Object
java.lang.Object
   ↳ com.google.gdata.util.httputil.FastURLEncoder

Class Overview

This class has been deprecated; use uriEscaper(), cppUriEscaper() or create your own custom PercentEscaper.

Almost every use of FastURLEncoder can now be replaced with an instance of the PercentEscaper class, which is much faster.

In most cases it should be possible to use the static instances available from CharEscapers but it is also possible to create your own escaper with custom behaviour.

See Deprecating FastURLEncoder for more information.

Note that the new uriEscaper only escapes using UTF-8 encoding and while no examples of other encodings were found when preparing this class for deprecation, it's possible that some instance were missed. If you have a valid reason to escape URIs via an encoding other than UTF-8 please let the java-libraries-team know.

FastURLEncoder is intended as a replacement for the slow and inefficient java.net.URLEncoder. There are a few differences though:

  • URLEncoder.encode(String) uses the platform's default encoding while FastURLEncoder.encode(String) always uses UTF-8. The default encoding is unpredictable and so it shouldn't be used anyway.
  • FastURLEncoder allocates much less memory. In my tests I escaped 81735 bytes of data 20 bytes at a time. URLEncoder allocated over 200 MB! FastURLEncoder allocated much less (probably about 500 kB).
  • FastURLEncoder is over 30 times as fast.
  • FastURLEncoder (optionally) lets you specify which octets should and shouldn't be escaped and also whether spaces should be escaped as "+" or "%20".

It is possible that URLEncoder is doing really complicated stuff for a reason and that I just don't understand why. If you are unsure of FastURLEncoder just call FastURLEncoder.setVerifyAgainstJava(true). This will run both versions and verify that the outputs are the same. Of course this will be slow but it is useful for testing. I wouldn't be surprised if the two differ for non-latin1, non-utf-8 encodings.

FastURLEncoder requires jdk 1.5.

See Also
  • java.net.URLEncoder

Summary

Fields
public static final BitSet CPLUSPLUS_COMPAT_SAFE_OCTETS This field is deprecated. Use cppUriEscaper()
private static final BitSet DEFAULT_SAFE_OCTETS These octets all go directly into the URL, all others are escaped.
private static final char[] HEX_DIGITS java.net.URLEncoder uses upper-case hex digits so we should too.
private static boolean verifyAgainstJava
Public Methods
static BitSet createSafeOctetBitSet()
This method is deprecated. Use uriEscaper(). or create an instance of PercentEscaper. See FastURLEncoder for more details.
static boolean encode(String s, String encoding, BitSet safeOctets, boolean plusForSpace, Appendable out)
This method is deprecated. Use uriEscaper() or create an instance of PercentEscaper. See FastURLEncoder for more details.
static void encode(String s, Appendable out)
This method is deprecated. Use uriEscaper(). See FastURLEncoder for more details.
static String encode(String s, String encoding, BitSet safeOctets, boolean plusForSpace)
This method is deprecated. Use uriEscaper() or create an instance of PercentEscaper. See FastURLEncoder for more details.
static void encode(String s, String encoding, Appendable out)
This method is deprecated. Use uriEscaper(). See FastURLEncoder for more details.
static String encode(String s, String encoding)
This method is deprecated. Use uriEscaper(). See FastURLEncoder for more details.
static String encode(String s, BitSet safeOctets, boolean plusForSpace)
This method is deprecated. Use uriEscaper(). or create an instance of PercentEscaper. See FastURLEncoder for more details.
static String encode(String s)
This method is deprecated. Use uriEscaper().
[Expand]
Inherited Methods
From class java.lang.Object

Fields

public static final BitSet CPLUSPLUS_COMPAT_SAFE_OCTETS

This field is deprecated.
Use cppUriEscaper()

These octets mimic the ones escaped by the C++ webutil/url URL class -- the kGoogle1Escape set. To produce the same escaping as C++, use this BitSet with the plusForSpace option.

private static final BitSet DEFAULT_SAFE_OCTETS

These octets all go directly into the URL, all others are escaped.

private static final char[] HEX_DIGITS

java.net.URLEncoder uses upper-case hex digits so we should too.

private static boolean verifyAgainstJava

Public Methods

public static BitSet createSafeOctetBitSet ()

This method is deprecated.
Use uriEscaper(). or create an instance of PercentEscaper. See FastURLEncoder for more details.

Instead of retrieving this set to add your own safe characters, simply provide your additional safe characters to the PercentEscaper(String, boolean) constructor. If you don't need to add your own safe characters, just use uriEscaper().

Returns

public static boolean encode (String s, String encoding, BitSet safeOctets, boolean plusForSpace, Appendable out)

This method is deprecated.
Use uriEscaper() or create an instance of PercentEscaper. See FastURLEncoder for more details.

URL-escapes s by encoding it with the specified character encoding, escaping all octets not included in safeOctets, and then outputting the result to an Appendable.

Parameters
s String to encode.
encoding Character encoding to use (e.g., "UTF-8")
safeOctets Set of octets that should not be escaped.
plusForSpace Whether octet 0x20, i.e. "space", should be encoded as a plus sign rather than "%20". Note that this parameter is effectively ignored if 0x20 is in safeOctets.
out The Appendable destination for the encoded string.
Returns
  • true if s did need escaping, false otherwise. In other words, this returns false only if s was output to out verbatim.
Throws
UnsupportedEncodingException if encoding is not supported.
IOException if out does so when appended to.

public static void encode (String s, Appendable out)

This method is deprecated.
Use uriEscaper(). See FastURLEncoder for more details.

Shortcut for encode(s, "UTF-8", out). This is very similiar to java.net.URLEncoder.encode() except that it uses UTF-8 instead of the platform's default encoding.

Parameters
s String to encode.
out The Appendable destination for the encoded string.
Throws
IOException
See Also

public static String encode (String s, String encoding, BitSet safeOctets, boolean plusForSpace)

This method is deprecated.
Use uriEscaper() or create an instance of PercentEscaper. See FastURLEncoder for more details.

URL-escapes s by encoding it with the specified character encoding, and then escaping all octets not included in safeOctets.

Parameters
s String to encode.
encoding Character encoding to use (e.g., "UTF-8")
safeOctets Set of octets that should not be escaped.
plusForSpace Whether octet 0x20, i.e. "space", should be encoded as a plus sign rather than "%20". Note that this parameter is effectively ignored if 0x20 is in safeOctets.
Returns
  • the encoded version of s. Will return s itself if no encoding is necessary.
Throws
UnsupportedEncodingException if encoding is not supported.

public static void encode (String s, String encoding, Appendable out)

This method is deprecated.
Use uriEscaper(). See FastURLEncoder for more details.

This should be a direct replacement for java.net.URLEncoder.encode(), but appends its output to an Appendable.

Parameters
s String to encode.
encoding Character encoding to use (e.g., "UTF-8")
out The Appendable destination for the encoded string.
Throws
UnsupportedEncodingException if encoding is not supported.
IOException if out does so when appended to.
See Also

public static String encode (String s, String encoding)

This method is deprecated.
Use uriEscaper(). See FastURLEncoder for more details.

This should be a direct replacement for java.net.URLEncoder.encode().

Parameters
s String to encode.
encoding Character encoding to use (e.g., "UTF-8")
Throws
UnsupportedEncodingException
See Also

public static String encode (String s, BitSet safeOctets, boolean plusForSpace)

This method is deprecated.
Use uriEscaper(). or create an instance of PercentEscaper. See FastURLEncoder for more details.

Shortcut for encode(s, "UTF-8"). This is very similiar to java.net.URLEncoder.encode() except that it uses UTF-8 instead of the platform's default encoding.

Parameters
s String to encode.
safeOctets Set of octets that should not be escaped.
plusForSpace Whether octet 0x20, i.e., "space", should be encoded as a plus sign rather than "%20". Note that this parameter is effectively ignored if 0x20 is in safeOctets.
See Also

public static String encode (String s)

This method is deprecated.
Use uriEscaper().

Shortcut for encode(s, "UTF-8"). This is very similiar to java.net.URLEncoder.encode() except that it uses UTF-8 instead of the platform's default encoding.

Parameters
s String to encode.
See Also