1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package org.jboss.netty.handler.codec.http;
17
18 import java.util.List;
19 import java.util.Map;
20 import java.util.Set;
21
22 import org.jboss.netty.buffer.ChannelBuffer;
23 import org.jboss.netty.buffer.ChannelBuffers;
24
25 /**
26 * An HTTP message which provides common properties for {@link HttpRequest} and
27 * {@link HttpResponse}.
28 * @see HttpHeaders
29 *
30 * @apiviz.landmark
31 * @apiviz.has org.jboss.netty.handler.codec.http.HttpChunk oneway - - is followed by
32 */
33 public interface HttpMessage {
34
35 /**
36 * Returns the header value with the specified header name. If there are
37 * more than one header value for the specified header name, the first
38 * value is returned.
39 *
40 * @return the header value or {@code null} if there is no such header
41 */
42 String getHeader(String name);
43
44 /**
45 * Returns the header values with the specified header name.
46 *
47 * @return the {@link List} of header values. An empty list if there is no
48 * such header.
49 */
50 List<String> getHeaders(String name);
51
52 /**
53 * Returns the all header names and values that this message contains.
54 *
55 * @return the {@link List} of the header name-value pairs. An empty list
56 * if there is no header in this message.
57 */
58 List<Map.Entry<String, String>> getHeaders();
59
60 /**
61 * Returns {@code true} if and only if there is a header with the specified
62 * header name.
63 */
64 boolean containsHeader(String name);
65
66 /**
67 * Returns the {@link Set} of all header names that this message contains.
68 */
69 Set<String> getHeaderNames();
70
71 /**
72 * Returns the protocol version of this message.
73 */
74 HttpVersion getProtocolVersion();
75
76 /**
77 * Sets the protocol version of this message.
78 */
79 void setProtocolVersion(HttpVersion version);
80
81 /**
82 * Returns the content of this message. If there is no content or
83 * {@link #isChunked()} returns {@code true}, an
84 * {@link ChannelBuffers#EMPTY_BUFFER} is returned.
85 */
86 ChannelBuffer getContent();
87
88 /**
89 * Sets the content of this message. If {@code null} is specified,
90 * the content of this message will be set to {@link ChannelBuffers#EMPTY_BUFFER}.
91 */
92 void setContent(ChannelBuffer content);
93
94 /**
95 * Adds a new header with the specified name and value.
96 */
97 void addHeader(String name, Object value);
98
99 /**
100 * Sets a new header with the specified name and value. If there is an
101 * existing header with the same name, the existing header is removed.
102 */
103 void setHeader(String name, Object value);
104
105 /**
106 * Sets a new header with the specified name and values. If there is an
107 * existing header with the same name, the existing header is removed.
108 */
109 void setHeader(String name, Iterable<?> values);
110
111 /**
112 * Removes the header with the specified name.
113 */
114 void removeHeader(String name);
115
116 /**
117 * Removes all headers from this message.
118 */
119 void clearHeaders();
120
121 /**
122 * @deprecated Use {@link HttpHeaders#getContentLength(HttpMessage)} instead.
123 */
124 @Deprecated
125 long getContentLength();
126
127 /**
128 * @deprecated Use {@link HttpHeaders#getContentLength(HttpMessage, long)} instead.
129 */
130 @Deprecated
131 long getContentLength(long defaultValue);
132
133 /**
134 * Returns {@code true} if and only if this message does not have any
135 * content but the {@link HttpChunk}s, which is generated by
136 * {@link HttpMessageDecoder} consecutively, contain the actual content.
137 * <p>
138 * Please note that this method will keep returning {@code true} if the
139 * {@code "Transfer-Encoding"} of this message is {@code "chunked"}, even if
140 * you attempt to override this property by calling {@link #setChunked(boolean)}
141 * with {@code false}.
142 */
143 boolean isChunked();
144
145 /**
146 * Sets if this message does not have any content but the
147 * {@link HttpChunk}s, which is generated by {@link HttpMessageDecoder}
148 * consecutively, contain the actual content.
149 * <p>
150 * If this method is called with {@code true}, the content of this message
151 * becomes {@link ChannelBuffers#EMPTY_BUFFER}.
152 * <p>
153 * Even if this method is called with {@code false}, {@link #isChunked()}
154 * will keep returning {@code true} if the {@code "Transfer-Encoding"} of
155 * this message is {@code "chunked"}.
156 */
157 void setChunked(boolean chunked);
158
159 /**
160 * @deprecated Use {@link HttpHeaders#isKeepAlive(HttpMessage)} instead.
161 */
162 @Deprecated
163 boolean isKeepAlive();
164 }