diff options
Diffstat (limited to 'mobile/android/thirdparty/ch/boye/httpclientandroidlib/HttpEntity.java')
| -rw-r--r-- | mobile/android/thirdparty/ch/boye/httpclientandroidlib/HttpEntity.java | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/mobile/android/thirdparty/ch/boye/httpclientandroidlib/HttpEntity.java b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/HttpEntity.java new file mode 100644 index 000000000..5e223c1ec --- /dev/null +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/HttpEntity.java @@ -0,0 +1,199 @@ +/* + * ==================================================================== + * 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 + * <http://www.apache.org/>. + * + */ + +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. + * <p> + * There are three distinct types of entities in HttpCore, + * depending on where their {@link #getContent content} originates: + * <ul> + * <li><b>streamed</b>: The content is received from a stream, or + * generated on the fly. In particular, this category includes + * entities being received from a {@link HttpConnection connection}. + * {@link #isStreaming Streamed} entities are generally not + * {@link #isRepeatable repeatable}. + * </li> + * <li><b>self-contained</b>: The content is in memory or obtained by + * means that are independent from a connection or other entity. + * Self-contained entities are generally {@link #isRepeatable repeatable}. + * </li> + * <li><b>wrapping</b>: The content is obtained from another entity. + * </li> + * </ul> + * 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. + * <br/> + * The behavior of wrapping entities is implementation dependent, + * but should respect the primary purpose. + * + * @return <code>true</code> if chunked encoding is preferred for this + * entity, or <code>false</code> 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 + * <code>null</code> 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 + * <code>null</code> 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. + * <p> + * 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. + * <p> + * <p> + * 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 <code>true</code>. Self-contained entities should return + * <code>false</code>. Wrapping entities should delegate this call + * to the wrapped entity. + * + * @return <code>true</code> if the entity content is streamed, + * <code>false</code> 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()} + * <p> + * 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. + * <p> + * 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 (4.1) Use {@link ch.boye.httpclientandroidlib.util.EntityUtils#consume(HttpEntity)} + * + * @see #getContent() and #writeTo(OutputStream) + */ + @Deprecated + void consumeContent() throws IOException; + +} |