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