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

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

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

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

+ *

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

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

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