This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-codec.git
commit d9233f55d70aee9bd58b4a8200b157fba5946f4d Author: Gary Gregory <[email protected]> AuthorDate: Wed Dec 31 09:42:08 2025 -0500 Javadoc --- .../org/apache/commons/codec/StringDecoder.java | 9 +- .../org/apache/commons/codec/StringEncoder.java | 9 +- .../org/apache/commons/codec/language/Soundex.java | 107 +++----- .../commons/codec/net/QuotedPrintableCodec.java | 281 ++++++++------------- .../org/apache/commons/codec/net/RFC1522Codec.java | 74 +++--- .../java/org/apache/commons/codec/net/Utils.java | 13 +- 6 files changed, 187 insertions(+), 306 deletions(-) diff --git a/src/main/java/org/apache/commons/codec/StringDecoder.java b/src/main/java/org/apache/commons/codec/StringDecoder.java index 8ef1e88c..56b41c35 100644 --- a/src/main/java/org/apache/commons/codec/StringDecoder.java +++ b/src/main/java/org/apache/commons/codec/StringDecoder.java @@ -25,12 +25,9 @@ public interface StringDecoder extends Decoder { /** * Decodes a String and returns a String. * - * @param source - * the String to decode - * @return the encoded String - * @throws DecoderException - * thrown if there is an error condition during the Encoding process. + * @param source the String to decode. + * @return the encoded String. + * @throws DecoderException thrown if there is an error condition during the Encoding process. */ String decode(String source) throws DecoderException; } - diff --git a/src/main/java/org/apache/commons/codec/StringEncoder.java b/src/main/java/org/apache/commons/codec/StringEncoder.java index 9e0d3abc..7808d879 100644 --- a/src/main/java/org/apache/commons/codec/StringEncoder.java +++ b/src/main/java/org/apache/commons/codec/StringEncoder.java @@ -25,12 +25,9 @@ public interface StringEncoder extends Encoder { /** * Encodes a String and returns a String. * - * @param source - * the String to encode - * @return the encoded String - * @throws EncoderException - * thrown if there is an error condition during the encoding process. + * @param source the String to encode. + * @return the encoded String. + * @throws EncoderException thrown if there is an error condition during the encoding process. */ String encode(String source) throws EncoderException; } - diff --git a/src/main/java/org/apache/commons/codec/language/Soundex.java b/src/main/java/org/apache/commons/codec/language/Soundex.java index bdf09957..34c4ca9e 100644 --- a/src/main/java/org/apache/commons/codec/language/Soundex.java +++ b/src/main/java/org/apache/commons/codec/language/Soundex.java @@ -21,21 +21,20 @@ import org.apache.commons.codec.EncoderException; import org.apache.commons.codec.StringEncoder; /** - * Encodes a string into a Soundex value. Soundex is an encoding used to relate similar names, but can also be used as a - * general purpose scheme to find word with similar phonemes. + * Encodes a string into a Soundex value. Soundex is an encoding used to relate similar names, but can also be used as a general purpose scheme to find word + * with similar phonemes. * - * <p>This class is thread-safe. - * Although not strictly immutable, the mutable fields are not actually used.</p> + * <p> + * This class is thread-safe. Although not strictly immutable, the mutable fields are not actually used. + * </p> */ public class Soundex implements StringEncoder { /** - * The marker character used to indicate a silent (ignored) character. - * These are ignored except when they appear as the first character. + * The marker character used to indicate a silent (ignored) character. These are ignored except when they appear as the first character. * <p> - * Note: The {@link #US_ENGLISH_MAPPING_STRING} does not use this mechanism - * because changing it might break existing code. Mappings that don't contain - * a silent marker code are treated as though H and W are silent. + * Note: The {@link #US_ENGLISH_MAPPING_STRING} does not use this mechanism because changing it might break existing code. Mappings that don't contain a + * silent marker code are treated as though H and W are silent. * </p> * <p> * To override this, use the {@link #Soundex(String, boolean)} constructor. @@ -46,46 +45,38 @@ public class Soundex implements StringEncoder { public static final char SILENT_MARKER = '-'; /** - * This is a default mapping of the 26 letters used in US English. A value of {@code 0} for a letter position - * means do not encode, but treat as a separator when it occurs between consonants with the same code. + * This is a default mapping of the 26 letters used in US English. A value of {@code 0} for a letter position means do not encode, but treat as a separator + * when it occurs between consonants with the same code. * <p> - * (This constant is provided as both an implementation convenience and to allow Javadoc to pick - * up the value for the constant values page.) + * (This constant is provided as both an implementation convenience and to allow Javadoc to pick up the value for the constant values page.) * </p> * <p> - * <strong>Note that letters H and W are treated specially.</strong> - * They are ignored (after the first letter) and don't act as separators - * between consonants with the same code. + * <strong>Note that letters H and W are treated specially.</strong> They are ignored (after the first letter) and don't act as separators between + * consonants with the same code. * </p> */ public static final String US_ENGLISH_MAPPING_STRING = "01230120022455012623010202"; /** - * This is a default mapping of the 26 letters used in US English. A value of {@code 0} for a letter position - * means do not encode. + * This is a default mapping of the 26 letters used in US English. A value of {@code 0} for a letter position means do not encode. * * @see Soundex#Soundex(char[]) */ private static final char[] US_ENGLISH_MAPPING = US_ENGLISH_MAPPING_STRING.toCharArray(); /** - * An instance of Soundex using the US_ENGLISH_MAPPING mapping. - * This treats H and W as silent letters. - * Apart from when they appear as the first letter, they are ignored. - * They don't act as separators between duplicate codes. + * An instance of Soundex using the US_ENGLISH_MAPPING mapping. This treats H and W as silent letters. Apart from when they appear as the first letter, they + * are ignored. They don't act as separators between duplicate codes. * * @see #US_ENGLISH_MAPPING_STRING */ public static final Soundex US_ENGLISH = new Soundex(); /** - * An instance of Soundex using the Simplified Soundex mapping, as described here: - * http://west-penwith.org.uk/misc/soundex.htm + * An instance of Soundex using the Simplified Soundex mapping, as described here: http://west-penwith.org.uk/misc/soundex.htm * <p> - * This treats H and W the same as vowels (AEIOUY). - * Such letters aren't encoded (after the first), but they do - * act as separators when dropping duplicate codes. - * The mapping is otherwise the same as for {@link #US_ENGLISH} + * This treats H and W the same as vowels (AEIOUY). Such letters aren't encoded (after the first), but they do act as separators when dropping duplicate + * codes. The mapping is otherwise the same as for {@link #US_ENGLISH}. * </p> * * @since 1.11 @@ -93,22 +84,18 @@ public class Soundex implements StringEncoder { public static final Soundex US_ENGLISH_SIMPLIFIED = new Soundex(US_ENGLISH_MAPPING_STRING, false); /** - * An instance of Soundex using the mapping as per the Genealogy site: - * http://www.genealogy.com/articles/research/00000060.html + * An instance of Soundex using the mapping as per the Genealogy site: http://www.genealogy.com/articles/research/00000060.html * <p> - * This treats vowels (AEIOUY), H and W as silent letters. - * Such letters are ignored (after the first) and do not - * act as separators when dropping duplicate codes. + * This treats vowels (AEIOUY), H and W as silent letters. Such letters are ignored (after the first) and do not act as separators when dropping duplicate + * codes. * </p> * <p> - * The codes for consonants are otherwise the same as for - * {@link #US_ENGLISH_MAPPING_STRING} and {@link #US_ENGLISH_SIMPLIFIED} + * The codes for consonants are otherwise the same as for {@link #US_ENGLISH_MAPPING_STRING} and {@link #US_ENGLISH_SIMPLIFIED}. * </p> * * @since 1.11 */ public static final Soundex US_ENGLISH_GENEALOGY = new Soundex("-123-12--22455-12623-1-2-2"); - // ABCDEFGHIJKLMNOPQRSTUVWXYZ /** * The maximum length of a Soundex code - Soundex codes are only four characters by definition. @@ -119,17 +106,16 @@ public class Soundex implements StringEncoder { private int maxLength = 4; /** - * Every letter of the alphabet is "mapped" to a numerical value. This char array holds the values to which each - * letter is mapped. This implementation contains a default map for US_ENGLISH + * Every letter of the alphabet is "mapped" to a numerical value. This char array holds the values to which each letter is mapped. This implementation + * contains a default map for US_ENGLISH. */ private final char[] soundexMapping; /** * Should H and W be treated specially? * <p> - * In versions of the code prior to 1.11, - * the code always treated H and W as silent (ignored) letters. - * If this field is false, H and W are no longer special-cased. + * In versions of the code prior to 1.11, the code always treated H and W as silent (ignored) letters. If this field is false, H and W are no longer + * special-cased. * </p> */ private final boolean specialCaseHW; @@ -146,18 +132,16 @@ public class Soundex implements StringEncoder { } /** - * Creates a Soundex instance using the given mapping. This constructor can be used to provide an internationalized - * mapping for a non-Western character set. + * Creates a Soundex instance using the given mapping. This constructor can be used to provide an internationalized mapping for a non-Western character set. * <p> - * Every letter of the alphabet is "mapped" to a numerical value. This char array holds the values to which each - * letter is mapped. This implementation contains a default map for US_ENGLISH + * Every letter of the alphabet is "mapped" to a numerical value. This char array holds the values to which each letter is mapped. This implementation + * contains a default map for US_ENGLISH * </p> * <p> * If the mapping contains an instance of {@link #SILENT_MARKER} then H and W are not given special treatment. * </p> * - * @param mapping - * Mapping array to use when finding the corresponding code for a given character. + * @param mapping Mapping array to use when finding the corresponding code for a given character. */ public Soundex(final char[] mapping) { this.soundexMapping = mapping.clone(); @@ -165,14 +149,13 @@ public class Soundex implements StringEncoder { } /** - * Creates a refined Soundex instance using a custom mapping. This constructor can be used to customize the mapping, - * and/or possibly provide an internationalized mapping for a non-Western character set. + * Creates a refined Soundex instance using a custom mapping. This constructor can be used to customize the mapping, and/or possibly provide an + * internationalized mapping for a non-Western character set. * <p> * If the mapping contains an instance of {@link #SILENT_MARKER} then H and W are not given special treatment. * </p> * - * @param mapping - * Mapping string to use when finding the corresponding code for a given character. + * @param mapping Mapping string to use when finding the corresponding code for a given character. * @since 1.4 */ public Soundex(final String mapping) { @@ -181,12 +164,11 @@ public class Soundex implements StringEncoder { } /** - * Creates a refined Soundex instance using a custom mapping. This constructor can be used to customize the mapping, - * and/or possibly provide an internationalized mapping for a non-Western character set. + * Creates a refined Soundex instance using a custom mapping. This constructor can be used to customize the mapping, and/or possibly provide an + * internationalized mapping for a non-Western character set. * - * @param mapping - * Mapping string to use when finding the corresponding code for a given character. - * @param specialCaseHW if true, then + * @param mapping Mapping string to use when finding the corresponding code for a given character. + * @param specialCaseHW if true, then H and W are treated as silent letters that are ignored and do not act as separators between duplicate codes. * @since 1.11 */ public Soundex(final String mapping, final boolean specialCaseHW) { @@ -203,7 +185,6 @@ public class Soundex implements StringEncoder { * @return The number of characters in the two encoded Strings that are the same from 0 to 4. * @see SoundexUtils#difference(StringEncoder,String,String) * @see <a href="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/tsqlref/ts_de-dz_8co5.asp";> MS T-SQL DIFFERENCE</a> - * * @throws EncoderException if an error occurs encoding one of the strings. * @since 1.3 */ @@ -243,8 +224,8 @@ public class Soundex implements StringEncoder { /** * Returns the maxLength. Standard Soundex * - * @deprecated This feature is not needed since the encoding size must be constant. Will be removed in 2.0. * @return the maxLength. + * @deprecated This feature is not needed since the encoding size must be constant. Will be removed in 2.0. */ @Deprecated public int getMaxLength() { @@ -263,11 +244,9 @@ public class Soundex implements StringEncoder { /** * Maps the given upper-case character to its Soundex code. * - * @param ch - * An upper-case character. + * @param ch An upper-case character. * @return A Soundex code. - * @throws IllegalArgumentException - * Thrown if {@code ch} is not mapped. + * @throws IllegalArgumentException Thrown if {@code ch} is not mapped. */ private char map(final char ch) { final int index = ch - 'A'; @@ -281,8 +260,7 @@ public class Soundex implements StringEncoder { * Sets the maxLength. * * @deprecated This feature is not needed since the encoding size must be constant. Will be removed in 2.0. - * @param maxLength - * The maxLength to set. + * @param maxLength The maxLength to set. */ @Deprecated public void setMaxLength(final int maxLength) { @@ -325,5 +303,4 @@ public class Soundex implements StringEncoder { } return new String(out); } - } diff --git a/src/main/java/org/apache/commons/codec/net/QuotedPrintableCodec.java b/src/main/java/org/apache/commons/codec/net/QuotedPrintableCodec.java index 4f9baaaa..8f9bc737 100644 --- a/src/main/java/org/apache/commons/codec/net/QuotedPrintableCodec.java +++ b/src/main/java/org/apache/commons/codec/net/QuotedPrintableCodec.java @@ -36,56 +36,48 @@ import org.apache.commons.codec.binary.StringUtils; /** * Codec for the Quoted-Printable section of <a href="https://www.ietf.org/rfc/rfc1521.txt";>RFC 1521</a>. * <p> - * 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. + * 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. * </p> * <p> * Note: * </p> * <p> - * Depending on the selected {@code strict} parameter, this class will implement a different set of rules of the - * quoted-printable spec: + * Depending on the selected {@code strict} parameter, this class will implement a different set of rules of the quoted-printable spec: * </p> * <ul> - * <li>{@code strict=false}: only rules #1 and #2 are implemented</li> - * <li>{@code strict=true}: all rules #1 through #5 are implemented</li> + * <li>{@code strict=false}: only rules #1 and #2 are implemented</li> + * <li>{@code strict=true}: all rules #1 through #5 are implemented</li> * </ul> * <p> - * 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. + * 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. * </p> * <p> * This class is immutable and thread-safe. * </p> * - * @see <a href="https://www.ietf.org/rfc/rfc1521.txt";>RFC 1521 MIME (Multipurpose Internet Mail Extensions) Part One: - * Mechanisms for Specifying and Describing the Format of Internet Message Bodies </a> + * @see <a href="https://www.ietf.org/rfc/rfc1521.txt";>RFC 1521 MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing + * the Format of Internet Message Bodies </a> * * @since 1.3 */ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, StringEncoder, StringDecoder { + /** * BitSet of printable characters as defined in RFC 1521. */ private static final BitSet PRINTABLE_CHARS = new BitSet(256); - private static final byte ESCAPE_CHAR = '='; - private static final byte TAB = 9; - private static final byte SPACE = 32; - private static final byte CR = 13; - private static final byte LF = 10; /** - * Minimum length required for the byte arrays used by encodeQuotedPrintable method + * Minimum length required for the byte arrays used by encodeQuotedPrintable method. */ private static final int MIN_BYTES = 3; @@ -108,18 +100,14 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } /** - * Decodes an array quoted-printable characters into an array of original bytes. Escaped characters are converted - * back to their original representation. + * Decodes an array quoted-printable characters into an array of original bytes. Escaped characters are converted back to their original representation. * <p> - * This function fully implements the quoted-printable encoding specification (rule #1 through rule #5) as - * defined in RFC 1521. + * This function fully implements the quoted-printable encoding specification (rule #1 through rule #5) as defined in RFC 1521. * </p> * - * @param bytes - * array of quoted-printable characters - * @return array of original bytes - * @throws DecoderException - * Thrown if quoted-printable decoding is unsuccessful + * @param bytes array of quoted-printable characters. + * @return array of original bytes. + * @throws DecoderException Thrown if quoted-printable decoding is unsuccessful. */ public static final byte[] decodeQuotedPrintable(final byte[] bytes) throws DecoderException { if (bytes == null) { @@ -151,13 +139,10 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes a byte in the buffer. * - * @param b - * byte to write - * @param encode - * indicates whether the octet shall be encoded - * @param buffer - * the buffer to write to - * @return the number of bytes that have been written to the buffer + * @param b byte to write. + * @param encode indicates whether the octet shall be encoded. + * @param buffer the buffer to write to. + * @return the number of bytes that have been written to the buffer. */ private static int encodeByte(final int b, final boolean encode, final ByteArrayOutputStream buffer) { if (encode) { @@ -170,15 +155,13 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped. * <p> - * 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. + * 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. * </p> * - * @param printable - * bitset of characters deemed quoted-printable - * @param bytes - * array of bytes to be encoded - * @return array of bytes containing quoted-printable data + * @param printable bitset of characters deemed quoted-printable. + * @param bytes array of bytes to be encoded. + * @return array of bytes containing quoted-printable data. */ public static final byte[] encodeQuotedPrintable(final BitSet printable, final byte[] bytes) { return encodeQuotedPrintable(printable, bytes, false); @@ -187,18 +170,14 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped. * <p> - * Depending on the selection of the {@code 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. + * Depending on the selection of the {@code 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. * </p> * - * @param printable - * bitset of characters deemed quoted-printable - * @param bytes - * array of bytes to be encoded - * @param strict - * if {@code true} the full ruleset is used, otherwise only rule #1 and rule #2 - * @return array of bytes containing quoted-printable data + * @param printable bitset of characters deemed quoted-printable. + * @param bytes array of bytes to be encoded. + * @param strict if {@code true} the full ruleset is used, otherwise only rule #1 and rule #2. + * @return array of bytes containing quoted-printable data. * @since 1.10 */ public static final byte[] encodeQuotedPrintable(BitSet printable, final byte[] bytes, final boolean strict) { @@ -210,12 +189,10 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } final ByteArrayOutputStream buffer = new ByteArrayOutputStream(); final int bytesLength = bytes.length; - if (strict) { if (bytesLength < MIN_BYTES) { return null; } - int pos = 1; // encode up to buffer.length - 3, the last three octets will be treated // separately for simplification of note #3 @@ -227,7 +204,6 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } else { // rule #3: whitespace at the end of a line *must* be encoded encodeByte(b, !printable.get(b) || isWhitespace(b), buffer); - // rule #5: soft line break buffer.write(ESCAPE_CHAR); buffer.write(CR); @@ -235,16 +211,14 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin pos = 1; } } - // rule #3: whitespace at the end of a line *must* be encoded // if we would do a soft break line after this octet, encode whitespace int b = getUnsignedOctet(bytesLength - 3, bytes); boolean encode = !printable.get(b) || isWhitespace(b) && pos > SAFE_LENGTH - 5; pos += encodeByte(b, encode, buffer); - // note #3: '=' *must not* be the ultimate or penultimate character // simplification: if < 6 bytes left, do a soft line break as we may need - // exactly 6 bytes space for the last 2 bytes + // exactly 6 bytes space for the last 2 bytes if (pos > SAFE_LENGTH - 2) { buffer.write(ESCAPE_CHAR); buffer.write(CR); @@ -275,11 +249,9 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes byte into its quoted-printable representation. * - * @param b - * byte to encode - * @param buffer - * the buffer to write to - * @return The number of bytes written to the {@code buffer} + * @param b byte to encode. + * @param buffer the buffer to write to. + * @return The number of bytes written to the {@code buffer}. */ private static int encodeQuotedPrintable(final int b, final ByteArrayOutputStream buffer) { buffer.write(ESCAPE_CHAR); @@ -291,14 +263,11 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } /** - * Gets the byte at position {@code index} of the byte array and - * make sure it is unsigned. + * Gets the byte at position {@code index} of the byte array and make sure it is unsigned. * - * @param index - * position in the array - * @param bytes - * the byte array - * @return the unsigned octet at position {@code index} from the array + * @param index position in the array. + * @param bytes the byte array. + * @return the unsigned octet at position {@code index} from the array. */ private static int getUnsignedOctet(final int index, final byte[] bytes) { int b = bytes[index]; @@ -311,9 +280,8 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Checks whether the given byte is whitespace. * - * @param b - * byte to be checked - * @return {@code true} if the byte is either a space or tab character + * @param b byte to be checked. + * @return {@code true} if the byte is either a space or tab character. */ private static boolean isWhitespace(final int b) { return b == SPACE || b == TAB; @@ -323,7 +291,6 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin * The default Charset used for string decoding and encoding. */ private final Charset charset; - /** * Indicates whether soft line breaks shall be used during encoding (rule #3-5). */ @@ -339,8 +306,7 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Constructor which allows for the selection of the strict mode. * - * @param strict - * if {@code true}, soft line breaks will be used + * @param strict if {@code true}, soft line breaks will be used. * @since 1.10 */ public QuotedPrintableCodec(final boolean strict) { @@ -350,8 +316,7 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Constructor which allows for the selection of a default Charset. * - * @param charset - * the default string Charset to use. + * @param charset the default string Charset to use. * @since 1.7 */ public QuotedPrintableCodec(final Charset charset) { @@ -361,10 +326,8 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Constructor which allows for the selection of a default Charset and strict mode. * - * @param charset - * the default string Charset to use. - * @param strict - * if {@code true}, soft line breaks will be used + * @param charset the default string Charset to use. + * @param strict if {@code true}, soft line breaks will be used. * @since 1.10 */ public QuotedPrintableCodec(final Charset charset, final boolean strict) { @@ -375,15 +338,10 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Constructor which allows for the selection of a default Charset. * - * @param charsetName - * the default string Charset to use. - * @throws UnsupportedCharsetException - * If no support for the named Charset is available - * in this instance of the Java virtual machine - * @throws IllegalArgumentException - * If the given charsetName is null - * @throws IllegalCharsetNameException - * If the given Charset name is illegal + * @param charsetName the default string Charset to use. + * @throws UnsupportedCharsetException If no support for the named Charset is available in this instance of the Java virtual machine. + * @throws IllegalArgumentException If the given charsetName is null. + * @throws IllegalCharsetNameException If the given Charset name is illegal. * * @since 1.7 throws UnsupportedCharsetException if the named Charset is unavailable */ @@ -392,18 +350,14 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } /** - * Decodes an array of quoted-printable characters into an array of original bytes. Escaped characters are converted - * back to their original representation. + * Decodes an array of quoted-printable characters into an array of original bytes. Escaped characters are converted back to their original representation. * <p> - * This function fully implements the quoted-printable encoding specification (rule #1 through rule #5) as - * defined in RFC 1521. + * This function fully implements the quoted-printable encoding specification (rule #1 through rule #5) as defined in RFC 1521. * </p> * - * @param bytes - * array of quoted-printable characters - * @return array of original bytes - * @throws DecoderException - * Thrown if quoted-printable decoding is unsuccessful + * @param bytes array of quoted-printable characters. + * @return array of original bytes. + * @throws DecoderException Thrown if quoted-printable decoding is unsuccessful. */ @Override public byte[] decode(final byte[] bytes) throws DecoderException { @@ -411,15 +365,12 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } /** - * Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original - * representation. + * Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original representation. * - * @param obj - * quoted-printable object to convert into its original form - * @return original object - * @throws DecoderException - * Thrown if the argument is not a {@code String} or {@code byte[]}. Thrown if a failure - * condition is encountered during the decode process. + * @param obj quoted-printable object to convert into its original form. + * @return original object. + * @throws DecoderException Thrown if the argument is not a {@code String} or {@code byte[]}. Thrown if a failure condition is encountered during the decode + * process. */ @Override public Object decode(final Object obj) throws DecoderException { @@ -436,14 +387,12 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } /** - * Decodes a quoted-printable string into its original form using the default string Charset. Escaped characters are - * converted back to their original representation. + * Decodes a quoted-printable string into its original form using the default string Charset. Escaped characters are converted back to their original + * representation. * - * @param sourceStr - * quoted-printable string to convert into its original form - * @return original string - * @throws DecoderException - * Thrown if quoted-printable decoding is unsuccessful. Thrown if Charset is not supported. + * @param sourceStr quoted-printable string to convert into its original form. + * @return original string. + * @throws DecoderException Thrown if quoted-printable decoding is unsuccessful. Thrown if Charset is not supported. * @see #getCharset() */ @Override @@ -452,16 +401,13 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } /** - * Decodes a quoted-printable string into its original form using the specified string Charset. Escaped characters - * are converted back to their original representation. + * Decodes a quoted-printable string into its original form using the specified string Charset. Escaped characters are converted back to their original + * representation. * - * @param sourceStr - * quoted-printable string to convert into its original form - * @param sourceCharset - * the original string Charset - * @return original string - * @throws DecoderException - * Thrown if quoted-printable decoding is unsuccessful + * @param sourceStr quoted-printable string to convert into its original form. + * @param sourceCharset the original string Charset. + * @return original string. + * @throws DecoderException Thrown if quoted-printable decoding is unsuccessful. * @since 1.7 */ public String decode(final String sourceStr, final Charset sourceCharset) throws DecoderException { @@ -472,18 +418,14 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin } /** - * Decodes a quoted-printable string into its original form using the specified string Charset. Escaped characters - * are converted back to their original representation. + * Decodes a quoted-printable string into its original form using the specified string Charset. Escaped characters are converted back to their original + * representation. * - * @param sourceStr - * quoted-printable string to convert into its original form - * @param sourceCharset - * the original string Charset - * @return original string - * @throws DecoderException - * Thrown if quoted-printable decoding is unsuccessful - * @throws UnsupportedEncodingException - * Thrown if Charset is not supported + * @param sourceStr quoted-printable string to convert into its original form. + * @param sourceCharset the original string Charset. + * @return original string. + * @throws DecoderException Thrown if quoted-printable decoding is unsuccessful. + * @throws UnsupportedEncodingException Thrown if Charset is not supported. */ public String decode(final String sourceStr, final String sourceCharset) throws DecoderException, UnsupportedEncodingException { if (sourceStr == null) { @@ -495,14 +437,12 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped. * <p> - * Depending on the selection of the {@code 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. + * Depending on the selection of the {@code 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. * </p> * - * @param bytes - * array of bytes to be encoded - * @return array of bytes containing quoted-printable data + * @param bytes array of bytes to be encoded. + * @return array of bytes containing quoted-printable data. */ @Override public byte[] encode(final byte[] bytes) { @@ -512,12 +452,9 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes an object into its quoted-printable safe form. Unsafe characters are escaped. * - * @param obj - * string to convert to a quoted-printable form - * @return quoted-printable object - * @throws EncoderException - * Thrown if quoted-printable encoding is not applicable to objects of this type or if encoding is - * unsuccessful + * @param obj string to convert to a quoted-printable form. + * @return quoted-printable object. + * @throws EncoderException Thrown if quoted-printable encoding is not applicable to objects of this type or if encoding is unsuccessful. */ @Override public Object encode(final Object obj) throws EncoderException { @@ -536,16 +473,13 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes a string into its quoted-printable form using the default string Charset. Unsafe characters are escaped. * <p> - * Depending on the selection of the {@code 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. + * Depending on the selection of the {@code 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. * </p> * - * @param sourceStr - * string to convert to quoted-printable form - * @return quoted-printable string - * @throws EncoderException - * Thrown if quoted-printable encoding is unsuccessful + * @param sourceStr string to convert to quoted-printable form. + * @return quoted-printable string. + * @throws EncoderException Thrown if quoted-printable encoding is unsuccessful. * * @see #getCharset() */ @@ -557,16 +491,13 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped. * <p> - * Depending on the selection of the {@code 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. + * Depending on the selection of the {@code 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. * </p> * - * @param sourceStr - * string to convert to quoted-printable form - * @param sourceCharset - * the Charset for sourceStr - * @return quoted-printable string + * @param sourceStr string to convert to quoted-printable form. + * @param sourceCharset the Charset for sourceStr. + * @return quoted-printable string. * @since 1.7 */ public String encode(final String sourceStr, final Charset sourceCharset) { @@ -579,18 +510,14 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped. * <p> - * Depending on the selection of the {@code 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. + * Depending on the selection of the {@code 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. * </p> * - * @param sourceStr - * string to convert to quoted-printable form - * @param sourceCharset - * the Charset for sourceStr - * @return quoted-printable string - * @throws UnsupportedEncodingException - * Thrown if the Charset is not supported + * @param sourceStr string to convert to quoted-printable form. + * @param sourceCharset the Charset for sourceStr. + * @return quoted-printable string. + * @throws UnsupportedEncodingException Thrown if the Charset is not supported. */ public String encode(final String sourceStr, final String sourceCharset) throws UnsupportedEncodingException { if (sourceStr == null) { @@ -602,7 +529,7 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Gets the default Charset name used for string decoding and encoding. * - * @return the default Charset name + * @return the default Charset name. * @since 1.7 */ public Charset getCharset() { @@ -612,7 +539,7 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin /** * Gets the default Charset name used for string decoding and encoding. * - * @return the default Charset name + * @return the default Charset name. */ public String getDefaultCharset() { return this.charset.name(); diff --git a/src/main/java/org/apache/commons/codec/net/RFC1522Codec.java b/src/main/java/org/apache/commons/codec/net/RFC1522Codec.java index 08ced993..f3b25b25 100644 --- a/src/main/java/org/apache/commons/codec/net/RFC1522Codec.java +++ b/src/main/java/org/apache/commons/codec/net/RFC1522Codec.java @@ -29,16 +29,14 @@ import org.apache.commons.codec.binary.StringUtils; /** * Implements methods common to all codecs defined in RFC 1522. * <p> - * <a href="https://www.ietf.org/rfc/rfc1522.txt";>RFC 1522</a> 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. + * <a href="https://www.ietf.org/rfc/rfc1522.txt";>RFC 1522</a> 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. * </p> * <p> * This class is immutable and thread-safe. * </p> * - * @see <a href="https://www.ietf.org/rfc/rfc1522.txt";>MIME (Multipurpose Internet Mail Extensions) Part Two: - * Message Header Extensions for Non-ASCII Text</a> + * @see <a href="https://www.ietf.org/rfc/rfc1522.txt";>MIME (Multipurpose Internet Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text</a> * @since 1.3 */ abstract class RFC1522Codec { @@ -64,17 +62,14 @@ abstract class RFC1522Codec { /** * Applies an RFC 1522 compliant decoding scheme to the given string of text. * <p> - * This method processes the "encoded-word" header common to all the RFC 1522 codecs and then invokes - * {@link #doDecoding(byte[])} method of a concrete class to perform the specific decoding. + * This method processes the "encoded-word" header common to all the RFC 1522 codecs and then invokes {@link #doDecoding(byte[])} method of a concrete class + * to perform the specific decoding. * </p> * - * @param text - * a string to decode + * @param text a string to decode. * @return A new decoded String or {@code null} if the input is {@code null}. - * @throws DecoderException - * thrown if there is an error condition during the decoding process. - * @throws UnsupportedEncodingException - * thrown if charset specified in the "encoded-word" header is not supported + * @throws DecoderException thrown if there is an error condition during the decoding process. + * @throws UnsupportedEncodingException thrown if charset specified in the "encoded-word" header is not supported. */ protected String decodeText(final String text) throws DecoderException, UnsupportedEncodingException { if (text == null) { @@ -112,39 +107,32 @@ abstract class RFC1522Codec { /** * Decodes an array of bytes using the defined encoding scheme. * - * @param bytes - * Data to be decoded - * @return a byte array that contains decoded data - * @throws DecoderException - * A decoder exception is thrown if a Decoder encounters a failure condition during the decode process. + * @param bytes Data to be decoded. + * @return a byte array that contains decoded data. + * @throws DecoderException A decoder exception is thrown if a Decoder encounters a failure condition during the decode process. */ protected abstract byte[] doDecoding(byte[] bytes) throws DecoderException; /** * Encodes an array of bytes using the defined encoding scheme. * - * @param bytes - * Data to be encoded - * @return A byte array containing the encoded data - * @throws EncoderException - * thrown if the Encoder encounters a failure condition during the encoding process. + * @param bytes Data to be encoded. + * @return A byte array containing the encoded data. + * @throws EncoderException thrown if the Encoder encounters a failure condition during the encoding process. */ protected abstract byte[] doEncoding(byte[] bytes) throws EncoderException; /** * Applies an RFC 1522 compliant encoding scheme to the given string of text with the given charset. * <p> - * This method constructs the "encoded-word" header common to all the RFC 1522 codecs and then invokes - * {@link #doEncoding(byte[])} method of a concrete class to perform the specific encoding. + * This method constructs the "encoded-word" header common to all the RFC 1522 codecs and then invokes {@link #doEncoding(byte[])} method of a concrete + * class to perform the specific encoding. * </p> * - * @param text - * a string to encode - * @param charset - * a charset to be used - * @return RFC 1522 compliant "encoded-word" - * @throws EncoderException - * thrown if there is an error condition during the Encoding process. + * @param text a string to encode. + * @param charset a charset to be used. + * @return RFC 1522 compliant "encoded-word". + * @throws EncoderException thrown if there is an error condition during the Encoding process. * @see Charset */ protected String encodeText(final String text, final Charset charset) throws EncoderException { @@ -165,19 +153,15 @@ abstract class RFC1522Codec { /** * Applies an RFC 1522 compliant encoding scheme to the given string of text with the given charset. * <p> - * This method constructs the "encoded-word" header common to all the RFC 1522 codecs and then invokes - * {@link #doEncoding(byte[])} method of a concrete class to perform the specific encoding. + * This method constructs the "encoded-word" header common to all the RFC 1522 codecs and then invokes {@link #doEncoding(byte[])} method of a concrete + * class to perform the specific encoding. * </p> * - * @param text - * a string to encode - * @param charsetName - * the charset to use - * @return RFC 1522 compliant "encoded-word" - * @throws EncoderException - * thrown if there is an error condition during the Encoding process. - * @throws UnsupportedCharsetException - * if charset is not available + * @param text a string to encode. + * @param charsetName the charset to use. + * @return RFC 1522 compliant "encoded-word". + * @throws EncoderException thrown if there is an error condition during the Encoding process. + * @throws UnsupportedCharsetException if charset is not available. * @see Charset */ protected String encodeText(final String text, final String charsetName) throws EncoderException { @@ -191,7 +175,7 @@ abstract class RFC1522Codec { /** * Gets the default Charset name used for string decoding and encoding. * - * @return the default Charset name + * @return the default Charset name. * @since 1.7 */ public Charset getCharset() { @@ -201,7 +185,7 @@ abstract class RFC1522Codec { /** * Gets the default Charset name used for string decoding and encoding. * - * @return the default Charset name + * @return the default Charset name. */ public String getDefaultCharset() { return charset.name(); diff --git a/src/main/java/org/apache/commons/codec/net/Utils.java b/src/main/java/org/apache/commons/codec/net/Utils.java index 03d2531f..bef805eb 100644 --- a/src/main/java/org/apache/commons/codec/net/Utils.java +++ b/src/main/java/org/apache/commons/codec/net/Utils.java @@ -22,7 +22,9 @@ import org.apache.commons.codec.DecoderException; /** * Utility methods for this package. * - * <p>This class is immutable and thread-safe.</p> + * <p> + * This class is immutable and thread-safe. + * </p> * * @since 1.4 */ @@ -36,11 +38,9 @@ final class Utils { /** * Returns the numeric value of the character {@code b} in radix 16. * - * @param b - * The byte to be converted. + * @param b The byte to be converted. * @return The numeric value represented by the character in radix 16. - * @throws DecoderException - * Thrown when the byte is not valid per {@link Character#digit(char,int)} + * @throws DecoderException Thrown when the byte is not valid per {@link Character#digit(char,int)}. */ static int digit16(final byte b) throws DecoderException { final int i = Character.digit((char) b, RADIX); @@ -53,11 +53,10 @@ final class Utils { /** * Returns the upper case hexadecimal digit of the lower 4 bits of the int. * - * @param b the input int + * @param b the input int. * @return the upper case hexadecimal digit of the lower 4 bits of the int. */ static char hexChar(final int b) { return Character.toUpperCase(Character.forDigit(b & 0xF, RADIX)); } - }
