Class BCodec
- All Implemented Interfaces:
Decoder,Encoder,StringDecoder,StringEncoder
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.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final CodecPolicyThe default decoding policy is lenient.private final CodecPolicyDecoding policy for the Base64 payload.Fields inherited from class org.apache.commons.codec.net.RFC1522Codec
charset, POSTFIX, PREFIX, SEP -
Constructor Summary
ConstructorsConstructorDescriptionBCodec()Constructs a new instance.Constructs a new instance for the selection of a default Charset.Constructs a new instance for the selection of a default Charset.BCodec(Charset charset, CodecPolicy decodingPolicy) Constructs a new instance for the selection of a default Charset. -
Method Summary
Modifier and TypeMethodDescriptionDecodes a Base64 object into its original form.Decodes a Base64 string into its original form.protected byte[]doDecoding(byte[] bytes) Decodes an array of bytes using the defined encoding scheme.protected byte[]doEncoding(byte[] bytes) Encodes an array of bytes using the defined encoding scheme.Encodes an object into its Base64 form using the default Charset.Encodes a string into its Base64 form using the default Charset.Encodes a string into its Base64 form using the specified Charset.Encodes a string into its Base64 form using the specified Charset.protected StringGets the codec name (referred to as encoding in the RFC 1522).booleanTests whether decoding requires a canonical Base64 payload.Methods inherited from class org.apache.commons.codec.net.RFC1522Codec
decodeText, encodeText, encodeText, getCharset, getDefaultCharset
-
Field Details
-
DECODING_POLICY_DEFAULT
The default decoding policy is lenient. -
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
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
Constructs a new instance for the selection of a default Charset.Use
CodecPolicy.STRICTto require canonical standard Base64 payloads. The other constructors useCodecPolicy.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
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
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)withCodecPolicy.STRICTfor canonical payload validation.- Specified by:
decodein interfaceDecoder- Parameters:
value- Base64 object to convert into its original form.- Returns:
- original object.
- Throws:
DecoderException- Thrown if the argument is not aString. Thrown if a failure condition is encountered during the decode process.
-
decode
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)withCodecPolicy.STRICTfor canonical payload validation.- Specified by:
decodein interfaceStringDecoder- 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
Decodes an array of bytes using the defined encoding scheme.- Specified by:
doDecodingin classRFC1522Codec- 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:RFC1522CodecEncodes an array of bytes using the defined encoding scheme.- Specified by:
doEncodingin classRFC1522Codec- Parameters:
bytes- Data to be encoded.- Returns:
- A byte array containing the encoded data.
-
encode
Encodes an object into its Base64 form using the default Charset. Unsafe characters are escaped.- Specified by:
encodein interfaceEncoder- 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
Encodes a string into its Base64 form using the default Charset. Unsafe characters are escaped.- Specified by:
encodein interfaceStringEncoder- 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
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 forvalue.- Returns:
- Base64 string.
- Throws:
EncoderException- Thrown if a failure condition is encountered during the encoding process.- Since:
- 1.7
-
encode
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 forvalue.- Returns:
- Base64 string.
- Throws:
EncoderException- Thrown if a failure condition is encountered during the encoding process.
-
getEncoding
Description copied from class:RFC1522CodecGets the codec name (referred to as encoding in the RFC 1522).- Specified by:
getEncodingin classRFC1522Codec- Returns:
- name of the codec.
-
isStrictDecoding
public boolean isStrictDecoding()Tests whether decoding requires a canonical Base64 payload.Strict decoding raises
DecoderExceptionfor 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
-