001: /*
002: * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.0-beta1/module-main/src/main/java/org/apache/http/HttpEntity.java $
003: * $Revision: 496070 $
004: * $Date: 2007-01-14 13:18:34 +0100 (Sun, 14 Jan 2007) $
005: *
006: * ====================================================================
007: * Licensed to the Apache Software Foundation (ASF) under one
008: * or more contributor license agreements. See the NOTICE file
009: * distributed with this work for additional information
010: * regarding copyright ownership. The ASF licenses this file
011: * to you under the Apache License, Version 2.0 (the
012: * "License"); you may not use this file except in compliance
013: * with the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing,
018: * software distributed under the License is distributed on an
019: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
020: * KIND, either express or implied. See the License for the
021: * specific language governing permissions and limitations
022: * under the License.
023: * ====================================================================
024: *
025: * This software consists of voluntary contributions made by many
026: * individuals on behalf of the Apache Software Foundation. For more
027: * information on the Apache Software Foundation, please see
028: * <http://www.apache.org/>.
029: *
030: */
031:
032: package org.apache.http;
033:
034: import java.io.IOException;
035: import java.io.InputStream;
036: import java.io.OutputStream;
037:
038: /**
039: * An entity that can be sent or received with an HTTP message.
040: * Entities can be found in some
041: * {@link HttpEntityEnclosingRequest requests} and in
042: * {@link HttpResponse responses}, where they are optional.
043: * <p>
044: * In some places, the JavaDoc distinguishes three kinds of entities,
045: * depending on where their {@link #getContent content} originates:
046: * <ul>
047: * <li><b>streamed</b>: The content is received from a stream, or
048: * generated on the fly. In particular, this category includes
049: * entities being received from a {@link HttpConnection connection}.
050: * {@link #isStreaming Streamed} entities are generally not
051: * {@link #isRepeatable repeatable}.
052: * </li>
053: * <li><b>self-contained</b>: The content is in memory or obtained by
054: * means that are independent from a connection or other entity.
055: * Self-contained entities are generally {@link #isRepeatable repeatable}.
056: * </li>
057: * <li><b>wrapping</b>: The content is obtained from another entity.
058: * </li>
059: * </ul>
060: * This distinction is important for connection management with incoming
061: * entities. For entities that are created by an application and only sent
062: * using the HTTP components framework, the difference between streamed
063: * and self-contained is of little importance. In that case, it is suggested
064: * to consider non-repeatable entities as streamed, and those that are
065: * repeatable (without a huge effort) as self-contained.
066: *
067: * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
068: *
069: * @version $Revision: 496070 $
070: *
071: * @since 4.0
072: */
073: public interface HttpEntity {
074:
075: /**
076: * Tells if the entity is capable to produce its data more than once.
077: * A repeatable entity's getContent() and writeTo(OutputStream) methods
078: * can be called more than once whereas a non-repeatable entity's can not.
079: * @return true if the entity is repeatable, false otherwise.
080: */
081: boolean isRepeatable();
082:
083: /**
084: * Tells about chunked encoding for this entity.
085: * The primary purpose of this method is to indicate whether
086: * chunked encoding should be used when the entity is sent.
087: * For entities that are received, it can also indicate whether
088: * the entity was received with chunked encoding.
089: * <br/>
090: * The behavior of wrapping entities is implementation dependent,
091: * but should respect the primary purpose.
092: *
093: * @return <code>true</code> if chunked encoding is preferred for this
094: * entity, or <code>false</code> if it is not
095: */
096: boolean isChunked();
097:
098: /**
099: * Tells the length of the content, if known.
100: *
101: * @return the number of bytes of the content, or
102: * a negative number if unknown. If the content length is known
103: * but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE},
104: * a negative number is returned.
105: */
106: long getContentLength();
107:
108: /**
109: * Obtains the Content-Type header, if known.
110: * This is the header that should be used when sending the entity,
111: * or the one that was received with the entity. It can include a
112: * charset attribute.
113: *
114: * @return the Content-Type header for this entity, or
115: * <code>null</code> if the content type is unknown
116: */
117: Header getContentType();
118:
119: /**
120: * Obtains the Content-Encoding header, if known.
121: * This is the header that should be used when sending the entity,
122: * or the one that was received with the entity.
123: * Wrapping entities that modify the content encoding should
124: * adjust this header accordingly.
125: *
126: * @return the Content-Encoding header for this entity, or
127: * <code>null</code> if the content encoding is unknown
128: */
129: Header getContentEncoding();
130:
131: /**
132: * Creates a new InputStream object of the entity.
133: * It is a programming error
134: * to return the same InputStream object more than once.
135: * Entities that are not {@link #isRepeatable repeatable}
136: * will throw an exception if this method is called multiple times.
137: *
138: * @return a new input stream that returns the entity data.
139: *
140: * @throws IOException if the stream could not be created
141: * @throws IllegalStateException
142: * if this entity is not repeatable and the stream
143: * has already been obtained previously
144: */
145: InputStream getContent() throws IOException, IllegalStateException;
146:
147: /**
148: * Writes the entity content to the output stream.
149: *
150: * @param outstream the output stream to write entity content to
151: *
152: * @throws IOException if an I/O error occurs
153: */
154: void writeTo(OutputStream outstream) throws IOException;
155:
156: /**
157: * Tells whether this entity depends on an underlying stream.
158: * Streamed entities should return <code>true</code> until the
159: * content has been consumed, <code>false</code> afterwards.
160: * Self-contained entities should return <code>false</code>.
161: * Wrapping entities should delegate this call to the wrapped entity.
162: * <br/>
163: * The content of a streamed entity is consumed when the stream
164: * returned by {@link #getContent getContent} has been read to EOF,
165: * or after {@link #consumeContent consumeContent} has been called.
166: * If a streamed entity can not detect whether the stream has been
167: * read to EOF, it should return <code>true</code> until
168: * {@link #consumeContent consumeContent} is called.
169: *
170: * @return <code>true</code> if the entity content is streamed and
171: * not yet consumed, <code>false</code> otherwise
172: */
173: boolean isStreaming(); // don't expect an exception here
174:
175: /**
176: * Consumes the remaining content of a streamed entity.
177: * This method is called to indicate that the content of this entity
178: * is no longer required.
179: * Streamed entities should dispose of the remaining content, if any.
180: * Self-contained entities can release allocated resources, but
181: * are not required to do anything.
182: * Wrapping entities should delegate this call to the wrapped entity.
183: * <br/>
184: * This method is of particular importance for entities being
185: * received from a {@link HttpConnection connection}. The entity
186: * needs to be consumed completely in order to re-use the connection
187: * with keep-alive.
188: *
189: * @throws IOException if an I/O error occurs.
190: * This indicates that connection keep-alive is not possible.
191: */
192: void consumeContent() throws IOException;
193:
194: } // interface HttpEntity
|