Package org.apache.commons.codec.net

Class URLCodec

java.lang.Object

org.apache.commons.codec.net.URLCodec

All Implemented Interfaces:

BinaryDecoder, BinaryEncoder, Decoder, Encoder, StringDecoder, StringEncoder

public class URLCodec
extends java.lang.Object
implements BinaryEncoder, BinaryDecoder, StringEncoder, StringDecoder

Implements the 'www-form-urlencoded' encoding scheme, also misleadingly known as URL encoding.

This codec is meant to be a replacement for standard Java classes URLEncoder and URLDecoder on older Java platforms, as these classes in Java versions below 1.4 rely on the platform's default charset encoding.

This class is thread-safe as of 1.11

Since:

1.2

See Also:

Chapter 17.13.4 Form content types of the HTML 4.01 Specification

Field Summary

Fields

Modifier and Type	Field	Description
protected java.lang.String	charset	Deprecated. TODO: This field will be changed to a private final Charset in 2.0.
protected static byte	ESCAPE_CHAR	Release 1.5 made this field final.
protected static java.util.BitSet	WWW_FORM_URL	Deprecated. 1.11 Will be removed in 2.0 (CODEC-230)

Constructor Summary

Constructors

Constructor	Description
URLCodec()	Default constructor.
URLCodec(java.lang.String charset)	Constructs a new instance for the selection of a default charset.

Method Summary

Modifier and Type	Method	Description
byte[]	decode(byte[] bytes)	Decodes an array of URL safe 7-bit characters into an array of original bytes.
java.lang.Object	decode(java.lang.Object obj)	Decodes a URL safe object into its original form.
java.lang.String	decode(java.lang.String str)	Decodes a URL safe string into its original form using the default string charset.
java.lang.String	decode(java.lang.String str, java.lang.String charsetName)	Decodes a URL safe string into its original form using the specified encoding.
static byte[]	decodeUrl(byte[] bytes)	Decodes an array of URL safe 7-bit characters into an array of original bytes.
static byte[]	decodeUrl(java.util.BitSet urlsafe, byte[] bytes)	Decodes an array of bytes using the safe set supplied to encodeUrl(BitSet, byte[]).
byte[]	encode(byte[] bytes)	Encodes an array of bytes into an array of URL safe 7-bit characters.
java.lang.Object	encode(java.lang.Object obj)	Encodes an object into its URL safe form.
java.lang.String	encode(java.lang.String str)	Encodes a string into its URL safe form using the default string charset.
java.lang.String	encode(java.lang.String str, java.lang.String charsetName)	Encodes a string into its URL safe form using the specified string charset.
static byte[]	encodeUrl(java.util.BitSet urlsafe, byte[] bytes)	Encodes an array of bytes using the given set of URL safe characters.
java.lang.String	getDefaultCharset()	Gets the default charset used for string decoding and encoding.
java.lang.String	getEncoding()	Deprecated. Use getDefaultCharset(), will be removed in 2.0.

Methods inherited from class java.lang.Object

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

Field Detail

ESCAPE_CHAR

protected static final byte ESCAPE_CHAR

Release 1.5 made this field final.

See Also:

Constant Field Values

WWW_FORM_URL

@Deprecated
protected static final java.util.BitSet WWW_FORM_URL

Deprecated.

1.11 Will be removed in 2.0 (CODEC-230)

BitSet of www-form-url safe characters. This is a copy of the internal BitSet which is now used for the conversion. Changes to this field are ignored.

charset

@Deprecated
protected volatile java.lang.String charset

Deprecated.

TODO: This field will be changed to a private final Charset in 2.0. (CODEC-126)

The default charset used for string decoding and encoding.

Constructor Detail

URLCodec

public URLCodec()

Default constructor.

URLCodec

public URLCodec(java.lang.String charset)

Constructs a new instance for the selection of a default charset.

Parameters:

charset - The default string charset to use.

Method Detail

decodeUrl

public static final byte[] decodeUrl(java.util.BitSet urlsafe,
                                     byte[] bytes)
                              throws DecoderException

Decodes an array of bytes using the safe set supplied to encodeUrl(BitSet, byte[]).

A percent sign marked safe is copied literally; otherwise it starts a two-digit hexadecimal escape. A plus sign marked safe is copied literally. Otherwise, a plus sign becomes a space only if space is marked safe. All other bytes are copied unchanged. A null bitset selects the default www-form-urlencoded safe set, giving the same behavior as decodeUrl(byte[]).

Not every safe set permits a round trip. If both space and plus are marked safe, the encoder maps both to plus and this method preserves that plus. If percent is marked safe, literal percent signs cannot be distinguished from generated escapes, so this method preserves all percent signs, including generated escapes. Use a safe set that excludes percent and does not mark both space and plus safe when a round trip is required.

Parameters:

urlsafe - bitset of characters deemed URL safe during encoding, or null to use the default safe set.

bytes - array of encoded bytes, or null.

Returns:

array of decoded bytes, or null if the input is null.

Throws:

DecoderException - if percent is not marked safe and an escape is incomplete or contains invalid hexadecimal digits.

Since:

1.23.0

decodeUrl

public static final byte[] decodeUrl(byte[] bytes)
                              throws DecoderException

Decodes an array of URL safe 7-bit characters into an array of original bytes. Escaped characters are converted back to their original representation.

Decoding always follows www-form-urlencoded rules: + becomes a space and % starts a hexadecimal escape. Output from encodeUrl(BitSet, byte[]) with a custom safe set may therefore not decode back to the original input and may cause a DecoderException, depending on which characters were marked safe.

Parameters:

bytes - array of URL safe characters.

Returns:

array of original bytes.

Throws:

DecoderException - Thrown if URL decoding is unsuccessful.

encodeUrl

public static final byte[] encodeUrl(java.util.BitSet urlsafe,
                                     byte[] bytes)

Encodes an array of bytes using the given set of URL safe characters.

Unsafe characters are percent-escaped. Characters marked safe are copied unchanged, except that a space marked safe is converted to +. A null bitset selects the default www-form-urlencoded safe set, which escapes both % and +.

A custom bitset can produce output that decodeUrl(byte[]) and the decode methods cannot decode back to the original input. These decoders always convert + to a space and interpret % as the start of a hexadecimal escape, regardless of the bitset used for encoding. If the custom bitset marks either character safe, decoding can change the original data or throw DecoderException. Callers using a custom bitset can use decodeUrl(BitSet, byte[]) with the same bitset, subject to its documented limitations for ambiguous safe sets.

Parameters:

urlsafe - bitset of characters deemed URL safe, or null to use the default www-form-urlencoded safe set.

bytes - array of bytes to convert to URL safe characters.

Returns:

array of bytes containing URL safe characters.

decode

public byte[] decode(byte[] bytes)
              throws DecoderException

Decodes an array of URL safe 7-bit characters into an array of original bytes. Escaped characters are converted back to their original representation.

Decoding always follows www-form-urlencoded rules: + becomes a space and % starts a hexadecimal escape. Output from encodeUrl(BitSet, byte[]) with a custom safe set may therefore not decode back to the original input and may cause a DecoderException, depending on which characters were marked safe.

Specified by:

decode in interface BinaryDecoder

Parameters:

bytes - array of URL safe characters.

Returns:

array of original bytes.

Throws:

DecoderException - Thrown if URL decoding is unsuccessful.

decode

public java.lang.Object decode(java.lang.Object obj)
                        throws DecoderException

Decodes a URL safe object into its original form. Escaped characters are converted back to their original representation.

Decoding always follows www-form-urlencoded rules: + becomes a space and % starts a hexadecimal escape. Output from encodeUrl(BitSet, byte[]) with a custom safe set may therefore not decode back to the original input and may cause a DecoderException, depending on which characters were marked safe.

Specified by:

decode in interface Decoder

Parameters:

obj - URL safe object to convert into its original form.

Returns:

original object.

Throws:

DecoderException - Thrown if the argument is not a String or byte[]. Thrown if a failure condition is encountered during the decode process.

decode

public java.lang.String decode(java.lang.String str)
                        throws DecoderException

Decodes a URL safe string into its original form using the default string charset. Escaped characters are converted back to their original representation.

Decoding always follows www-form-urlencoded rules: + becomes a space and % starts a hexadecimal escape. Output from encodeUrl(BitSet, byte[]) with a custom safe set may therefore not decode back to the original input and may cause a DecoderException, depending on which characters were marked safe.

Specified by:

decode in interface StringDecoder

Parameters:

str - URL safe string to convert into its original form.

Returns:

original string.

Throws:

DecoderException - Thrown if URL decoding is unsuccessful.

See Also:

getDefaultCharset()

decode

public java.lang.String decode(java.lang.String str,
                               java.lang.String charsetName)
                        throws DecoderException,
                               java.io.UnsupportedEncodingException

Decodes a URL safe string into its original form using the specified encoding. Escaped characters are converted back to their original representation.

Decoding always follows www-form-urlencoded rules: + becomes a space and % starts a hexadecimal escape. Output from encodeUrl(BitSet, byte[]) with a custom safe set may therefore not decode back to the original input and may cause a DecoderException, depending on which characters were marked safe.

Parameters:

str - URL safe string to convert into its original form.

charsetName - the original string charset.

Returns:

original string.

Throws:

DecoderException - Thrown if URL decoding is unsuccessful.

java.io.UnsupportedEncodingException - Thrown if charset is not supported.

encode

public byte[] encode(byte[] bytes)

Encodes an array of bytes into an array of URL safe 7-bit characters. Unsafe characters are escaped.

Specified by:

encode in interface BinaryEncoder

Parameters:

bytes - array of bytes to convert to URL safe characters.

Returns:

array of bytes containing URL safe characters.

encode

public java.lang.Object encode(java.lang.Object obj)
                        throws EncoderException

Encodes an object into its URL safe form. Unsafe characters are escaped.

Specified by:

encode in interface Encoder

Parameters:

obj - string to convert to a URL safe form.

Returns:

URL safe object.

Throws:

EncoderException - Thrown if URL encoding is not applicable to objects of this type or if encoding is unsuccessful.

encode

public java.lang.String encode(java.lang.String str)
                        throws EncoderException

Encodes a string into its URL safe form using the default string charset. Unsafe characters are escaped.

Specified by:

encode in interface StringEncoder

Parameters:

str - string to convert to a URL safe form.

Returns:

URL safe string.

Throws:

EncoderException - Thrown if URL encoding is unsuccessful.

See Also:

getDefaultCharset()

encode

public java.lang.String encode(java.lang.String str,
                               java.lang.String charsetName)
                        throws java.io.UnsupportedEncodingException

Encodes a string into its URL safe form using the specified string charset. Unsafe characters are escaped.

Parameters:

str - string to convert to a URL safe form.

charsetName - the charset for str.

Returns:

URL safe string.

Throws:

java.io.UnsupportedEncodingException - Thrown if charset is not supported.

getDefaultCharset

public java.lang.String getDefaultCharset()

Gets the default charset used for string decoding and encoding.

Returns:

The default string charset.

getEncoding

@Deprecated
public java.lang.String getEncoding()

Deprecated.

Use getDefaultCharset(), will be removed in 2.0.

Gets the String encoding used for decoding and encoding.

Returns:

The encoding.