URLCodec (Apache Commons Codec 1.22.1 API)
Description: declaration: package: org.apache.commons.codec.net, class: URLCodec

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 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 String`
  `charset`
  Deprecated.
  TODO: This field will be changed to a private final Charset in 2.0.
  `protected static final byte`
  `ESCAPE_CHAR`
  Release 1.5 made this field final.
  `protected static final BitSet`
  `WWW_FORM_URL`
  Deprecated.
  1.11 Will be removed in 2.0 (CODEC-230)

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `URLCodec()`
  Default constructor.
  `URLCodec(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.
  `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 charsetName)`
  Decodes a URL safe string into its original form using the specified encoding.
  `static final 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 charsetName)`
  Encodes a string into its URL safe form using the specified string charset.
  `static final 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 Details

  - ### 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 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 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 Details

  - ### URLCodec

    public URLCodec()
    Default constructor.

  - ### URLCodec

    public URLCodec(String charset)
    Constructs a new instance for the selection of a default charset.
    Parameters:
      `charset` - The default string charset to use.

- ## Method Details

  - ### 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.

  - ### 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. The characters `%` and `+` are always escaped because `decodeUrl(byte[])` treats them as URL-encoding syntax.
    Parameters:
      `urlsafe` - bitset of characters deemed URL safe, except for `%` and `+`.
      `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.

  - ### 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.

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

  - ### decode

    public String decode(String str, String charsetName) 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.
      `charsetName` - the original string charset.
    Returns:
      original string.
    Throws:
      `DecoderException` - Thrown if URL decoding is unsuccessful.
      `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 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.

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

  - ### encode

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

  - ### 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:
      The encoding.