Javadoc

src/main/java/org/jboss/netty/handler/codec/http/websocket/DefaultWebSocketFrame.java

@@ -20,6 +20,7 @@ import org.jboss.netty.buffer.ChannelBuffers;
 import org.jboss.netty.util.CharsetUtil;
 
 /**
+ * The default {@link WebSocketFrame} implementation.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (trustin@gmail.com)
@@ -30,14 +31,33 @@ public class DefaultWebSocketFrame implements WebSocketFrame {
     private int type;
     private ChannelBuffer binaryData;
 
+    /**
+     * Creates a new empty text frame.
+     */
     public DefaultWebSocketFrame() {
         this(0, ChannelBuffers.EMPTY_BUFFER);
     }
 
+    /**
+     * Creates a new text frame from with the specified string.
+     */
     public DefaultWebSocketFrame(String textData) {
         this(0, ChannelBuffers.copiedBuffer(textData, CharsetUtil.UTF_8));
     }
 
+    /**
+     * Creates a new frame with the specified frame type and the specified data.
+     *
+     * @param type
+     *        the type of the frame. {@code 0} is the only allowed type currently.
+     * @param binaryData
+     *        the content of the frame.  If <tt>(type &amp; 0x80 == 0)</tt>,
+     *        it must be encoded in UTF-8.
+     *
+     * @throws IllegalArgumentException
+     *         if If <tt>(type &amp; 0x80 == 0)</tt> and the data is not encoded
+     *         in UTF-8
+     */
     public DefaultWebSocketFrame(int type, ChannelBuffer binaryData) {
         setData(type, binaryData);
     }

src/main/java/org/jboss/netty/handler/codec/http/websocket/WebSocketFrame.java

@@ -18,16 +18,63 @@ package org.jboss.netty.handler.codec.http.websocket;
 import org.jboss.netty.buffer.ChannelBuffer;
 
 /**
+ * A Web Socket frame that represents either text or binary data.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (trustin@gmail.com)
  * @version $Rev$, $Date$
  */
 public interface WebSocketFrame {
+
+    /**
+     * Returns the type of this frame.
+     * <tt>0x00-0x7F</tt> means a text frame encoded in UTF-8, and
+     * <tt>0x80-0xFF</tt> means a binary frame.  Currently, {@code 0} is the
+     * only allowed type according to the specification.
+     */
     int getType();
+
+    /**
+     * Returns {@code true} if and only if the content of this frame is a string
+     * encoded in UTF-8.
+     */
     boolean isText();
+
+    /**
+     * Returns {@code true} if and only if the content of this frame is an
+     * arbitrary binary data.
+     */
     boolean isBinary();
+
+    /**
+     * Returns the content of this frame as-is, with no UTF-8 decoding.
+     */
     ChannelBuffer getBinaryData();
+
+    /**
+     * Converts the content of this frame into a UTF-8 string and returns the
+     * converted string.
+     */
     String getTextData();
+
+    /**
+     * Sets the type and the content of this frame.
+     *
+     * @param type
+     *        the type of the frame. {@code 0} is the only allowed type currently.
+     * @param binaryData
+     *        the content of the frame.  If <tt>(type &amp; 0x80 == 0)</tt>,
+     *        it must be encoded in UTF-8.
+     *
+     * @throws IllegalArgumentException
+     *         if If <tt>(type &amp; 0x80 == 0)</tt> and the data is not encoded
+     *         in UTF-8
+     */
     void setData(int type, ChannelBuffer binaryData);
+
+    /**
+     * Returns the string representation of this frame.  Please note that this
+     * method is not identical to {@link #getTextData()}.
+     */
+    String toString();
 }

src/main/java/org/jboss/netty/handler/codec/http/websocket/WebSocketFrameDecoder.java

@@ -24,14 +24,16 @@ import org.jboss.netty.handler.codec.replay.ReplayingDecoder;
 import org.jboss.netty.handler.codec.replay.VoidEnum;
 
 /**
- * Decodes the received {@link ChannelBuffer}s as Web Socket frames.  If the Web Socket frame type has its most
+ * Decodes {@link ChannelBuffer}s into {@link WebSocketFrame}s.
- * significant bit set, the Web Socket frame will be sent upstream as a {@link ChannelBuffer} object.  Otherwise,
+ * <p>
- * a {@link String} object is ent upstream.
+ * For the detailed instruction on adding add Web Socket support to your HTTP
+ * server, take a look into the <tt>WebSocketServer</tt> example located in the
+ * {@code org.jboss.netty.example.http.websocket} package.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Mike Heath (mheath@apache.org)
  * @author Trustin Lee (trustin@gmail.com)
- * @version $Rev:$, $Date:$
+ * @version $Rev$, $Date$
  */
 @ChannelPipelineCoverage("one")
 public class WebSocketFrameDecoder extends ReplayingDecoder<VoidEnum> {

src/main/java/org/jboss/netty/handler/codec/http/websocket/WebSocketFrameEncoder.java

@@ -22,12 +22,16 @@ import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.handler.codec.oneone.OneToOneEncoder;
 
 /**
- * Encodes a {@code String} to a {@link ChannelBuffer} inside a Web Socket protocol frame.
+ * Encodes a {@link WebSocketFrame} into a {@link ChannelBuffer}.
+ * <p>
+ * For the detailed instruction on adding add Web Socket support to your HTTP
+ * server, take a look into the <tt>WebSocketServer</tt> example located in the
+ * {@code org.jboss.netty.example.http.websocket} package.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Mike Heath (mheath@apache.org)
  * @author Trustin Lee (trustin@gmail.com)
- * @version $Rev:$, $Date:$
+ * @version $Rev$, $Date$
  */
 @ChannelPipelineCoverage("all")
 public class WebSocketFrameEncoder extends OneToOneEncoder {

src/main/java/org/jboss/netty/handler/codec/http/websocket/package-info.java

@@ -17,7 +17,11 @@
 /**
  * Encoder, decoder and their related message types for
  * <a href="http://en.wikipedia.org/wiki/Web_Sockets">Web Socket</a> data frames.
- *
+ * <p>
+ * For the detailed instruction on adding add Web Socket support to your HTTP
+ * server, take a look into the <tt>WebSocketServer</tt> example located in the
+ * {@code org.jboss.netty.example.http.websocket} package.
+ * *
  * @apiviz.exclude OneToOne(Encoder|Decoder)$
  * @apiviz.exclude \.codec\.replay\.
  */