andreacavalli/netty5
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Made the documentation in HttpMessage a bit easier to understand

Browse Source
This commit is contained in:
Cruz Julian Bishop 2012-06-29 16:33:14 +10:00
parent 33c42bee6d
commit 59bb92171b
1 changed files with 87 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
codec-http/src/main/java/io/netty/handler/codec/http/HttpMessage.java
View File

@ -25,8 +25,10 @@ import java.util.Map;
import java.util.Set; import java.util.Set;
/** /**
* An HTTP message which provides common properties for {@link HttpRequest} and * An interface that defines a HTTP message, providing common properties for
* {@link HttpResponse}. * {@link HttpRequest} and {@link HttpResponse}.
* @see HttpResponse
* @see HttpRequest
* @see HttpHeaders * @see HttpHeaders
* *
* @apiviz.landmark * @apiviz.landmark
@ -35,86 +37,111 @@ import java.util.Set;
public interface HttpMessage { public interface HttpMessage {
/** /**
* Returns the header value with the specified header name. If there are * Gets the value of a header with the specified name. If there are
* more than one header value for the specified header name, the first * more than one values for the specified name, the first value is returned.
* 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); 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 * @param name The name of the headers to search
* such header. * @return A {@link List} of header values which will be empty if no values
* are found
*/ */
List<String> getHeaders(String name); List<String> 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 * @return A {@link List} of the header name-value entries, which will be
* if there is no header in this message. * empty if no pairs are found
*/ */
List<Map.Entry<String, String>> getHeaders(); List<Map.Entry<String, String>> getHeaders();
/** /**
* Returns {@code true} if and only if there is a header with the specified * Checks to see if there is a header with the specified name
* header name. *
* @param name The name of the header to search for
* @return True if at least one header is found
*/ */
boolean containsHeader(String name); 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<String> getHeaderNames(); Set<String> getHeaderNames();
/** /**
* Returns the protocol version of this message. * Gets the protocol version of this {@link HttpMessage}
*
* @returns The protocol version
*/ */
HttpVersion getProtocolVersion(); 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); void setProtocolVersion(HttpVersion version);
/** /**
* Returns the content of this message. If there is no content or * Gets the content of this {@link HttpMessage}.
* {@link #isChunked()} returns {@code true}, an *
* {@link Unpooled#EMPTY_BUFFER} is returned. * 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(); ByteBuf getContent();
/** /**
* Sets the content of this message. If {@code null} is specified, * Sets the content of this {@link HttpMessage}.
* the content of this message will be set to {@link Unpooled#EMPTY_BUFFER}. *
* 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); void setContent(ByteBuf content);
/** /**
* Adds a new header with the specified name and value. * 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} * If the specified value is not a {@link String}, it is converted
* and {@link Calendar} which are formatted to the date format defined in * into a {@link String} by {@link Object#toString()}, except in the cases
* <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>. * of {@link Date} and {@link Calendar}, which are formatted to the date
* format defined in <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>.
*
* @param name The name of the header being added
* @param value The value of the header being added
*/ */
void addHeader(String name, Object value); void addHeader(String name, Object value);
/** /**
* Sets a new header with the specified name and value. If there is an * Sets a header with the specified name and value.
* existing header with the same name, the existing header is removed. *
* 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 * If the specified value is not a {@link String}, it is converted into a
* {@link String} by {@link Object#toString()}, except for {@link Date} * {@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
* <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>. * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>.
*
* @param name The name of the header being set
* @param value The value of the header being set
*/ */
void setHeader(String name, Object value); void setHeader(String name, Object value);
/** /**
* Sets a new header with the specified name and values. If there is an * Sets a header with the specified name and values.
* existing header with the same name, the existing header is removed. *
* If there is an existing header with the same name, it is removed.
* This method can be represented approximately as the following code: * This method can be represented approximately as the following code:
* <pre> * <pre>
* m.removeHeader(name); * m.removeHeader(name);
@ -125,42 +152,62 @@ public interface HttpMessage {
* m.addHeader(name, v); * m.addHeader(name, v);
* } * }
* </pre> * </pre>
*
* @param name The name of the headers being set
* @param values The values of the headers being set
*/ */
void setHeader(String name, Iterable<?> values); void setHeader(String name, Iterable<?> values);
/** /**
* Removes the header with the specified name. * Removes the header with the specified name.
*
* @param name The name of the header to remove
*/ */
void removeHeader(String name); void removeHeader(String name);
/** /**
* Removes all headers from this message. * Removes all headers from this {@link HttpMessage}.
*/ */
void clearHeaders(); void clearHeaders();
/** /**
* Returns {@code true} if and only if this message does not have any * Checks to see if this {@link HttpMessage} is broken into multiple "chunks"
* content but the {@link HttpChunk}s, which is generated by *
* {@link HttpMessageDecoder} consecutively, contain the actual content. * 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.
* <p> * <p>
* Please note that this method will keep returning {@code true} if the * Please note that this method will keep returning {@code true} if the
* {@code "Transfer-Encoding"} of this message is {@code "chunked"}, even if * {@code "Transfer-Encoding"} of this message is {@code "chunked"}, even if
* you attempt to override this property by calling {@link #setChunked(boolean)} * you attempt to override this property by calling {@link #setChunked(boolean)}
* with {@code false}. * with {@code false}.
* </p>
*
* @return True if this message is chunked, otherwise false
*/ */
boolean isChunked(); boolean isChunked();
/** /**
* Sets if this message does not have any content but the * Sets the boolean defining if this {@link HttpMessage} is chunked.
* {@link HttpChunk}s, which is generated by {@link HttpMessageDecoder} *
* consecutively, contain the actual content.
* <p> * <p>
* If this method is called with {@code true}, the content of this message * If this is set to true, it means that this initial {@link HttpMessage}
* becomes {@link Unpooled#EMPTY_BUFFER}. * 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}
* </p>
*
* <p> * <p>
* Even if this method is called with {@code false}, {@link #isChunked()} * Even if this method is called with {@code false}, {@link #isChunked()}
* will keep returning {@code true} if the {@code "Transfer-Encoding"} of * will keep returning {@code true} if the {@code "Transfer-Encoding"} of
* this message is {@code "chunked"}. * this message is {@code "chunked"}.
* </p>
*
* @param chunked True if this message is to be delivered in chunks,
* otherwise false.
*/ */
void setChunked(boolean chunked); void setChunked(boolean chunked);
} }