From 997dc9081a5657b28038314eec4e3c363925b90e Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Fri, 19 Jun 2009 14:49:26 +0000 Subject: [PATCH] Javadoc --- .../netty/handler/codec/http/Cookie.java | 93 +++++++++++++++++++ .../handler/codec/http/CookieDecoder.java | 11 +++ .../handler/codec/http/CookieEncoder.java | 35 ++++++- .../handler/codec/http/DefaultHttpChunk.java | 2 +- .../netty/handler/codec/http/HttpChunk.java | 15 +++ .../codec/http/QueryStringDecoder.java | 25 +++++ .../codec/http/QueryStringEncoder.java | 24 +++++ 7 files changed, 202 insertions(+), 3 deletions(-) diff --git a/src/main/java/org/jboss/netty/handler/codec/http/Cookie.java b/src/main/java/org/jboss/netty/handler/codec/http/Cookie.java index da516f37cf..e714e9164a 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/Cookie.java +++ b/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 HTTP Cookie. + * * @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 { + + /** + * 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 getPorts(); + + /** + * Sets the ports of this cookie. + */ void setPorts(int... ports); + + /** + * Sets the ports of this cookie. + */ void setPorts(Iterable ports); } \ No newline at end of file diff --git a/src/main/java/org/jboss/netty/handler/codec/http/CookieDecoder.java b/src/main/java/org/jboss/netty/handler/codec/http/CookieDecoder.java index 768e2db32b..e6c194ebdf 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/CookieDecoder.java +++ b/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 decode(String header) { Matcher m = PATTERN.matcher(header); List names = new ArrayList(8); diff --git a/src/main/java/org/jboss/netty/handler/codec/http/CookieEncoder.java b/src/main/java/org/jboss/netty/handler/codec/http/CookieEncoder.java index 325a1ce568..f18a00c8c4 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/CookieEncoder.java +++ b/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. + *

+ * 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 cookies = new TreeSet(); 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() { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/DefaultHttpChunk.java b/src/main/java/org/jboss/netty/handler/codec/http/DefaultHttpChunk.java index f1839b4cd1..c63f8866d3 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/DefaultHttpChunk.java +++ b/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) { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpChunk.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpChunk.java index 89b180578a..10c5589b23 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpChunk.java +++ b/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 HTTP + * 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(); } diff --git a/src/main/java/org/jboss/netty/handler/codec/http/QueryStringDecoder.java b/src/main/java/org/jboss/netty/handler/codec/http/QueryStringDecoder.java index dea9e21e7d..1df102ff0a 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/QueryStringDecoder.java +++ b/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> params = new HashMap>(); + /** + * 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> getParameters() { if(path == null){ if(uri.contains("?")) { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/QueryStringEncoder.java b/src/main/java/org/jboss/netty/handler/codec/http/QueryStringEncoder.java index 52552c56bc..f184f7e0f2 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/QueryStringEncoder.java +++ b/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 params = new ArrayList(); + /** + * 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()) {