From 37e471dbe6a40b7974c8994c65ab4b2f3675d2ac Mon Sep 17 00:00:00 2001
From: Alex Vasiliev <alex.vassiliev@gmail.com>
Date: Thu, 20 Dec 2018 17:40:06 +1100
Subject: [PATCH] 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.
---
 .../java/io/netty/handler/codec/LineBasedFrameDecoder.java | 6 ++++++
 .../io/netty/handler/codec/json/JsonObjectDecoder.java     | 7 ++++++-
 .../java/io/netty/handler/codec/xml/XmlFrameDecoder.java   | 6 ++++++
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/codec/src/main/java/io/netty/handler/codec/LineBasedFrameDecoder.java b/codec/src/main/java/io/netty/handler/codec/LineBasedFrameDecoder.java
index 58f2e85f04..fda45cc401 100644
--- a/codec/src/main/java/io/netty/handler/codec/LineBasedFrameDecoder.java
+++ b/codec/src/main/java/io/netty/handler/codec/LineBasedFrameDecoder.java
@@ -25,6 +25,12 @@ import java.util.List;
  * A decoder that splits the received {@link ByteBuf}s on line endings.
  * <p>
  * 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}.
  */
 public class LineBasedFrameDecoder extends ByteToMessageDecoder {
diff --git a/codec/src/main/java/io/netty/handler/codec/json/JsonObjectDecoder.java b/codec/src/main/java/io/netty/handler/codec/json/JsonObjectDecoder.java
index f63e62066e..2508ff6c09 100644
--- a/codec/src/main/java/io/netty/handler/codec/json/JsonObjectDecoder.java
+++ b/codec/src/main/java/io/netty/handler/codec/json/JsonObjectDecoder.java
@@ -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
  * {@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
  * 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.
diff --git a/codec/src/main/java/io/netty/handler/codec/xml/XmlFrameDecoder.java b/codec/src/main/java/io/netty/handler/codec/xml/XmlFrameDecoder.java
index 4a8b262bf8..480f0be1c5 100644
--- a/codec/src/main/java/io/netty/handler/codec/xml/XmlFrameDecoder.java
+++ b/codec/src/main/java/io/netty/handler/codec/xml/XmlFrameDecoder.java
@@ -59,6 +59,12 @@ import java.util.List;
  * +-----------------+-------------------------------------+
  * </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
  * xml streaming protocols such as
  * <a href="http://xmpp.org/rfcs/rfc6120.html">XMPP</a>,