diff options
Diffstat (limited to 'src/org/apache/http/HttpEntity.java')
| -rw-r--r-- | src/org/apache/http/HttpEntity.java | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/src/org/apache/http/HttpEntity.java b/src/org/apache/http/HttpEntity.java new file mode 100644 index 0000000..51ddafc --- /dev/null +++ b/src/org/apache/http/HttpEntity.java @@ -0,0 +1,196 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpEntity.java $ + * $Revision: 645824 $ + * $Date: 2008-04-08 03:12:41 -0700 (Tue, 08 Apr 2008) $ + * + * ==================================================================== + * 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 org.apache.http; + +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> + * In some places, the JavaDoc distinguishes three kinds of entities, + * 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. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @version $Revision: 645824 $ + * + * @since 4.0 + */ +public interface HttpEntity { + + /** + * Tells if the entity is capable to produce 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(); + + /** + * Creates a new InputStream object of the entity. + * It is a programming error + * to return the same InputStream object more than once. + * Entities that are not {@link #isRepeatable repeatable} + * will throw an exception if this method is called multiple times. + * + * @return a new input stream that returns the entity data. + * + * @throws IOException if the stream could not be created + * @throws IllegalStateException + * if this entity is not repeatable and the stream + * has already been obtained previously + */ + InputStream getContent() throws IOException, IllegalStateException; + + /** + * Writes the entity content to the output stream. + * + * @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 should return <code>true</code> until the + * content has been consumed, <code>false</code> afterwards. + * Self-contained entities should return <code>false</code>. + * Wrapping entities should delegate this call to the wrapped entity. + * <br/> + * The content of a streamed entity is consumed when the stream + * returned by {@link #getContent getContent} has been read to EOF, + * or after {@link #consumeContent consumeContent} has been called. + * If a streamed entity can not detect whether the stream has been + * read to EOF, it should return <code>true</code> until + * {@link #consumeContent consumeContent} is called. + * + * @return <code>true</code> if the entity content is streamed and + * not yet consumed, <code>false</code> otherwise + */ + boolean isStreaming(); // don't expect an exception here + + /** + * TODO: The name of this method is misnomer. It will be renamed to + * #finish() in the next major release. + * <br/> + * 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. + * <br/> + * 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. + * This indicates that connection keep-alive is not possible. + */ + void consumeContent() throws IOException; + +} // interface HttpEntity |