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 public interface HttpEntity { 74 75 /** 76 * Tells if the entity is capable to produce its data more than once. 77 * A repeatable entity's getContent() and writeTo(OutputStream) methods 78 * can be called more than once whereas a non-repeatable entity's can not. 79 * @return true if the entity is repeatable, false otherwise. 80 */ isRepeatable()81 boolean isRepeatable(); 82 83 /** 84 * Tells about chunked encoding for this entity. 85 * The primary purpose of this method is to indicate whether 86 * chunked encoding should be used when the entity is sent. 87 * For entities that are received, it can also indicate whether 88 * the entity was received with chunked encoding. 89 * <br/> 90 * The behavior of wrapping entities is implementation dependent, 91 * but should respect the primary purpose. 92 * 93 * @return <code>true</code> if chunked encoding is preferred for this 94 * entity, or <code>false</code> if it is not 95 */ isChunked()96 boolean isChunked(); 97 98 /** 99 * Tells the length of the content, if known. 100 * 101 * @return the number of bytes of the content, or 102 * a negative number if unknown. If the content length is known 103 * but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE}, 104 * a negative number is returned. 105 */ getContentLength()106 long getContentLength(); 107 108 /** 109 * Obtains the Content-Type header, if known. 110 * This is the header that should be used when sending the entity, 111 * or the one that was received with the entity. It can include a 112 * charset attribute. 113 * 114 * @return the Content-Type header for this entity, or 115 * <code>null</code> if the content type is unknown 116 */ getContentType()117 Header getContentType(); 118 119 /** 120 * Obtains the Content-Encoding header, if known. 121 * This is the header that should be used when sending the entity, 122 * or the one that was received with the entity. 123 * Wrapping entities that modify the content encoding should 124 * adjust this header accordingly. 125 * 126 * @return the Content-Encoding header for this entity, or 127 * <code>null</code> if the content encoding is unknown 128 */ getContentEncoding()129 Header getContentEncoding(); 130 131 /** 132 * Creates a new InputStream object of the entity. 133 * It is a programming error 134 * to return the same InputStream object more than once. 135 * Entities that are not {@link #isRepeatable repeatable} 136 * will throw an exception if this method is called multiple times. 137 * 138 * @return a new input stream that returns the entity data. 139 * 140 * @throws IOException if the stream could not be created 141 * @throws IllegalStateException 142 * if this entity is not repeatable and the stream 143 * has already been obtained previously 144 */ getContent()145 InputStream getContent() throws IOException, IllegalStateException; 146 147 /** 148 * Writes the entity content to the output stream. 149 * 150 * @param outstream the output stream to write entity content to 151 * 152 * @throws IOException if an I/O error occurs 153 */ writeTo(OutputStream outstream)154 void writeTo(OutputStream outstream) throws IOException; 155 156 /** 157 * Tells whether this entity depends on an underlying stream. 158 * Streamed entities should return <code>true</code> until the 159 * content has been consumed, <code>false</code> afterwards. 160 * Self-contained entities should return <code>false</code>. 161 * Wrapping entities should delegate this call to the wrapped entity. 162 * <br/> 163 * The content of a streamed entity is consumed when the stream 164 * returned by {@link #getContent getContent} has been read to EOF, 165 * or after {@link #consumeContent consumeContent} has been called. 166 * If a streamed entity can not detect whether the stream has been 167 * read to EOF, it should return <code>true</code> until 168 * {@link #consumeContent consumeContent} is called. 169 * 170 * @return <code>true</code> if the entity content is streamed and 171 * not yet consumed, <code>false</code> otherwise 172 */ isStreaming()173 boolean isStreaming(); // don't expect an exception here 174 175 /** 176 * TODO: The name of this method is misnomer. It will be renamed to 177 * #finish() in the next major release. 178 * <br/> 179 * This method is called to indicate that the content of this entity 180 * is no longer required. All entity implementations are expected to 181 * release all allocated resources as a result of this method 182 * invocation. Content streaming entities are also expected to 183 * dispose of the remaining content, if any. Wrapping entities should 184 * delegate this call to the wrapped entity. 185 * <br/> 186 * This method is of particular importance for entities being 187 * received from a {@link HttpConnection connection}. The entity 188 * needs to be consumed completely in order to re-use the connection 189 * with keep-alive. 190 * 191 * @throws IOException if an I/O error occurs. 192 * This indicates that connection keep-alive is not possible. 193 */ consumeContent()194 void consumeContent() throws IOException; 195 196 } // interface HttpEntity 197