Javadoc

src/main/java/org/jboss/netty/handler/codec/http/Cookie.java

@@ -24,32 +24,125 @@ package org.jboss.netty.handler.codec.http;
 import java.util.Set;
 
 /**
+ * An <a href="http://en.wikipedia.org/wiki/HTTP_cookie">HTTP Cookie</a>.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @author Andy Taylor (andy.taylor@jboss.org)
  * @version $Rev$, $Date$
  */
 public interface Cookie extends Comparable<Cookie> {
+
+    /**
+     * Returns the name of this cookie.
+     */
     String getName();
+
+    /**
+     * Returns the value of this cookie.
+     */
     String getValue();
+
+    /**
+     * Sets the value of this cookie.
+     */
     void setValue(String value);
+
+    /**
+     * Returns the domain of this cookie.
+     */
     String getDomain();
+
+    /**
+     * Sets the domain of this cookie.
+     */
     void setDomain(String domain);
+
+    /**
+     * Returns the path of this cookie.
+     */
     String getPath();
+
+    /**
+     * Sets the path of this cookie.
+     */
     void setPath(String path);
+
+    /**
+     * Returns the comment of this cookie.
+     */
     String getComment();
+
+    /**
+     * Sets the comment of this cookie.
+     */
     void setComment(String comment);
+
+    /**
+     * Returns the max age of this cookie in seconds.
+     */
     int getMaxAge();
+
+    /**
+     * Sets the max age of this cookie in seconds.  If {@code 0} is specified,
+     * this cookie will be removed by browser because it will be expired
+     * immediately.  If {@code -1} is specified, this cookie will be removed
+     * when a user terminates browser.
+     */
     void setMaxAge(int maxAge);
+
+    /**
+     * Returns the version of this cookie.
+     */
     int getVersion();
+
+    /**
+     * Sets the version of this cookie.
+     */
     void setVersion(int version);
+
+    /**
+     * Returns the secure flag of this cookie.
+     */
     boolean isSecure();
+
+    /**
+     * Sets the secure flag of this cookie.
+     */
     void setSecure(boolean secure);
+
+    /**
+     * Returns the comment URL of this cookie.
+     */
     String getCommentUrl();
+
+    /**
+     * Sets the comment URL of this cookie.
+     */
     void setCommentUrl(String commentUrl);
+
+    /**
+     * Returns the discard flag of this cookie.
+     */
     boolean isDiscard();
+
+    /**
+     * Sets the discard flag of this cookie.
+     */
     void setDiscard(boolean discard);
+
+    /**
+     * Returns the ports of this cookie.
+     */
     Set<Integer> getPorts();
+
+    /**
+     * Sets the ports of this cookie.
+     */
     void setPorts(int... ports);
+
+    /**
+     * Sets the ports of this cookie.
+     */
     void setPorts(Iterable<Integer> ports);
 }

src/main/java/org/jboss/netty/handler/codec/http/CookieDecoder.java

@@ -31,6 +31,9 @@ import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 /**
+ * Decodes an HTTP header value into {@link Cookie}s.  This decoder can decode
+ * the HTTP cookie version 0, 1, and 2.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Andy Taylor (andy.taylor@jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -43,10 +46,18 @@ public class CookieDecoder {
 
     private final static String COMMA = ",";
 
+    /**
+     * Creates a new decoder.
+     */
     public CookieDecoder() {
         super();
     }
 
+    /**
+     * Decodes the specified HTTP header value into {@link Cookie}s.
+     *
+     * @return the decoded {@link Cookie}s
+     */
     public Set<Cookie> decode(String header) {
         Matcher m = PATTERN.matcher(header);
         List<String> names = new ArrayList<String>(8);

src/main/java/org/jboss/netty/handler/codec/http/CookieEncoder.java

@@ -26,6 +26,15 @@ import java.util.Set;
 import java.util.TreeSet;
 
 /**
+ * Encodes {@link Cookie}s into an HTTP header value.  This encoder can encode
+ * the HTTP cookie version 0, 1, and 2.
+ * <p>
+ * This encoder is stateful.  It maintains an internal data structure that
+ * holds the {@link Cookie}s added by the {@link #addCookie(String, String)}
+ * method.  Once {@link #encode()} is called, all added {@link Cookie}s are
+ * encoded into an HTTP header value and all {@link Cookie}s in the internal
+ * data structure are removed so that the encoder can start over.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Andy Taylor (andy.taylor@jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -36,24 +45,46 @@ public class CookieEncoder {
     private final Set<Cookie> cookies = new TreeSet<Cookie>();
     private final boolean server;
 
+    /**
+     * Creates a new encoder.
+     *
+     * @param server {@code true} if and only if this encoder is supposed to
+     *               encode server-side cookies.  {@code false} if and only if
+     *               this encoder is supposed to encode client-side cookies.
+     */
     public CookieEncoder(boolean server) {
         this.server = server;
     }
 
+    /**
+     * Adds a new {@link Cookie} created with the specified name and value to
+     * this encoder.
+     */
     public void addCookie(String name, String value) {
         cookies.add(new DefaultCookie(name, value));
     }
 
+    /**
+     * Adds the specified {@link Cookie} to this encoder.
+     */
     public void addCookie(Cookie cookie) {
         cookies.add(cookie);
     }
 
+    /**
+     * Encodes the {@link Cookie}s which were added by {@link #addCookie(Cookie)}
+     * so far into an HTTP header value.  If no {@link Cookie}s were added,
+     * an empty string is returned.
+     */
     public String encode() {
+        String answer;
         if (server) {
-            return encodeServerSide();
+            answer = encodeServerSide();
         } else {
-            return encodeClientSide();
+            answer = encodeClientSide();
         }
+        cookies.clear();
+        return answer;
     }
 
     private String encodeServerSide() {

src/main/java/org/jboss/netty/handler/codec/http/DefaultHttpChunk.java

@@ -38,7 +38,7 @@ public class DefaultHttpChunk implements HttpChunk {
 
     /**
      * Creates a new instance with the specified chunk content. If an empty
-     * buffer is specified, this chunk becomes the 'end of chunk' marker.
+     * buffer is specified, this chunk becomes the 'end of content' marker.
      */
     public DefaultHttpChunk(ChannelBuffer content) {
         if (content == null) {

src/main/java/org/jboss/netty/handler/codec/http/HttpChunk.java

@@ -26,14 +26,29 @@ import org.jboss.netty.buffer.ChannelBuffer;
 import org.jboss.netty.buffer.ChannelBuffers;
 
 /**
+ * An <a href="http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol">HTTP</a>
+ * chunk.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$
  */
 public interface HttpChunk {
 
+    /**
+     * The 'end of content' maker in chunked encoding.
+     */
     static HttpChunk LAST_CHUNK = new DefaultHttpChunk(ChannelBuffers.EMPTY_BUFFER);
 
+    /**
+     * Returns {@code true} if and only if this chunk is the 'end of content'
+     * marker.
+     */
     boolean isLast();
+
+    /**
+     * Returns the content of this chunk.  If this is the 'end of content'
+     * maker, {@link ChannelBuffers#EMPTY_BUFFER} will be returned.
+     */
     ChannelBuffer getContent();
 }

src/main/java/org/jboss/netty/handler/codec/http/QueryStringDecoder.java

@@ -33,6 +33,9 @@ import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 /**
+ * Splits an HTTP query string into a path string and key-value parameter pairs.
+ * This decoder is for one time use only.  Create a new instance for each URI.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Andy Taylor (andy.taylor@jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -49,10 +52,18 @@ public class QueryStringDecoder {
     private String path;
     private final Map<String, List<String>> params = new HashMap<String, List<String>>();
 
+    /**
+     * Creates a new decoder that decodes the specified URI. The decoder will
+     * assume that the query string is encoded in UTF-8.
+     */
     public QueryStringDecoder(String uri) {
         this(uri, HttpCodecUtil.DEFAULT_CHARSET);
     }
 
+    /**
+     * Creates a new decoder that decodes the specified URI encoded in the
+     * specified charset.
+     */
     public QueryStringDecoder(String uri, String charset) {
         if (uri == null) {
             throw new NullPointerException("uri");
@@ -65,10 +76,18 @@ public class QueryStringDecoder {
         this.charset = charset;
     }
 
+    /**
+     * Creates a new decoder that decodes the specified URI. The decoder will
+     * assume that the query string is encoded in UTF-8.
+     */
     public QueryStringDecoder(URI uri) {
         this(uri, HttpCodecUtil.DEFAULT_CHARSET);
     }
 
+    /**
+     * Creates a new decoder that decodes the specified URI encoded in the
+     * specified charset.
+     */
     public QueryStringDecoder(URI uri, String charset){
         if (uri == null) {
             throw new NullPointerException("uri");
@@ -81,6 +100,9 @@ public class QueryStringDecoder {
         this.charset = charset;
     }
 
+    /**
+     * Returns the decoded path string of the URI.
+     */
     public String getPath() {
         //decode lazily
         if(path == null) {
@@ -94,6 +116,9 @@ public class QueryStringDecoder {
         return path;
     }
 
+    /**
+     * Returns the decoded key-value parameter pairs of the URI.
+     */
     public Map<String, List<String>> getParameters() {
         if(path == null){
             if(uri.contains("?")) {

src/main/java/org/jboss/netty/handler/codec/http/QueryStringEncoder.java

@@ -30,6 +30,9 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
+ * Creates an URL-encoded URI from a path string and key-value parameter pairs.
+ * This encoder is for one time use only.  Create a new instance for each URI.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Andy Taylor (andy.taylor@jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -43,10 +46,18 @@ public class QueryStringEncoder {
     private final String uri;
     private final List<Param> params = new ArrayList<Param>();
 
+    /**
+     * Creates a new encoder that encodes a URI that starts with the specified
+     * path string.  The encoder will encode the URI in UTF-8.
+     */
     public QueryStringEncoder(String uri) {
         this(uri, HttpCodecUtil.DEFAULT_CHARSET);
     }
 
+    /**
+     * Creates a new encoder that encodes a URI that starts with the specified
+     * path string in the specified charset.
+     */
     public QueryStringEncoder(String uri, String charset) {
         if (uri == null) {
             throw new NullPointerException("uri");
@@ -59,6 +70,9 @@ public class QueryStringEncoder {
         this.charset = charset;
     }
 
+    /**
+     * Adds a parameter with the specified name and value to this encoder.
+     */
     public void addParam(String name, String value) {
         if (name == null) {
             throw new NullPointerException("name");
@@ -69,10 +83,20 @@ public class QueryStringEncoder {
         params.add(new Param(name, value));
     }
 
+    /**
+     * Returns the URL-encoded URI object which was created from the path string
+     * specified in the constructor and the parameters added by
+     * {@link #addParam(String, String)} method.
+     */
     public URI toUri() throws URISyntaxException {
         return new URI(toString());
     }
 
+    /**
+     * Returns the URL-encoded URI which was created from the path string
+     * specified in the constructor and the parameters added by
+     * {@link #addParam(String, String)} method.
+     */
     @Override
     public String toString() {
         if (params.isEmpty()) {