Class QuotedPrintableCodec
- java.lang.Object
-
- org.apache.commons.codec.net.QuotedPrintableCodec
-
- All Implemented Interfaces:
BinaryDecoder
,BinaryEncoder
,Decoder
,Encoder
,StringDecoder
,StringEncoder
public class QuotedPrintableCodec extends java.lang.Object implements BinaryEncoder, BinaryDecoder, StringEncoder, StringDecoder
Codec for the Quoted-Printable section of RFC 1521.The Quoted-Printable encoding is intended to represent data that largely consists of octets that correspond to printable characters in the ASCII character set. It encodes the data in such a way that the resulting octets are unlikely to be modified by mail transport. If the data being encoded are mostly ASCII text, the encoded form of the data remains largely recognizable by humans. A body which is entirely ASCII may also be encoded in Quoted-Printable to ensure the integrity of the data should the message pass through a character- translating, and/or line-wrapping gateway.
Note:
Depending on the selected
strict
parameter, this class will implement a different set of rules of the quoted-printable spec:strict=false
: only rules #1 and #2 are implementedstrict=true
: all rules #1 through #5 are implemented
Originally, this class only supported the non-strict mode, but the codec in this partial form could already be used for certain applications that do not require quoted-printable line formatting (rules #3, #4, #5), for instance Q codec. The strict mode has been added in 1.10.
This class is immutable and thread-safe.
-
-
Field Summary
Fields Modifier and Type Field Description private java.nio.charset.Charset
charset
The default Charset used for string decoding and encoding.private static byte
CR
private static byte
ESCAPE_CHAR
private static byte
LF
private static java.util.BitSet
PRINTABLE_CHARS
BitSet of printable characters as defined in RFC 1521.private static int
SAFE_LENGTH
Safe line length for quoted printable encoded text.private static byte
SPACE
private boolean
strict
Indicates whether soft line breaks shall be used during encoding (rule #3-5).private static byte
TAB
-
Constructor Summary
Constructors Constructor Description QuotedPrintableCodec()
Default constructor, assumes default Charset ofStandardCharsets.UTF_8
QuotedPrintableCodec(boolean strict)
Constructor which allows for the selection of the strict mode.QuotedPrintableCodec(java.lang.String charsetName)
Constructor which allows for the selection of a default Charset.QuotedPrintableCodec(java.nio.charset.Charset charset)
Constructor which allows for the selection of a default Charset.QuotedPrintableCodec(java.nio.charset.Charset charset, boolean strict)
Constructor which allows for the selection of a default Charset and strict mode.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description byte[]
decode(byte[] bytes)
Decodes an array of quoted-printable characters into an array of original bytes.java.lang.Object
decode(java.lang.Object obj)
Decodes a quoted-printable object into its original form.java.lang.String
decode(java.lang.String sourceStr)
Decodes a quoted-printable string into its original form using the default string Charset.java.lang.String
decode(java.lang.String sourceStr, java.lang.String sourceCharset)
Decodes a quoted-printable string into its original form using the specified string Charset.java.lang.String
decode(java.lang.String sourceStr, java.nio.charset.Charset sourceCharset)
Decodes a quoted-printable string into its original form using the specified string Charset.static byte[]
decodeQuotedPrintable(byte[] bytes)
Decodes an array quoted-printable characters into an array of original bytes.byte[]
encode(byte[] bytes)
Encodes an array of bytes into an array of quoted-printable 7-bit characters.java.lang.Object
encode(java.lang.Object obj)
Encodes an object into its quoted-printable safe form.java.lang.String
encode(java.lang.String sourceStr)
Encodes a string into its quoted-printable form using the default string Charset.java.lang.String
encode(java.lang.String sourceStr, java.lang.String sourceCharset)
Encodes a string into its quoted-printable form using the specified Charset.java.lang.String
encode(java.lang.String sourceStr, java.nio.charset.Charset sourceCharset)
Encodes a string into its quoted-printable form using the specified Charset.private static int
encodeByte(int b, boolean encode, java.io.ByteArrayOutputStream buffer)
Write a byte to the buffer.private static int
encodeQuotedPrintable(int b, java.io.ByteArrayOutputStream buffer)
Encodes byte into its quoted-printable representation.static byte[]
encodeQuotedPrintable(java.util.BitSet printable, byte[] bytes)
Encodes an array of bytes into an array of quoted-printable 7-bit characters.static byte[]
encodeQuotedPrintable(java.util.BitSet printable, byte[] bytes, boolean strict)
Encodes an array of bytes into an array of quoted-printable 7-bit characters.java.nio.charset.Charset
getCharset()
Gets the default Charset name used for string decoding and encoding.java.lang.String
getDefaultCharset()
Gets the default Charset name used for string decoding and encoding.private static int
getUnsignedOctet(int index, byte[] bytes)
Return the byte at positionindex
of the byte array and make sure it is unsigned.private static boolean
isWhitespace(int b)
Checks whether the given byte is whitespace.
-
-
-
Field Detail
-
charset
private final java.nio.charset.Charset charset
The default Charset used for string decoding and encoding.
-
strict
private final boolean strict
Indicates whether soft line breaks shall be used during encoding (rule #3-5).
-
PRINTABLE_CHARS
private static final java.util.BitSet PRINTABLE_CHARS
BitSet of printable characters as defined in RFC 1521.
-
ESCAPE_CHAR
private static final byte ESCAPE_CHAR
- See Also:
- Constant Field Values
-
TAB
private static final byte TAB
- See Also:
- Constant Field Values
-
SPACE
private static final byte SPACE
- See Also:
- Constant Field Values
-
CR
private static final byte CR
- See Also:
- Constant Field Values
-
LF
private static final byte LF
- See Also:
- Constant Field Values
-
SAFE_LENGTH
private static final int SAFE_LENGTH
Safe line length for quoted printable encoded text.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
QuotedPrintableCodec
public QuotedPrintableCodec()
Default constructor, assumes default Charset ofStandardCharsets.UTF_8
-
QuotedPrintableCodec
public QuotedPrintableCodec(boolean strict)
Constructor which allows for the selection of the strict mode.- Parameters:
strict
- iftrue
, soft line breaks will be used- Since:
- 1.10
-
QuotedPrintableCodec
public QuotedPrintableCodec(java.nio.charset.Charset charset)
Constructor which allows for the selection of a default Charset.- Parameters:
charset
- the default string Charset to use.- Since:
- 1.7
-
QuotedPrintableCodec
public QuotedPrintableCodec(java.nio.charset.Charset charset, boolean strict)
Constructor which allows for the selection of a default Charset and strict mode.- Parameters:
charset
- the default string Charset to use.strict
- iftrue
, soft line breaks will be used- Since:
- 1.10
-
QuotedPrintableCodec
public QuotedPrintableCodec(java.lang.String charsetName) throws java.nio.charset.IllegalCharsetNameException, java.lang.IllegalArgumentException, java.nio.charset.UnsupportedCharsetException
Constructor which allows for the selection of a default Charset.- Parameters:
charsetName
- the default string Charset to use.- Throws:
java.nio.charset.UnsupportedCharsetException
- If no support for the named Charset is available in this instance of the Java virtual machinejava.lang.IllegalArgumentException
- If the given charsetName is nulljava.nio.charset.IllegalCharsetNameException
- If the given Charset name is illegal- Since:
- 1.7 throws UnsupportedCharsetException if the named Charset is unavailable
-
-
Method Detail
-
encodeQuotedPrintable
private static final int encodeQuotedPrintable(int b, java.io.ByteArrayOutputStream buffer)
Encodes byte into its quoted-printable representation.- Parameters:
b
- byte to encodebuffer
- the buffer to write to- Returns:
- The number of bytes written to the
buffer
-
getUnsignedOctet
private static int getUnsignedOctet(int index, byte[] bytes)
Return the byte at positionindex
of the byte array and make sure it is unsigned.- Parameters:
index
- position in the arraybytes
- the byte array- Returns:
- the unsigned octet at position
index
from the array
-
encodeByte
private static int encodeByte(int b, boolean encode, java.io.ByteArrayOutputStream buffer)
Write a byte to the buffer.- Parameters:
b
- byte to writeencode
- indicates whether the octet shall be encodedbuffer
- the buffer to write to- Returns:
- the number of bytes that have been written to the buffer
-
isWhitespace
private static boolean isWhitespace(int b)
Checks whether the given byte is whitespace.- Parameters:
b
- byte to be checked- Returns:
true
if the byte is either a space or tab character
-
encodeQuotedPrintable
public static final byte[] encodeQuotedPrintable(java.util.BitSet printable, byte[] bytes)
Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped.This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in RFC 1521 and is suitable for encoding binary data and unformatted text.
- Parameters:
printable
- bitset of characters deemed quoted-printablebytes
- array of bytes to be encoded- Returns:
- array of bytes containing quoted-printable data
-
encodeQuotedPrintable
public static final byte[] encodeQuotedPrintable(java.util.BitSet printable, byte[] bytes, boolean strict)
Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped.Depending on the selection of the
strict
parameter, this function either implements the full ruleset or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in RFC 1521 and is suitable for encoding binary data and unformatted text.- Parameters:
printable
- bitset of characters deemed quoted-printablebytes
- array of bytes to be encodedstrict
- iftrue
the full ruleset is used, otherwise only rule #1 and rule #2- Returns:
- array of bytes containing quoted-printable data
- Since:
- 1.10
-
decodeQuotedPrintable
public static final byte[] decodeQuotedPrintable(byte[] bytes) throws DecoderException
Decodes an array quoted-printable characters into an array of original bytes. Escaped characters are converted back to their original representation.This function fully implements the quoted-printable encoding specification (rule #1 through rule #5) as defined in RFC 1521.
- Parameters:
bytes
- array of quoted-printable characters- Returns:
- array of original bytes
- Throws:
DecoderException
- Thrown if quoted-printable decoding is unsuccessful
-
encode
public byte[] encode(byte[] bytes)
Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped.Depending on the selection of the
strict
parameter, this function either implements the full ruleset or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in RFC 1521 and is suitable for encoding binary data and unformatted text.- Specified by:
encode
in interfaceBinaryEncoder
- Parameters:
bytes
- array of bytes to be encoded- Returns:
- array of bytes containing quoted-printable data
-
decode
public byte[] decode(byte[] bytes) throws DecoderException
Decodes an array of quoted-printable characters into an array of original bytes. Escaped characters are converted back to their original representation.This function fully implements the quoted-printable encoding specification (rule #1 through rule #5) as defined in RFC 1521.
- Specified by:
decode
in interfaceBinaryDecoder
- Parameters:
bytes
- array of quoted-printable characters- Returns:
- array of original bytes
- Throws:
DecoderException
- Thrown if quoted-printable decoding is unsuccessful
-
encode
public java.lang.String encode(java.lang.String sourceStr) throws EncoderException
Encodes a string into its quoted-printable form using the default string Charset. Unsafe characters are escaped.Depending on the selection of the
strict
parameter, this function either implements the full ruleset or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in RFC 1521 and is suitable for encoding binary data and unformatted text.- Specified by:
encode
in interfaceStringEncoder
- Parameters:
sourceStr
- string to convert to quoted-printable form- Returns:
- quoted-printable string
- Throws:
EncoderException
- Thrown if quoted-printable encoding is unsuccessful- See Also:
getCharset()
-
decode
public java.lang.String decode(java.lang.String sourceStr, java.nio.charset.Charset sourceCharset) throws DecoderException
Decodes a quoted-printable string into its original form using the specified string Charset. Escaped characters are converted back to their original representation.- Parameters:
sourceStr
- quoted-printable string to convert into its original formsourceCharset
- the original string Charset- Returns:
- original string
- Throws:
DecoderException
- Thrown if quoted-printable decoding is unsuccessful- Since:
- 1.7
-
decode
public java.lang.String decode(java.lang.String sourceStr, java.lang.String sourceCharset) throws DecoderException, java.io.UnsupportedEncodingException
Decodes a quoted-printable string into its original form using the specified string Charset. Escaped characters are converted back to their original representation.- Parameters:
sourceStr
- quoted-printable string to convert into its original formsourceCharset
- the original string Charset- Returns:
- original string
- Throws:
DecoderException
- Thrown if quoted-printable decoding is unsuccessfuljava.io.UnsupportedEncodingException
- Thrown if Charset is not supported
-
decode
public java.lang.String decode(java.lang.String sourceStr) throws DecoderException
Decodes a quoted-printable string into its original form using the default string Charset. Escaped characters are converted back to their original representation.- Specified by:
decode
in interfaceStringDecoder
- Parameters:
sourceStr
- quoted-printable string to convert into its original form- Returns:
- original string
- Throws:
DecoderException
- Thrown if quoted-printable decoding is unsuccessful. Thrown if Charset is not supported.- See Also:
getCharset()
-
encode
public java.lang.Object encode(java.lang.Object obj) throws EncoderException
Encodes an object into its quoted-printable safe form. Unsafe characters are escaped.- Specified by:
encode
in interfaceEncoder
- Parameters:
obj
- string to convert to a quoted-printable form- Returns:
- quoted-printable object
- Throws:
EncoderException
- Thrown if quoted-printable encoding is not applicable to objects of this type or if encoding is unsuccessful
-
decode
public java.lang.Object decode(java.lang.Object obj) throws DecoderException
Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original representation.- Specified by:
decode
in interfaceDecoder
- Parameters:
obj
- quoted-printable object to convert into its original form- Returns:
- original object
- Throws:
DecoderException
- Thrown if the argument is not aString
orbyte[]
. Thrown if a failure condition is encountered during the decode process.
-
getCharset
public java.nio.charset.Charset getCharset()
Gets the default Charset name used for string decoding and encoding.- Returns:
- the default Charset name
- Since:
- 1.7
-
getDefaultCharset
public java.lang.String getDefaultCharset()
Gets the default Charset name used for string decoding and encoding.- Returns:
- the default Charset name
-
encode
public java.lang.String encode(java.lang.String sourceStr, java.nio.charset.Charset sourceCharset)
Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped.Depending on the selection of the
strict
parameter, this function either implements the full ruleset or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in RFC 1521 and is suitable for encoding binary data and unformatted text.- Parameters:
sourceStr
- string to convert to quoted-printable formsourceCharset
- the Charset for sourceStr- Returns:
- quoted-printable string
- Since:
- 1.7
-
encode
public java.lang.String encode(java.lang.String sourceStr, java.lang.String sourceCharset) throws java.io.UnsupportedEncodingException
Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped.Depending on the selection of the
strict
parameter, this function either implements the full ruleset or only a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in RFC 1521 and is suitable for encoding binary data and unformatted text.- Parameters:
sourceStr
- string to convert to quoted-printable formsourceCharset
- the Charset for sourceStr- Returns:
- quoted-printable string
- Throws:
java.io.UnsupportedEncodingException
- Thrown if the Charset is not supported
-
-