Added comments to LineBasedFrameDecoder, JsonObjectDecoder and XmlFrameDecoder that they are only compatible with UTF-8 encoded streams. (#8651)

Motivation:

LineBasedFrameDecoder, JsonObjectDecoder and XmlFrameDecoder upon investigation of the
sourcecode appeared to only support ASCII or UTF-8 input. It is an important characteristic
and ont reflected in any documentation. This could lead to improper usage and bugs.

Modifications:

Javadoc comment is addedd to all three classes to state that implementation is only
compatible with UTF-8 or ASCII input streams and brifly touches on implementaion details.

Result:

The end user of the netty library would not have to study sorcecode to deterime character
encoding limitations for given classes.
This commit is contained in:
Alex Vasiliev 2018-12-20 17:40:06 +11:00 committed by Norman Maurer
parent 44b919b698
commit 37e471dbe6
3 changed files with 18 additions and 1 deletions

View File

@ -25,6 +25,12 @@ import java.util.List;
* A decoder that splits the received {@link ByteBuf}s on line endings. * A decoder that splits the received {@link ByteBuf}s on line endings.
* <p> * <p>
* Both {@code "\n"} and {@code "\r\n"} are handled. * Both {@code "\n"} and {@code "\r\n"} are handled.
* <p>
* The byte stream is expected to be in UTF-8 character encoding or ASCII. The current implementation
* uses direct {@code byte} to {@code char} cast and then compares that {@code char} to a few low range
* ASCII characters like {@code '\n'} or {@code '\r'}. UTF-8 is not using low range [0..0x7F]
* byte values for multibyte codepoint representations therefore fully supported by this implementation.
* <p>
* For a more general delimiter-based decoder, see {@link DelimiterBasedFrameDecoder}. * For a more general delimiter-based decoder, see {@link DelimiterBasedFrameDecoder}.
*/ */
public class LineBasedFrameDecoder extends ByteToMessageDecoder { public class LineBasedFrameDecoder extends ByteToMessageDecoder {

View File

@ -30,7 +30,12 @@ import java.util.List;
/** /**
* Splits a byte stream of JSON objects and arrays into individual objects/arrays and passes them up the * Splits a byte stream of JSON objects and arrays into individual objects/arrays and passes them up the
* {@link ChannelPipeline}. * {@link ChannelPipeline}.
* * <p>
* The byte stream is expected to be in UTF-8 character encoding or ASCII. The current implementation
* uses direct {@code byte} to {@code char} cast and then compares that {@code char} to a few low range
* ASCII characters like {@code '{'}, {@code '['} or {@code '"'}. UTF-8 is not using low range [0..0x7F]
* byte values for multibyte codepoint representations therefore fully supported by this implementation.
* <p>
* This class does not do any real parsing or validation. A sequence of bytes is considered a JSON object/array * This class does not do any real parsing or validation. A sequence of bytes is considered a JSON object/array
* if it contains a matching number of opening and closing braces/brackets. It's up to a subsequent * if it contains a matching number of opening and closing braces/brackets. It's up to a subsequent
* {@link ChannelHandler} to parse the JSON text into a more usable form i.e. a POJO. * {@link ChannelHandler} to parse the JSON text into a more usable form i.e. a POJO.

View File

@ -59,6 +59,12 @@ import java.util.List;
* +-----------------+-------------------------------------+ * +-----------------+-------------------------------------+
* </pre> * </pre>
* *
* <p/>
* The byte stream is expected to be in UTF-8 character encoding or ASCII. The current implementation
* uses direct {@code byte} to {@code char} cast and then compares that {@code char} to a few low range
* ASCII characters like {@code '<'}, {@code '>'} or {@code '/'}. UTF-8 is not using low range [0..0x7F]
* byte values for multibyte codepoint representations therefore fully supported by this implementation.
* <p/>
* Please note that this decoder is not suitable for * Please note that this decoder is not suitable for
* xml streaming protocols such as * xml streaming protocols such as
* <a href="http://xmpp.org/rfcs/rfc6120.html">XMPP</a>, * <a href="http://xmpp.org/rfcs/rfc6120.html">XMPP</a>,