1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27
28 package org.apache.http;
29
30 import java.io.IOException;
31 import java.io.InputStream;
32 import java.io.OutputStream;
33
34 /**
35 * An entity that can be sent or received with an HTTP message.
36 * Entities can be found in some
37 * {@link HttpEntityEnclosingRequest requests} and in
38 * {@link HttpResponse responses}, where they are optional.
39 * <p>
40 * There are three distinct types of entities in HttpCore,
41 * depending on where their {@link #getContent content} originates:
42 * <ul>
43 * <li><b>streamed</b>: The content is received from a stream, or
44 * generated on the fly. In particular, this category includes
45 * entities being received from a {@link HttpConnection connection}.
46 * {@link #isStreaming Streamed} entities are generally not
47 * {@link #isRepeatable repeatable}.
48 * </li>
49 * <li><b>self-contained</b>: The content is in memory or obtained by
50 * means that are independent from a connection or other entity.
51 * Self-contained entities are generally {@link #isRepeatable repeatable}.
52 * </li>
53 * <li><b>wrapping</b>: The content is obtained from another entity.
54 * </li>
55 * </ul>
56 * This distinction is important for connection management with incoming
57 * entities. For entities that are created by an application and only sent
58 * using the HTTP components framework, the difference between streamed
59 * and self-contained is of little importance. In that case, it is suggested
60 * to consider non-repeatable entities as streamed, and those that are
61 * repeatable (without a huge effort) as self-contained.
62 *
63 * @since 4.0
64 */
65 public interface HttpEntity {
66
67 /**
68 * Tells if the entity is capable of producing its data more than once.
69 * A repeatable entity's getContent() and writeTo(OutputStream) methods
70 * can be called more than once whereas a non-repeatable entity's can not.
71 * @return true if the entity is repeatable, false otherwise.
72 */
73 boolean isRepeatable();
74
75 /**
76 * Tells about chunked encoding for this entity.
77 * The primary purpose of this method is to indicate whether
78 * chunked encoding should be used when the entity is sent.
79 * For entities that are received, it can also indicate whether
80 * the entity was received with chunked encoding.
81 * <p>
82 * The behavior of wrapping entities is implementation dependent,
83 * but should respect the primary purpose.
84 * </p>
85 *
86 * @return {@code true} if chunked encoding is preferred for this
87 * entity, or {@code false} if it is not
88 */
89 boolean isChunked();
90
91 /**
92 * Tells the length of the content, if known.
93 *
94 * @return the number of bytes of the content, or
95 * a negative number if unknown. If the content length is known
96 * but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE},
97 * a negative number is returned.
98 */
99 long getContentLength();
100
101 /**
102 * Obtains the Content-Type header, if known.
103 * This is the header that should be used when sending the entity,
104 * or the one that was received with the entity. It can include a
105 * charset attribute.
106 *
107 * @return the Content-Type header for this entity, or
108 * {@code null} if the content type is unknown
109 */
110 Header getContentType();
111
112 /**
113 * Obtains the Content-Encoding header, if known.
114 * This is the header that should be used when sending the entity,
115 * or the one that was received with the entity.
116 * Wrapping entities that modify the content encoding should
117 * adjust this header accordingly.
118 *
119 * @return the Content-Encoding header for this entity, or
120 * {@code null} if the content encoding is unknown
121 */
122 Header getContentEncoding();
123
124 /**
125 * Returns a content stream of the entity.
126 * {@link #isRepeatable Repeatable} entities are expected
127 * to create a new instance of {@link InputStream} for each invocation
128 * of this method and therefore can be consumed multiple times.
129 * Entities that are not {@link #isRepeatable repeatable} are expected
130 * to return the same {@link InputStream} instance and therefore
131 * may not be consumed more than once.
132 * <p>
133 * IMPORTANT: Please note all entity implementations must ensure that
134 * all allocated resources are properly deallocated after
135 * the {@link InputStream#close()} method is invoked.
136 *
137 * @return content stream of the entity.
138 *
139 * @throws IOException if the stream could not be created
140 * @throws UnsupportedOperationException
141 * if entity content cannot be represented as {@link java.io.InputStream}.
142 *
143 * @see #isRepeatable()
144 */
145 InputStream getContent() throws IOException, UnsupportedOperationException;
146
147 /**
148 * Writes the entity content out to the output stream.
149 * <p>
150 * IMPORTANT: Please note all entity implementations must ensure that
151 * all allocated resources are properly deallocated when this method
152 * returns.
153 *
154 * @param outStream the output stream to write entity content to
155 *
156 * @throws IOException if an I/O error occurs
157 */
158 void writeTo(OutputStream outStream) throws IOException;
159
160 /**
161 * Tells whether this entity depends on an underlying stream.
162 * Streamed entities that read data directly from the socket should
163 * return {@code true}. Self-contained entities should return
164 * {@code false}. Wrapping entities should delegate this call
165 * to the wrapped entity.
166 *
167 * @return {@code true} if the entity content is streamed,
168 * {@code false} otherwise
169 */
170 boolean isStreaming(); // don't expect an exception here
171
172 /**
173 * This method is deprecated since version 4.1. Please use standard
174 * java convention to ensure resource deallocation by calling
175 * {@link InputStream#close()} on the input stream returned by
176 * {@link #getContent()}
177 * <p>
178 * This method is called to indicate that the content of this entity
179 * is no longer required. All entity implementations are expected to
180 * release all allocated resources as a result of this method
181 * invocation. Content streaming entities are also expected to
182 * dispose of the remaining content, if any. Wrapping entities should
183 * delegate this call to the wrapped entity.
184 * <p>
185 * This method is of particular importance for entities being
186 * received from a {@link HttpConnection connection}. The entity
187 * needs to be consumed completely in order to re-use the connection
188 * with keep-alive.
189 *
190 * @throws IOException if an I/O error occurs.
191 *
192 * @deprecated (4.1) Use {@link org.apache.http.util.EntityUtils#consume(HttpEntity)}
193 *
194 * @see #getContent() and #writeTo(OutputStream)
195 */
196 @Deprecated
197 void consumeContent() throws IOException;
198
199 }