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 32 package org.apache.http; 33 34 import java.io.IOException; 35 import java.io.InputStream; 36 import 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 78 public 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 */ isRepeatable()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 */ isChunked()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 */ getContentLength()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 */ getContentType()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 */ getContentEncoding()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 */ getContent()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 */ writeTo(OutputStream outstream)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 */ isStreaming()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 */ consumeContent()199 void consumeContent() throws IOException; 200 201 } // interface HttpEntity 202