michael@0: /* michael@0: * ==================================================================== michael@0: * Licensed to the Apache Software Foundation (ASF) under one michael@0: * or more contributor license agreements. See the NOTICE file michael@0: * distributed with this work for additional information michael@0: * regarding copyright ownership. The ASF licenses this file michael@0: * to you under the Apache License, Version 2.0 (the michael@0: * "License"); you may not use this file except in compliance michael@0: * with the License. You may obtain a copy of the License at michael@0: * michael@0: * http://www.apache.org/licenses/LICENSE-2.0 michael@0: * michael@0: * Unless required by applicable law or agreed to in writing, michael@0: * software distributed under the License is distributed on an michael@0: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY michael@0: * KIND, either express or implied. See the License for the michael@0: * specific language governing permissions and limitations michael@0: * under the License. michael@0: * ==================================================================== michael@0: * michael@0: * This software consists of voluntary contributions made by many michael@0: * individuals on behalf of the Apache Software Foundation. For more michael@0: * information on the Apache Software Foundation, please see michael@0: * . michael@0: * michael@0: */ michael@0: michael@0: package ch.boye.httpclientandroidlib; michael@0: michael@0: import java.io.IOException; michael@0: import java.io.InputStream; michael@0: import java.io.OutputStream; michael@0: michael@0: /** michael@0: * An entity that can be sent or received with an HTTP message. michael@0: * Entities can be found in some michael@0: * {@link HttpEntityEnclosingRequest requests} and in michael@0: * {@link HttpResponse responses}, where they are optional. michael@0: *

michael@0: * There are three distinct types of entities in HttpCore, michael@0: * depending on where their {@link #getContent content} originates: michael@0: *

michael@0: * This distinction is important for connection management with incoming michael@0: * entities. For entities that are created by an application and only sent michael@0: * using the HTTP components framework, the difference between streamed michael@0: * and self-contained is of little importance. In that case, it is suggested michael@0: * to consider non-repeatable entities as streamed, and those that are michael@0: * repeatable (without a huge effort) as self-contained. michael@0: * michael@0: * @since 4.0 michael@0: */ michael@0: public interface HttpEntity { michael@0: michael@0: /** michael@0: * Tells if the entity is capable of producing its data more than once. michael@0: * A repeatable entity's getContent() and writeTo(OutputStream) methods michael@0: * can be called more than once whereas a non-repeatable entity's can not. michael@0: * @return true if the entity is repeatable, false otherwise. michael@0: */ michael@0: boolean isRepeatable(); michael@0: michael@0: /** michael@0: * Tells about chunked encoding for this entity. michael@0: * The primary purpose of this method is to indicate whether michael@0: * chunked encoding should be used when the entity is sent. michael@0: * For entities that are received, it can also indicate whether michael@0: * the entity was received with chunked encoding. michael@0: *
michael@0: * The behavior of wrapping entities is implementation dependent, michael@0: * but should respect the primary purpose. michael@0: * michael@0: * @return true if chunked encoding is preferred for this michael@0: * entity, or false if it is not michael@0: */ michael@0: boolean isChunked(); michael@0: michael@0: /** michael@0: * Tells the length of the content, if known. michael@0: * michael@0: * @return the number of bytes of the content, or michael@0: * a negative number if unknown. If the content length is known michael@0: * but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE}, michael@0: * a negative number is returned. michael@0: */ michael@0: long getContentLength(); michael@0: michael@0: /** michael@0: * Obtains the Content-Type header, if known. michael@0: * This is the header that should be used when sending the entity, michael@0: * or the one that was received with the entity. It can include a michael@0: * charset attribute. michael@0: * michael@0: * @return the Content-Type header for this entity, or michael@0: * null if the content type is unknown michael@0: */ michael@0: Header getContentType(); michael@0: michael@0: /** michael@0: * Obtains the Content-Encoding header, if known. michael@0: * This is the header that should be used when sending the entity, michael@0: * or the one that was received with the entity. michael@0: * Wrapping entities that modify the content encoding should michael@0: * adjust this header accordingly. michael@0: * michael@0: * @return the Content-Encoding header for this entity, or michael@0: * null if the content encoding is unknown michael@0: */ michael@0: Header getContentEncoding(); michael@0: michael@0: /** michael@0: * Returns a content stream of the entity. michael@0: * {@link #isRepeatable Repeatable} entities are expected michael@0: * to create a new instance of {@link InputStream} for each invocation michael@0: * of this method and therefore can be consumed multiple times. michael@0: * Entities that are not {@link #isRepeatable repeatable} are expected michael@0: * to return the same {@link InputStream} instance and therefore michael@0: * may not be consumed more than once. michael@0: *

michael@0: * IMPORTANT: Please note all entity implementations must ensure that michael@0: * all allocated resources are properly deallocated after michael@0: * the {@link InputStream#close()} method is invoked. michael@0: * michael@0: * @return content stream of the entity. michael@0: * michael@0: * @throws IOException if the stream could not be created michael@0: * @throws IllegalStateException michael@0: * if content stream cannot be created. michael@0: * michael@0: * @see #isRepeatable() michael@0: */ michael@0: InputStream getContent() throws IOException, IllegalStateException; michael@0: michael@0: /** michael@0: * Writes the entity content out to the output stream. michael@0: *

michael@0: *

michael@0: * IMPORTANT: Please note all entity implementations must ensure that michael@0: * all allocated resources are properly deallocated when this method michael@0: * returns. michael@0: * michael@0: * @param outstream the output stream to write entity content to michael@0: * michael@0: * @throws IOException if an I/O error occurs michael@0: */ michael@0: void writeTo(OutputStream outstream) throws IOException; michael@0: michael@0: /** michael@0: * Tells whether this entity depends on an underlying stream. michael@0: * Streamed entities that read data directly from the socket should michael@0: * return true. Self-contained entities should return michael@0: * false. Wrapping entities should delegate this call michael@0: * to the wrapped entity. michael@0: * michael@0: * @return true if the entity content is streamed, michael@0: * false otherwise michael@0: */ michael@0: boolean isStreaming(); // don't expect an exception here michael@0: michael@0: /** michael@0: * This method is deprecated since version 4.1. Please use standard michael@0: * java convention to ensure resource deallocation by calling michael@0: * {@link InputStream#close()} on the input stream returned by michael@0: * {@link #getContent()} michael@0: *

michael@0: * This method is called to indicate that the content of this entity michael@0: * is no longer required. All entity implementations are expected to michael@0: * release all allocated resources as a result of this method michael@0: * invocation. Content streaming entities are also expected to michael@0: * dispose of the remaining content, if any. Wrapping entities should michael@0: * delegate this call to the wrapped entity. michael@0: *

michael@0: * This method is of particular importance for entities being michael@0: * received from a {@link HttpConnection connection}. The entity michael@0: * needs to be consumed completely in order to re-use the connection michael@0: * with keep-alive. michael@0: * michael@0: * @throws IOException if an I/O error occurs. michael@0: * michael@0: * @deprecated Use {@link ch.boye.httpclientandroidlib.util.EntityUtils#consume(HttpEntity)} michael@0: * michael@0: * @see #getContent() and #writeTo(OutputStream) michael@0: */ michael@0: void consumeContent() throws IOException; michael@0: michael@0: }