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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `URLCodec()` Default constructor.
    `URLCodec(String charset)` Constructor which allows for the selection of a default charset.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and 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 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 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 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.

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

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

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

    - #### 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–2023 The Apache Software Foundation. All rights reserved.