Class BCodec

java.lang.Object
org.apache.commons.codec.net.RFC1522Codec
org.apache.commons.codec.net.BCodec
All Implemented Interfaces:
Decoder, Encoder, StringDecoder, StringEncoder

public class BCodec extends RFC1522Codec implements StringEncoder, StringDecoder
Identical to the Base64 encoding defined by RFC 1521 and allows a character set to be specified.

RFC 1522 describes techniques to allow the encoding of non-ASCII text in various portions of a RFC 822 [2] message header, in a manner which is unlikely to confuse existing message handling software.

This class is immutable and thread-safe.

Decoding is lenient by default: the Base64 payload can contain ignored characters, noncanonical padding or trailing bits, and data after padding. Different encoded words can therefore decode to the same text. To require a canonical Base64 payload, select CodecPolicy.STRICT:

 BCodec codec = new BCodec(StandardCharsets.UTF_8, CodecPolicy.STRICT);
 

Strict decoding requires the standard Base64 alphabet, padding for partial blocks, and no whitespace within the payload. Invalid payloads cause a DecoderException. This validates the Base64 payload only; it does not establish a unique representation of the complete encoded word or message header, including its charset label. Applications comparing header values for security decisions must use a consistent representation, and signature verification must follow the signing protocol.

Since:
1.3
See Also:
  • Field Details

    • DECODING_POLICY_DEFAULT

      private static final CodecPolicy DECODING_POLICY_DEFAULT
      The default decoding policy is lenient.
    • decodingPolicy

      private final CodecPolicy decodingPolicy
      Decoding policy for the Base64 payload. The default is lenient; strict decoding requires a canonical payload.
  • Constructor Details

    • BCodec

      public BCodec()
      Constructs a new instance.
    • BCodec

      public BCodec(Charset charset)
      Constructs a new instance for the selection of a default Charset.
      Parameters:
      charset - the default string Charset to use.
      Since:
      1.7
      See Also:
    • BCodec

      public BCodec(Charset charset, CodecPolicy decodingPolicy)
      Constructs a new instance for the selection of a default Charset.

      Use CodecPolicy.STRICT to require canonical standard Base64 payloads. The other constructors use CodecPolicy.LENIENT. This policy applies to the Base64 payload, not the complete encoded word; see the class documentation.

      Parameters:
      charset - the default string Charset to use.
      decodingPolicy - The decoding policy.
      Since:
      1.15
      See Also:
    • BCodec

      public BCodec(String charsetName)
      Constructs a new instance for the selection of a default Charset.
      Parameters:
      charsetName - the default Charset to use.
      Throws:
      UnsupportedCharsetException - Thrown if the named Charset is unavailable.
      Since:
      1.7 throws UnsupportedCharsetException if the named Charset is unavailable
      See Also:
  • Method Details

    • decode

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

      Uses the decoding policy selected at construction. The default is lenient and does not require a canonical Base64 payload. Use BCodec(Charset, CodecPolicy) with CodecPolicy.STRICT for canonical payload validation.

      Specified by:
      decode in interface Decoder
      Parameters:
      value - Base64 object to convert into its original form.
      Returns:
      original object.
      Throws:
      DecoderException - Thrown if the argument is not a String. Thrown if a failure condition is encountered during the decode process.
    • decode

      public String decode(String value) throws DecoderException
      Decodes a Base64 string into its original form. Escaped characters are converted back to their original representation.

      Uses the decoding policy selected at construction. The default is lenient and does not require a canonical Base64 payload. Use BCodec(Charset, CodecPolicy) with CodecPolicy.STRICT for canonical payload validation.

      Specified by:
      decode in interface StringDecoder
      Parameters:
      value - Base64 string to convert into its original form.
      Returns:
      original string.
      Throws:
      DecoderException - Thrown if a failure condition is encountered during the decoding process.
    • doDecoding

      protected byte[] doDecoding(byte[] bytes) throws DecoderException
      Decodes an array of bytes using the defined encoding scheme.
      Specified by:
      doDecoding in class RFC1522Codec
      Parameters:
      bytes - Data to be decoded.
      Returns:
      A byte array that contains decoded data.
      Throws:
      IllegalArgumentException - Thrown when a problem is detected processing data.
      DecoderException - Thrown if a Decoder encounters a failure condition during the decode process.
    • doEncoding

      protected byte[] doEncoding(byte[] bytes)
      Description copied from class: RFC1522Codec
      Encodes an array of bytes using the defined encoding scheme.
      Specified by:
      doEncoding in class RFC1522Codec
      Parameters:
      bytes - Data to be encoded.
      Returns:
      A byte array containing the encoded data.
    • encode

      public Object encode(Object value) throws EncoderException
      Encodes an object into its Base64 form using the default Charset. Unsafe characters are escaped.
      Specified by:
      encode in interface Encoder
      Parameters:
      value - object to convert to Base64 form.
      Returns:
      Base64 object.
      Throws:
      EncoderException - Thrown if a failure condition is encountered during the encoding process.
    • encode

      public String encode(String strSource) throws EncoderException
      Encodes a string into its Base64 form using the default Charset. Unsafe characters are escaped.
      Specified by:
      encode in interface StringEncoder
      Parameters:
      strSource - string to convert to Base64 form.
      Returns:
      Base64 string.
      Throws:
      EncoderException - Thrown if a failure condition is encountered during the encoding process.
    • encode

      public String encode(String strSource, Charset sourceCharset) throws EncoderException
      Encodes a string into its Base64 form using the specified Charset. Unsafe characters are escaped.
      Parameters:
      strSource - string to convert to Base64 form.
      sourceCharset - the Charset for value.
      Returns:
      Base64 string.
      Throws:
      EncoderException - Thrown if a failure condition is encountered during the encoding process.
      Since:
      1.7
    • encode

      public String encode(String strSource, String sourceCharset) throws EncoderException
      Encodes a string into its Base64 form using the specified Charset. Unsafe characters are escaped.
      Parameters:
      strSource - string to convert to Base64 form.
      sourceCharset - the Charset for value.
      Returns:
      Base64 string.
      Throws:
      EncoderException - Thrown if a failure condition is encountered during the encoding process.
    • getEncoding

      protected String getEncoding()
      Description copied from class: RFC1522Codec
      Gets the codec name (referred to as encoding in the RFC 1522).
      Specified by:
      getEncoding in class RFC1522Codec
      Returns:
      name of the codec.
    • isStrictDecoding

      public boolean isStrictDecoding()
      Tests whether decoding requires a canonical Base64 payload.

      Strict decoding raises DecoderException for a noncanonical Base64 payload, including invalid alphabet characters, padding, or trailing bits. The default is lenient. This policy does not establish a canonical representation of the complete encoded word.

      Returns:
      true if using strict decoding.
      Since:
      1.15