From f15db3a65e7ed57c4401afe33607f0113019362c Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Mon, 20 Jul 2009 03:37:35 +0000 Subject: [PATCH] Updated APIviz tags and improved Javadoc of the HTTP codec --- .../org/jboss/netty/handler/codec/http/Cookie.java | 2 ++ .../netty/handler/codec/http/CookieDecoder.java | 6 ++++++ .../netty/handler/codec/http/CookieEncoder.java | 13 +++++++++++++ .../jboss/netty/handler/codec/http/HttpChunk.java | 2 ++ .../handler/codec/http/HttpChunkAggregator.java | 1 + .../jboss/netty/handler/codec/http/HttpMessage.java | 4 +++- .../handler/codec/http/HttpMessageDecoder.java | 2 ++ .../handler/codec/http/HttpMessageEncoder.java | 2 ++ .../jboss/netty/handler/codec/http/HttpRequest.java | 9 +++++++++ .../netty/handler/codec/http/HttpResponse.java | 7 +++++++ .../handler/codec/http/QueryStringDecoder.java | 4 +++- .../handler/codec/http/QueryStringEncoder.java | 4 +++- .../netty/handler/codec/http/package-info.java | 3 ++- 13 files changed, 55 insertions(+), 4 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 01029773b0..8085fe550e 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 @@ -31,6 +31,8 @@ import java.util.Set; * @author Trustin Lee (tlee@redhat.com) * @author Andy Taylor (andy.taylor@jboss.org) * @version $Rev$, $Date$ + * + * @apiviz.landmark */ public interface Cookie extends Comparable { 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 e73e6517e9..bb327be0b9 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 @@ -35,6 +35,12 @@ 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. * + * 
+ * HttpRequest req = ...;
+ * String value = req.getHeader("Cookie");
+ * Set<Cookie> cookies = new CookieDecoder().decode(value);
+ *
+ * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) * @author Trustin Lee (tlee@redhat.com) 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 ecde55b7dc..4291bd6300 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 @@ -35,6 +35,19 @@ import java.util.TreeSet; * 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. + * 
+ * // Client-side example
+ * HttpRequest req = ...;
+ * CookieEncoder encoder = new CookieEncoder(false);
+ * encoder.addCookie("JSESSIONID", "1234");
+ * res.setHeader("Cookie", encoder.encode());
+ *
+ * // Server-side example
+ * HttpResponse res = ...;
+ * CookieEncoder encoder = new CookieEncoder(true);
+ * encoder.addCookie("JSESSIONID", "1234");
+ * res.setHeader("Set-Cookie", encoder.encode());
+ *
* * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) 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 06722f2166..63cebaa96d 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 @@ -39,6 +39,8 @@ import org.jboss.netty.channel.ChannelPipeline; * @version $Rev$, $Date$ * * @see HttpChunkAggregator + * + * @apiviz.landmark */ public interface HttpChunk { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpChunkAggregator.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpChunkAggregator.java index b9ff38daee..3852428ca4 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpChunkAggregator.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpChunkAggregator.java @@ -55,6 +55,7 @@ import org.jboss.netty.handler.codec.frame.TooLongFrameException; * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ * + * @apiviz.landmark * @apiviz.has org.jboss.netty.handler.codec.http.HttpChunk oneway - - filters out */ @ChannelPipelineCoverage("one") diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpMessage.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpMessage.java index 0c2eda6854..260dfffe52 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpMessage.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpMessage.java @@ -37,8 +37,10 @@ import org.jboss.netty.buffer.ChannelBuffers; * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ * + * @see HttpHeaders + * + * @apiviz.landmark * @apiviz.has org.jboss.netty.handler.codec.http.HttpChunk oneway - - is followed by - * @apiviz.uses org.jboss.netty.handler.codec.http.HttpHeaders - - useful */ public interface HttpMessage { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageDecoder.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageDecoder.java index 6e7114ed0e..048f2eddc8 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageDecoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageDecoder.java @@ -79,6 +79,8 @@ import org.jboss.netty.handler.codec.replay.ReplayingDecoder; * @author Andy Taylor (andy.taylor@jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ + * + * @apiviz.landmark */ public abstract class HttpMessageDecoder extends ReplayingDecoder { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageEncoder.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageEncoder.java index 03d946cd64..6d042b1a8e 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageEncoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageEncoder.java @@ -53,6 +53,8 @@ import org.jboss.netty.handler.codec.oneone.OneToOneEncoder; * @author Andy Taylor (andy.taylor@jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ + * + * @apiviz.landmark */ @ChannelPipelineCoverage("all") public abstract class HttpMessageEncoder extends OneToOneEncoder { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpRequest.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpRequest.java index 9e69c08479..8a2c9b6738 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpRequest.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpRequest.java @@ -26,6 +26,13 @@ package org.jboss.netty.handler.codec.http; /** * An HTTP request. * + *

Accessing Query Parameters and Cookie

+ *

+ * Unlike the Servlet API, a query string is constructed and decomposed by + * {@link QueryStringEncoder} and {@link QueryStringDecoder}. {@link Cookie} + * support is also provided separately via {@link CookieEncoder} and + * {@link CookieDecoder}. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) * @version $Rev$, $Date$ @@ -33,6 +40,8 @@ package org.jboss.netty.handler.codec.http; * @see HttpResponse * @see QueryStringEncoder * @see QueryStringDecoder + * @see CookieEncoder + * @see CookieDecoder */ public interface HttpRequest extends HttpMessage { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpResponse.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpResponse.java index 85c674d883..c66edbbc76 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpResponse.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpResponse.java @@ -26,12 +26,19 @@ package org.jboss.netty.handler.codec.http; /** * An HTTP response. * + *

Accessing Cookie

+ *

+ * Unlike the Servlet API, {@link Cookie} support is provided separately via + * {@link CookieEncoder} and {@link CookieDecoder}. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ * * @see HttpRequest + * @see CookieEncoder + * @see CookieDecoder */ public interface HttpResponse extends HttpMessage { 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 0ba125c12a..7e2aaaafa3 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 @@ -47,8 +47,10 @@ import java.util.regex.Pattern; * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ * - * @apiviz.stereotype utility * @see QueryStringEncoder + * + * @apiviz.stereotype utility + * @apiviz.has org.jboss.netty.handler.codec.http.HttpRequest oneway - - decodes */ public class QueryStringDecoder { 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 17666aace0..772ff3100a 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 @@ -45,8 +45,10 @@ import java.util.List; * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ * - * @apiviz.stereotype utility * @see QueryStringDecoder + * + * @apiviz.stereotype utility + * @apiviz.has org.jboss.netty.handler.codec.http.HttpRequest oneway - - encodes */ public class QueryStringEncoder { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/package-info.java b/src/main/java/org/jboss/netty/handler/codec/http/package-info.java index fec3495a7f..56d35e9c3b 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/package-info.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/package-info.java @@ -24,9 +24,10 @@ /** * Encoder, decoder and their related message types for HTTP. * - * @apiviz.exclude HttpHeaders\. * @apiviz.exclude ^java\.lang\. * @apiviz.exclude OneToOne(Encoder|Decoder)$ + * @apiviz.exclude HttpHeaders + * @apiviz.exclude (QueryString|Cookie)(Encoder|Decoder)$ * @apiviz.exclude \.codec\.replay\. * @apiviz.exclude \.(Simple)?Channel[A-Za-z]*Handler$ */