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