Add LineEncoder to append a line separator automatically

Motivation:

See #1811

Modifications:

Add LineEncoder and LineSeparator

Result:

The user can use LineEncoder to write a String with a line separator automatically

buffer/src/main/java/io/netty/buffer/ByteBufUtil.java

@@ -507,12 +507,26 @@ public final class ByteBufUtil {
      * is allocated via the {@link ByteBufAllocator}.
      */
     public static ByteBuf encodeString(ByteBufAllocator alloc, CharBuffer src, Charset charset) {
-        return encodeString0(alloc, false, src, charset);
+        return encodeString0(alloc, false, src, charset, 0);
     }
 
-    static ByteBuf encodeString0(ByteBufAllocator alloc, boolean enforceHeap, CharBuffer src, Charset charset) {
+    /**
+     * Encode the given {@link CharBuffer} using the given {@link Charset} into a new {@link ByteBuf} which
+     * is allocated via the {@link ByteBufAllocator}.
+     *
+     * @param alloc The {@link ByteBufAllocator} to allocate {@link ByteBuf}.
+     * @param src The {@link CharBuffer} to encode.
+     * @param charset The specified {@link Charset}.
+     * @param extraCapacity the extra capacity to alloc except the space for decoding.
+     */
+    public static ByteBuf encodeString(ByteBufAllocator alloc, CharBuffer src, Charset charset, int extraCapacity) {
+        return encodeString0(alloc, false, src, charset, extraCapacity);
+    }
+
+    static ByteBuf encodeString0(ByteBufAllocator alloc, boolean enforceHeap, CharBuffer src, Charset charset,
+                                 int extraCapacity) {
         final CharsetEncoder encoder = CharsetUtil.encoder(charset);
-        int length = (int) ((double) src.remaining() * encoder.maxBytesPerChar());
+        int length = (int) ((double) src.remaining() * encoder.maxBytesPerChar()) + extraCapacity;
         boolean release = true;
         final ByteBuf dst;
         if (enforceHeap) {

buffer/src/main/java/io/netty/buffer/Unpooled.java

@@ -666,7 +666,7 @@ public final class Unpooled {
     }
 
     private static ByteBuf copiedBuffer(CharBuffer buffer, Charset charset) {
-        return ByteBufUtil.encodeString0(ALLOC, true, buffer, charset);
+        return ByteBufUtil.encodeString0(ALLOC, true, buffer, charset, 0);
     }
 
     /**

codec/src/main/java/io/netty/handler/codec/string/LineEncoder.java

@@ -0,0 +1,94 @@
+/*
+ * Copyright 2016 The Netty Project
+ *
+ * The Netty Project licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package io.netty.handler.codec.string;
+
+import io.netty.buffer.ByteBuf;
+import io.netty.buffer.ByteBufUtil;
+import io.netty.channel.ChannelHandler.Sharable;
+import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.ChannelPipeline;
+import io.netty.handler.codec.LineBasedFrameDecoder;
+import io.netty.handler.codec.MessageToMessageEncoder;
+import io.netty.util.CharsetUtil;
+import io.netty.util.internal.ObjectUtil;
+
+import java.nio.CharBuffer;
+import java.nio.charset.Charset;
+import java.util.List;
+
+/**
+ * Apply a line separator to the requested {@link String} and encode it into a {@link ByteBuf}.
+ * A typical setup for a text-based line protocol in a TCP/IP socket would be:
+ * <pre>
+ * {@link ChannelPipeline} pipeline = ...;
+ *
+ * // Decoders
+ * pipeline.addLast("frameDecoder", new {@link LineBasedFrameDecoder}(80));
+ * pipeline.addLast("stringDecoder", new {@link StringDecoder}(CharsetUtil.UTF_8));
+ *
+ * // Encoder
+ * pipeline.addLast("lineEncoder", new {@link LineEncoder}(LineSeparator.UNIX, CharsetUtil.UTF_8));
+ * </pre>
+ * and then you can use a {@link String} instead of a {@link ByteBuf}
+ * as a message:
+ * <pre>
+ * void channelRead({@link ChannelHandlerContext} ctx, {@link String} msg) {
+ *     ch.write("Did you say '" + msg + "'?");
+ * }
+ * </pre>
+ */
+@Sharable
+public class LineEncoder extends MessageToMessageEncoder<CharSequence> {
+
+    private final Charset charset;
+    private final byte[] lineSeparator;
+
+    /**
+     * Creates a new instance with the current system line separator and UTF-8 charset encoding.
+     */
+    public LineEncoder() {
+        this(LineSeparator.DEFAULT, CharsetUtil.UTF_8);
+    }
+
+    /**
+     * Creates a new instance with the specified line separator and UTF-8 charset encoding.
+     */
+    public LineEncoder(LineSeparator lineSeparator) {
+        this(lineSeparator, CharsetUtil.UTF_8);
+    }
+
+    /**
+     * Creates a new instance with the specified character set.
+     */
+    public LineEncoder(Charset charset) {
+        this(LineSeparator.DEFAULT, charset);
+    }
+
+    /**
+     * Creates a new instance with the specified line separator and character set.
+     */
+    public LineEncoder(LineSeparator lineSeparator, Charset charset) {
+        this.charset = ObjectUtil.checkNotNull(charset, "charset");
+        this.lineSeparator = ObjectUtil.checkNotNull(lineSeparator, "lineSeparator").value().getBytes(charset);
+    }
+
+    @Override
+    protected void encode(ChannelHandlerContext ctx, CharSequence msg, List<Object> out) throws Exception {
+        ByteBuf buffer = ByteBufUtil.encodeString(ctx.alloc(), CharBuffer.wrap(msg), charset, lineSeparator.length);
+        buffer.writeBytes(lineSeparator);
+        out.add(buffer);
+    }
+}

codec/src/main/java/io/netty/handler/codec/string/LineSeparator.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2016 The Netty Project
+ *
+ * The Netty Project licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package io.netty.handler.codec.string;
+
+import io.netty.buffer.ByteBufUtil;
+import io.netty.util.CharsetUtil;
+import io.netty.util.internal.ObjectUtil;
+import io.netty.util.internal.StringUtil;
+
+/**
+ * A class to represent line separators in different environments.
+ */
+public final class LineSeparator {
+
+    /**
+     * The default line separator in the current system.
+     */
+    public static final LineSeparator DEFAULT = new LineSeparator(StringUtil.NEWLINE);
+
+    /**
+     * The Unix line separator(LF)
+     */
+    public static final LineSeparator UNIX = new LineSeparator("\n");
+
+    /**
+     * The Windows line separator(CRLF)
+     */
+    public static final LineSeparator WINDOWS = new LineSeparator("\r\n");
+
+    private final String value;
+
+    /**
+     * Create {@link LineSeparator} with the specified {@code lineSeparator} string.
+     */
+    public LineSeparator(String lineSeparator) {
+        this.value = ObjectUtil.checkNotNull(lineSeparator, "lineSeparator");
+    }
+
+    /**
+     * Return the string value of this line separator.
+     */
+    public String value() {
+        return value;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof LineSeparator)) {
+            return false;
+        }
+        LineSeparator that = (LineSeparator) o;
+        return value != null ? value.equals(that.value) : that.value == null;
+    }
+
+    @Override
+    public int hashCode() {
+        return value != null ? value.hashCode() : 0;
+    }
+
+    /**
+     * Return a <a href="http://en.wikipedia.org/wiki/Hex_dump">hex dump</a> of the line separator in UTF-8 encoding.
+     */
+    @Override
+    public String toString() {
+        return ByteBufUtil.hexDump(value.getBytes(CharsetUtil.UTF_8));
+    }
+}

codec/src/test/java/io/netty/handler/codec/string/LineEncoderTest.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2016 The Netty Project
+ *
+ * The Netty Project licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package io.netty.handler.codec.string;
+
+import io.netty.buffer.ByteBuf;
+import io.netty.channel.embedded.EmbeddedChannel;
+import io.netty.util.CharsetUtil;
+import org.junit.Assert;
+import org.junit.Test;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class LineEncoderTest {
+
+    @Test
+    public void testEncode() {
+        testLineEncode(LineSeparator.DEFAULT, "abc");
+        testLineEncode(LineSeparator.WINDOWS, "abc");
+        testLineEncode(LineSeparator.UNIX, "abc");
+    }
+
+    private void testLineEncode(LineSeparator lineSeparator, String msg) {
+        EmbeddedChannel channel = new EmbeddedChannel(new LineEncoder(lineSeparator, CharsetUtil.UTF_8));
+        assertTrue(channel.writeOutbound(msg));
+        ByteBuf buf = channel.readOutbound();
+        try {
+            byte[] data = new byte[buf.readableBytes()];
+            buf.readBytes(data);
+            byte[] expected = (msg + lineSeparator.value()).getBytes(CharsetUtil.UTF_8);
+            Assert.assertArrayEquals(expected, data);
+            Assert.assertNull(channel.readOutbound());
+        } finally {
+            buf.release();
+            assertFalse(channel.finish());
+        }
+    }
+}