1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 28 package org.apache.http; 29 30 import java.io.IOException; 31 import java.io.InputStream; 32 import java.io.OutputStream; 33 34 /** 35 * An entity that can be sent or received with an HTTP message. 36 * Entities can be found in some 37 * {@link HttpEntityEnclosingRequest requests} and in 38 * {@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, or 44 * generated on the fly. In particular, this category includes 45 * entities being received from a {@link HttpConnection connection}. 46 * {@link #isStreaming Streamed} entities are generally not 47 * {@link #isRepeatable repeatable}. 48 * </li> 49 * <li><b>self-contained</b>: The content is in memory or obtained by 50 * 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 incoming 57 * entities. For entities that are created by an application and only sent 58 * using the HTTP components framework, the difference between streamed 59 * and self-contained is of little importance. In that case, it is suggested 60 * to consider non-repeatable entities as streamed, and those that are 61 * repeatable (without a huge effort) as self-contained. 62 * 63 * @since 4.0 64 */ 65 public interface HttpEntity { 66 67 /** 68 * Tells if the entity is capable of producing its data more than once. 69 * A repeatable entity's getContent() and writeTo(OutputStream) methods 70 * 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 */ 73 boolean isRepeatable(); 74 75 /** 76 * Tells about chunked encoding for this entity. 77 * The primary purpose of this method is to indicate whether 78 * chunked encoding should be used when the entity is sent. 79 * For entities that are received, it can also indicate whether 80 * the entity was received with chunked encoding. 81 * <p> 82 * The behavior of wrapping entities is implementation dependent, 83 * but should respect the primary purpose. 84 * </p> 85 * 86 * @return {@code true} if chunked encoding is preferred for this 87 * entity, or {@code false} if it is not 88 */ 89 boolean isChunked(); 90 91 /** 92 * Tells the length of the content, if known. 93 * 94 * @return the number of bytes of the content, or 95 * a negative number if unknown. If the content length is known 96 * but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE}, 97 * a negative number is returned. 98 */ 99 long getContentLength(); 100 101 /** 102 * Obtains the Content-Type header, if known. 103 * This is the header that should be used when sending the entity, 104 * or the one that was received with the entity. It can include a 105 * charset attribute. 106 * 107 * @return the Content-Type header for this entity, or 108 * {@code null} if the content type is unknown 109 */ 110 Header getContentType(); 111 112 /** 113 * Obtains the Content-Encoding header, if known. 114 * This is the header that should be used when sending the entity, 115 * or the one that was received with the entity. 116 * Wrapping entities that modify the content encoding should 117 * adjust this header accordingly. 118 * 119 * @return the Content-Encoding header for this entity, or 120 * {@code null} if the content encoding is unknown 121 */ 122 Header getContentEncoding(); 123 124 /** 125 * Returns a content stream of the entity. 126 * {@link #isRepeatable Repeatable} entities are expected 127 * to create a new instance of {@link InputStream} for each invocation 128 * of this method and therefore can be consumed multiple times. 129 * Entities that are not {@link #isRepeatable repeatable} are expected 130 * to return the same {@link InputStream} instance and therefore 131 * may not be consumed more than once. 132 * <p> 133 * IMPORTANT: Please note all entity implementations must ensure that 134 * all allocated resources are properly deallocated after 135 * the {@link InputStream#close()} method is invoked. 136 * 137 * @return content stream of the entity. 138 * 139 * @throws IOException if the stream could not be created 140 * @throws UnsupportedOperationException 141 * if entity content cannot be represented as {@link java.io.InputStream}. 142 * 143 * @see #isRepeatable() 144 */ 145 InputStream getContent() throws IOException, UnsupportedOperationException; 146 147 /** 148 * Writes the entity content out to the output stream. 149 * <p> 150 * IMPORTANT: Please note all entity implementations must ensure that 151 * all allocated resources are properly deallocated when this method 152 * returns. 153 * 154 * @param outStream the output stream to write entity content to 155 * 156 * @throws IOException if an I/O error occurs 157 */ 158 void writeTo(OutputStream outStream) throws IOException; 159 160 /** 161 * Tells whether this entity depends on an underlying stream. 162 * Streamed entities that read data directly from the socket should 163 * return {@code true}. Self-contained entities should return 164 * {@code false}. Wrapping entities should delegate this call 165 * to the wrapped entity. 166 * 167 * @return {@code true} if the entity content is streamed, 168 * {@code false} otherwise 169 */ 170 boolean isStreaming(); // don't expect an exception here 171 172 /** 173 * This method is deprecated since version 4.1. Please use standard 174 * java convention to ensure resource deallocation by calling 175 * {@link InputStream#close()} on the input stream returned by 176 * {@link #getContent()} 177 * <p> 178 * This method is called to indicate that the content of this entity 179 * is no longer required. All entity implementations are expected to 180 * release all allocated resources as a result of this method 181 * invocation. Content streaming entities are also expected to 182 * dispose of the remaining content, if any. Wrapping entities should 183 * delegate this call to the wrapped entity. 184 * <p> 185 * This method is of particular importance for entities being 186 * received from a {@link HttpConnection connection}. The entity 187 * needs to be consumed completely in order to re-use the connection 188 * 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 197 void consumeContent() throws IOException; 198 199 }