org.apache.commons.codec.net
Class URLCodec

java.lang.Object
  extended by org.apache.commons.codec.net.URLCodec
All Implemented Interfaces:
BinaryDecoder, BinaryEncoder, Decoder, Encoder, StringDecoder, StringEncoder

public class URLCodec
extends 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 immutable and thread-safe.

Since:
1.2
Version:
$Id: URLCodec.html 889935 2013-12-11 05:05:13Z ggregory $
See Also:
"Chapter 17.13.4 'Form content types'" of the HTML 4.01 Specification

Field Summary
protected  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 BitSet WWW_FORM_URL
          BitSet of www-form-url safe characters.
 
Constructor Summary
URLCodec()
          Default constructor.
URLCodec(String charset)
          Constructor which allows for the selection of a default charset.
 
Method Summary
 byte[] decode(byte[] bytes)
          Decodes an array of URL safe 7-bit characters into an array of original bytes.
 Object decode(Object obj)
          Decodes a URL safe object into its original form.
 String decode(String str)
          Decodes a URL safe string into its original form using the default string charset.
 String decode(String str, String charset)
          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.
 byte[] encode(byte[] bytes)
          Encodes an array of bytes into an array of URL safe 7-bit characters.
 Object encode(Object obj)
          Encodes an object into its URL safe form.
 String encode(String str)
          Encodes a string into its URL safe form using the default string charset.
 String encode(String str, String charset)
          Encodes a string into its URL safe form using the specified string charset.
static byte[] encodeUrl(BitSet urlsafe, byte[] bytes)
          Encodes an array of bytes into an array of URL safe 7-bit characters.
 String getDefaultCharset()
          The default charset used for string decoding and encoding.
 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

charset

@Deprecated
protected String charset
Deprecated. TODO: This field will be changed to a private final Charset in 2.0.
The default charset used for string decoding and encoding.


ESCAPE_CHAR

protected static final byte ESCAPE_CHAR
Release 1.5 made this field final.

See Also:
Constant Field Values

WWW_FORM_URL

protected static final BitSet WWW_FORM_URL
BitSet of www-form-url safe characters.

Constructor Detail

URLCodec

public URLCodec()
Default constructor.


URLCodec

public URLCodec(String charset)
Constructor which allows for the selection of a default charset.

Parameters:
charset - the default string charset to use.
Method Detail

encodeUrl

public static final byte[] encodeUrl(BitSet urlsafe,
                                     byte[] bytes)
Encodes an array of bytes into an array of URL safe 7-bit characters. Unsafe characters are escaped.

Parameters:
urlsafe - bitset of characters deemed URL safe
bytes - array of bytes to convert to URL safe characters
Returns:
array of bytes containing URL safe characters

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.

Parameters:
bytes - array of URL safe characters
Returns:
array of original bytes
Throws:
DecoderException - Thrown if URL decoding is unsuccessful

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

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.

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

encode

public String encode(String str,
                     String charset)
              throws 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
charset - the charset for str
Returns:
URL safe string
Throws:
UnsupportedEncodingException - Thrown if charset is not supported

encode

public String encode(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()

decode

public String decode(String str,
                     String charset)
              throws DecoderException,
                     UnsupportedEncodingException
Decodes a URL safe string into its original form using the specified encoding. Escaped characters are converted back to their original representation.

Parameters:
str - URL safe string to convert into its original form
charset - the original string charset
Returns:
original string
Throws:
DecoderException - Thrown if URL decoding is unsuccessful
UnsupportedEncodingException - Thrown if charset is not supported

decode

public String decode(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.

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()

encode

public Object encode(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

decode

public Object decode(Object obj)
              throws DecoderException
Decodes a URL safe object into its original form. Escaped characters are converted back to their original representation.

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.

getDefaultCharset

public String getDefaultCharset()
The default charset used for string decoding and encoding.

Returns:
the default string charset.

getEncoding

@Deprecated
public String getEncoding()
Deprecated. Use getDefaultCharset(), will be removed in 2.0.

The String encoding used for decoding and encoding.

Returns:
Returns the encoding.


Copyright © 2002-2013 The Apache Software Foundation. All Rights Reserved.