Made the documentation in HttpMessage a bit easier to understand
This commit is contained in:
Cruz Julian Bishop
parent
33c42bee6d
commit
59bb92171b
@ -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<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
|
||||
* 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<Map.Entry<String, String>> 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<String> 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
|
||||
* <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>.
|
||||
*
|
||||
* 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 <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);
|
||||
|
||||
/**
|
||||
* 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
|
||||
* <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);
|
||||
|
||||
/**
|
||||
* 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:
|
||||
* <pre>
|
||||
* m.removeHeader(name);
|
||||
@ -125,42 +152,62 @@ public interface HttpMessage {
|
||||
* m.addHeader(name, v);
|
||||
* }
|
||||
* </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);
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* <p>
|
||||
* 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}.
|
||||
* </p>
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* <p>
|
||||
* 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}
|
||||
* </p>
|
||||
*
|
||||
* <p>
|
||||
* 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"}.
|
||||
* </p>
|
||||
*
|
||||
* @param chunked True if this message is to be delivered in chunks,
|
||||
* otherwise false.
|
||||
*/
|
||||
void setChunked(boolean chunked);
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user