1/*2 * ====================================================================3 * Licensed to the Apache Software Foundation (ASF) under one4 * or more contributor license agreements. See the NOTICE file5 * distributed with this work for additional information6 * regarding copyright ownership. The ASF licenses this file7 * to you under the Apache License, Version 2.0 (the8 * "License"); you may not use this file except in compliance9 * with the License. You may obtain a copy of the License at10 *11 * http://www.apache.org/licenses/LICENSE-2.012 *13 * Unless required by applicable law or agreed to in writing,14 * software distributed under the License is distributed on an15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY16 * KIND, either express or implied. See the License for the17 * specific language governing permissions and limitations18 * under the License.19 * ====================================================================20 *21 * This software consists of voluntary contributions made by many22 * individuals on behalf of the Apache Software Foundation. For more23 * information on the Apache Software Foundation, please see24 * <http://www.apache.org/>.25 *26 */2728package org.apache.http;
2930import java.io.IOException;
31import java.io.InputStream;
32import java.io.OutputStream;
3334/**35 * An entity that can be sent or received with an HTTP message.36 * Entities can be found in some37 * {@link HttpEntityEnclosingRequest requests} and in38 * {@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, or44 * generated on the fly. In particular, this category includes45 * entities being received from a {@link HttpConnection connection}.46 * {@link #isStreaming Streamed} entities are generally not47 * {@link #isRepeatable repeatable}.48 * </li>49 * <li><b>self-contained</b>: The content is in memory or obtained by50 * 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 incoming57 * entities. For entities that are created by an application and only sent58 * using the HTTP components framework, the difference between streamed59 * and self-contained is of little importance. In that case, it is suggested60 * to consider non-repeatable entities as streamed, and those that are61 * repeatable (without a huge effort) as self-contained.62 *63 * @since 4.064 */65publicinterfaceHttpEntity {
6667/**68 * Tells if the entity is capable of producing its data more than once.69 * A repeatable entity's getContent() and writeTo(OutputStream) methods70 * 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 */73boolean isRepeatable();
7475/**76 * Tells about chunked encoding for this entity.77 * The primary purpose of this method is to indicate whether78 * chunked encoding should be used when the entity is sent.79 * For entities that are received, it can also indicate whether80 * the entity was received with chunked encoding.81 * <br/>82 * The behavior of wrapping entities is implementation dependent,83 * but should respect the primary purpose.84 *85 * @return <code>true</code> if chunked encoding is preferred for this86 * entity, or <code>false</code> if it is not87 */88boolean isChunked();
8990/**91 * Tells the length of the content, if known.92 *93 * @return the number of bytes of the content, or94 * a negative number if unknown. If the content length is known95 * but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE},96 * a negative number is returned.97 */98long getContentLength();
99100/**101 * Obtains the Content-Type header, if known.102 * This is the header that should be used when sending the entity,103 * or the one that was received with the entity. It can include a104 * charset attribute.105 *106 * @return the Content-Type header for this entity, or107 * <code>null</code> if the content type is unknown108 */109Header getContentType();
110111/**112 * Obtains the Content-Encoding header, if known.113 * This is the header that should be used when sending the entity,114 * or the one that was received with the entity.115 * Wrapping entities that modify the content encoding should116 * adjust this header accordingly.117 *118 * @return the Content-Encoding header for this entity, or119 * <code>null</code> if the content encoding is unknown120 */121Header getContentEncoding();
122123/**124 * Returns a content stream of the entity.125 * {@link #isRepeatable Repeatable} entities are expected126 * to create a new instance of {@link InputStream} for each invocation127 * of this method and therefore can be consumed multiple times.128 * Entities that are not {@link #isRepeatable repeatable} are expected129 * to return the same {@link InputStream} instance and therefore130 * may not be consumed more than once.131 * <p>132 * IMPORTANT: Please note all entity implementations must ensure that133 * all allocated resources are properly deallocated after134 * the {@link InputStream#close()} method is invoked.135 *136 * @return content stream of the entity.137 *138 * @throws IOException if the stream could not be created139 * @throws IllegalStateException140 * if content stream cannot be created.141 *142 * @see #isRepeatable()143 */144 InputStream getContent() throws IOException, IllegalStateException;
145146/**147 * Writes the entity content out to the output stream.148 * <p>149 * <p>150 * IMPORTANT: Please note all entity implementations must ensure that151 * all allocated resources are properly deallocated when this method152 * returns.153 *154 * @param outstream the output stream to write entity content to155 *156 * @throws IOException if an I/O error occurs157 */158void writeTo(OutputStream outstream) throws IOException;
159160/**161 * Tells whether this entity depends on an underlying stream.162 * Streamed entities that read data directly from the socket should163 * return <code>true</code>. Self-contained entities should return164 * <code>false</code>. Wrapping entities should delegate this call165 * to the wrapped entity.166 *167 * @return <code>true</code> if the entity content is streamed,168 * <code>false</code> otherwise169 */170boolean isStreaming(); // don't expect an exception here171172/**173 * This method is deprecated since version 4.1. Please use standard174 * java convention to ensure resource deallocation by calling175 * {@link InputStream#close()} on the input stream returned by176 * {@link #getContent()}177 * <p>178 * This method is called to indicate that the content of this entity179 * is no longer required. All entity implementations are expected to180 * release all allocated resources as a result of this method181 * invocation. Content streaming entities are also expected to182 * dispose of the remaining content, if any. Wrapping entities should183 * delegate this call to the wrapped entity.184 * <p>185 * This method is of particular importance for entities being186 * received from a {@link HttpConnection connection}. The entity187 * needs to be consumed completely in order to re-use the connection188 * 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
197void consumeContent() throws IOException;
198199 }