diff --git a/codec-http/src/main/java/io/netty/handler/codec/http/HttpMessage.java b/codec-http/src/main/java/io/netty/handler/codec/http/HttpMessage.java index 36a33bb967..6e0a29a8d4 100644 --- a/codec-http/src/main/java/io/netty/handler/codec/http/HttpMessage.java +++ b/codec-http/src/main/java/io/netty/handler/codec/http/HttpMessage.java @@ -25,8 +25,10 @@ import java.util.Map; import java.util.Set; /** - * An HTTP message which provides common properties for {@link HttpRequest} and - * {@link HttpResponse}. + * An interface that defines a HTTP message, providing common properties for + * {@link HttpRequest} and {@link HttpResponse}. + * @see HttpResponse + * @see HttpRequest * @see HttpHeaders * * @apiviz.landmark @@ -35,86 +37,111 @@ import java.util.Set; public interface HttpMessage { /** - * Returns the header value with the specified header name. If there are - * more than one header value for the specified header name, the first - * value is returned. + * Gets the value of a header with the specified name. If there are + * more than one values for the specified name, the first value is returned. * - * @return the header value or {@code null} if there is no such header + * @param name The name of the header to search + * @return The first header value or {@code null} if there is no such header */ String getHeader(String name); /** - * Returns the header values with the specified header name. + * Returns the values of headers with the specified name * - * @return the {@link List} of header values. An empty list if there is no - * such header. + * @param name The name of the headers to search + * @return A {@link List} of header values which will be empty if no values + * are found */ List getHeaders(String name); /** - * Returns the all header names and values that this message contains. + * Returns the all headers that this message contains. * - * @return the {@link List} of the header name-value pairs. An empty list - * if there is no header in this message. + * @return A {@link List} of the header name-value entries, which will be + * empty if no pairs are found */ List> getHeaders(); /** - * Returns {@code true} if and only if there is a header with the specified - * header name. + * Checks to see if there is a header with the specified name + * + * @param name The name of the header to search for + * @return True if at least one header is found */ boolean containsHeader(String name); /** - * Returns the {@link Set} of all header names that this message contains. + * Gets a {@link Set} of all header names that this message contains + * + * @return A {@link Set} of all header names */ Set getHeaderNames(); /** - * Returns the protocol version of this message. + * Gets the protocol version of this {@link HttpMessage} + * + * @returns The protocol version */ HttpVersion getProtocolVersion(); /** - * Sets the protocol version of this message. + * Sets the protocol version of this {@link HttpMessage} + * + * @param version The version to set */ void setProtocolVersion(HttpVersion version); /** - * Returns the content of this message. If there is no content or - * {@link #isChunked()} returns {@code true}, an - * {@link Unpooled#EMPTY_BUFFER} is returned. + * Gets the content of this {@link HttpMessage}. + * + * If there is no content or {@link #isChunked()} returns {@code true}, + * an {@link Unpooled#EMPTY_BUFFER} is returned. + * + * @return A {@link ByteBuf} containing this {@link HttpMessage}'s content */ ByteBuf getContent(); /** - * Sets the content of this message. If {@code null} is specified, - * the content of this message will be set to {@link Unpooled#EMPTY_BUFFER}. + * Sets the content of this {@link HttpMessage}. + * + * If {@code null} is specified, the content of this message + * will be set to {@link Unpooled#EMPTY_BUFFER} + * + * @param content The {@link ByteBuf} containing the content to use */ void setContent(ByteBuf content); /** * Adds a new header with the specified name and value. - * If the specified value is not a {@link String}, it is converted into a - * {@link String} by {@link Object#toString()}, except for {@link Date} - * and {@link Calendar} which are formatted to the date format defined in - * RFC2616. + * + * If the specified value is not a {@link String}, it is converted + * into a {@link String} by {@link Object#toString()}, except in the cases + * of {@link Date} and {@link Calendar}, which are formatted to the date + * format defined in RFC2616. + * + * @param name The name of the header being added + * @param value The value of the header being added */ void addHeader(String name, Object value); /** - * Sets a new header with the specified name and value. If there is an - * existing header with the same name, the existing header is removed. + * Sets a header with the specified name and value. + * + * If there is an existing header with the same name, it is removed. * If the specified value is not a {@link String}, it is converted into a * {@link String} by {@link Object#toString()}, except for {@link Date} - * and {@link Calendar} which are formatted to the date format defined in + * and {@link Calendar}, which are formatted to the date format defined in * RFC2616. + * + * @param name The name of the header being set + * @param value The value of the header being set */ void setHeader(String name, Object value); /** - * Sets a new header with the specified name and values. If there is an - * existing header with the same name, the existing header is removed. + * Sets a header with the specified name and values. + * + * If there is an existing header with the same name, it is removed. * This method can be represented approximately as the following code: * 
      * m.removeHeader(name);
@@ -125,42 +152,62 @@ public interface HttpMessage {
      *     m.addHeader(name, v);
      * }
      *
+ * + * @param name The name of the headers being set + * @param values The values of the headers being set */ void setHeader(String name, Iterable values); /** * Removes the header with the specified name. + * + * @param name The name of the header to remove */ void removeHeader(String name); /** - * Removes all headers from this message. + * Removes all headers from this {@link HttpMessage}. */ void clearHeaders(); /** - * Returns {@code true} if and only if this message does not have any - * content but the {@link HttpChunk}s, which is generated by - * {@link HttpMessageDecoder} consecutively, contain the actual content. + * Checks to see if this {@link HttpMessage} is broken into multiple "chunks" + * + * If this returns true, it means that this {@link HttpMessage} + * actually has no content - The {@link HttpChunk}s (which are generated + * by the {@link HttpMessageDecoder} consecutively) contain the actual content. *

* Please note that this method will keep returning {@code true} if the * {@code "Transfer-Encoding"} of this message is {@code "chunked"}, even if * you attempt to override this property by calling {@link #setChunked(boolean)} * with {@code false}. + *

+ * + * @return True if this message is chunked, otherwise false */ boolean isChunked(); /** - * Sets if this message does not have any content but the - * {@link HttpChunk}s, which is generated by {@link HttpMessageDecoder} - * consecutively, contain the actual content. + * Sets the boolean defining if this {@link HttpMessage} is chunked. + * *

- * If this method is called with {@code true}, the content of this message - * becomes {@link Unpooled#EMPTY_BUFFER}. + * If this is set to true, it means that this initial {@link HttpMessage} + * does not contain any content - The content is contained by multiple + * {@link HttpChunk}s, which are generated by the {@link HttpMessageDecoder} + * consecutively. + * + * Because of this, the content of this {@link HttpMessage} becomes + * {@link Unpooled#EMPTY_BUFFER} + *

+ * *

* Even if this method is called with {@code false}, {@link #isChunked()} * will keep returning {@code true} if the {@code "Transfer-Encoding"} of * this message is {@code "chunked"}. + *

+ * + * @param chunked True if this message is to be delivered in chunks, + * otherwise false. */ void setChunked(boolean chunked); }