From 49e62cd000e6d359403a1f36201d28b568397c9c Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Thu, 4 Sep 2008 03:14:19 +0000
Subject: [PATCH] Added JavaDoc for handler.codec.string

---
 .../handler/codec/string/StringDecoder.java   | 42 ++++++++++++++++++-
 .../handler/codec/string/StringEncoder.java   | 27 +++++++++++-
 2 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/jboss/netty/handler/codec/string/StringDecoder.java b/src/main/java/org/jboss/netty/handler/codec/string/StringDecoder.java
index 294f3fef7e..e5a7fbac50 100644
--- a/src/main/java/org/jboss/netty/handler/codec/string/StringDecoder.java
+++ b/src/main/java/org/jboss/netty/handler/codec/string/StringDecoder.java
@@ -29,30 +29,70 @@ import java.nio.charset.Charset;
 import org.jboss.netty.buffer.ChannelBuffer;
 import org.jboss.netty.channel.ChannelEvent;
 import org.jboss.netty.channel.ChannelHandlerContext;
+import org.jboss.netty.channel.ChannelPipeline;
 import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.channel.ChannelUpstreamHandler;
 import org.jboss.netty.channel.MessageEvent;
+import org.jboss.netty.handler.codec.frame.DelimiterBasedFrameDecoder;
+import org.jboss.netty.handler.codec.frame.Delimiters;
+import org.jboss.netty.handler.codec.frame.FrameDecoder;
 
 /**
+ * Decodes a received {@link ChannelBuffer} into a {@link String}.  Please
+ * note that this decoder must be used with a proper {@link FrameDecoder}
+ * such as {@link DelimiterBasedFrameDecoder} if you are using a stream-based
+ * transport such as TCP/IP.  A typical decoder setup for a text-based line
+ * protocol in a TCP/IP socket would be:
+ * <pre>
+ * {@link ChannelPipeline} pipeline = ...;
+ *
+ * // Decoders
+ * pipeline.addLast("frameDecoder", new {@link DelimiterBasedFrameDecoder}({@link Delimiters#lineDelimiter()}));
+ * pipeline.addLast("stringDecoder", new {@link StringDecoder}("UTF-8"));
+ *
+ * // Encoder
+ * pipeline.addLast("stringEncoder", new {@link StringEncoder}("UTF-8"));
+ * </pre>
+ * and then you can use {@link String}s instead of {@link ChannelBuffer}s
+ * as a message:
+ * <pre>
+ * void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
+ *     String msg = (String) e.getMessage();
+ *     ch.write("Did you say '" + msg + "'?\n");
+ * }
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
  * @version $Rev:231 $, $Date:2008-06-12 16:44:50 +0900 (목, 12 6월 2008) $
- *
  */
 @ChannelPipelineCoverage("all")
 public class StringDecoder implements ChannelUpstreamHandler {
 
     private final String charsetName;
 
+    /**
+     * Creates a new instance with the current system character set.
+     */
     public StringDecoder() {
         this(Charset.defaultCharset());
     }
 
+    /**
+     * Creates a new instance.
+     *
+     * @param charsetName  the name of the character set to use for decoding
+     */
     public StringDecoder(String charsetName) {
         this(Charset.forName(charsetName));
     }
 
+    /**
+     * Creates a new instance.
+     *
+     * @param charset  the character set to use for decoding
+     */
     public StringDecoder(Charset charset) {
         if (charset == null) {
             throw new NullPointerException("charset");
diff --git a/src/main/java/org/jboss/netty/handler/codec/string/StringEncoder.java b/src/main/java/org/jboss/netty/handler/codec/string/StringEncoder.java
index e5420b73af..c96cc908bb 100644
--- a/src/main/java/org/jboss/netty/handler/codec/string/StringEncoder.java
+++ b/src/main/java/org/jboss/netty/handler/codec/string/StringEncoder.java
@@ -27,18 +27,43 @@ import static org.jboss.netty.channel.Channels.*;
 
 import java.nio.charset.Charset;
 
+import org.jboss.netty.buffer.ChannelBuffer;
 import org.jboss.netty.channel.ChannelDownstreamHandler;
 import org.jboss.netty.channel.ChannelEvent;
 import org.jboss.netty.channel.ChannelHandlerContext;
+import org.jboss.netty.channel.ChannelPipeline;
 import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.channel.MessageEvent;
+import org.jboss.netty.handler.codec.frame.DelimiterBasedFrameDecoder;
+import org.jboss.netty.handler.codec.frame.Delimiters;
 
 /**
+ * Encodes the requested {@link String} into a {@link ChannelBuffer}.
+ * The typical decoder setup for a text-based line protocol in a TCP/IP socket
+ * would be:
+ * <pre>
+ * {@link ChannelPipeline} pipeline = ...;
+ *
+ * // Decoders
+ * pipeline.addLast("frameDecoder", new {@link DelimiterBasedFrameDecoder}({@link Delimiters#lineDelimiter()}));
+ * pipeline.addLast("stringDecoder", new {@link StringDecoder}("UTF-8"));
+ *
+ * // Encoder
+ * pipeline.addLast("stringEncoder", new {@link StringEncoder}("UTF-8"));
+ * </pre>
+ * and then you can use {@link String}s instead of {@link ChannelBuffer}s
+ * as a message:
+ * <pre>
+ * void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
+ *     String msg = (String) e.getMessage();
+ *     ch.write("Did you say '" + msg + "'?\n");
+ * }
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
  * @version $Rev:231 $, $Date:2008-06-12 16:44:50 +0900 (목, 12 6월 2008) $
- *
  */
 @ChannelPipelineCoverage("all")
 public class StringEncoder implements ChannelDownstreamHandler {