View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http;
29  
30  import java.io.IOException;
31  import java.io.InputStream;
32  import java.io.OutputStream;
33  
34  /**
35   * An entity that can be sent or received with an HTTP message.
36   * Entities can be found in some
37   * {@link HttpEntityEnclosingRequest requests} and in
38   * {@link HttpResponse responses}, where they are optional.
39   * <p>
40   * There are three distinct types of entities in HttpCore,
41   * depending on where their {@link #getContent content} originates:
42   * <ul>
43   * <li><b>streamed</b>: The content is received from a stream, or
44   *     generated on the fly. In particular, this category includes
45   *     entities being received from a {@link HttpConnection connection}.
46   *     {@link #isStreaming Streamed} entities are generally not
47   *      {@link #isRepeatable repeatable}.
48   *     </li>
49   * <li><b>self-contained</b>: The content is in memory or obtained by
50   *     means that are independent from a connection or other entity.
51   *     Self-contained entities are generally {@link #isRepeatable repeatable}.
52   *     </li>
53   * <li><b>wrapping</b>: The content is obtained from another entity.
54   *     </li>
55   * </ul>
56   * This distinction is important for connection management with incoming
57   * entities. For entities that are created by an application and only sent
58   * using the HTTP components framework, the difference between streamed
59   * and self-contained is of little importance. In that case, it is suggested
60   * to consider non-repeatable entities as streamed, and those that are
61   * repeatable (without a huge effort) as self-contained.
62   *
63   * @since 4.0
64   */
65  public interface HttpEntity {
66  
67      /**
68       * Tells if the entity is capable of producing its data more than once.
69       * A repeatable entity's getContent() and writeTo(OutputStream) methods
70       * can be called more than once whereas a non-repeatable entity's can not.
71       * @return true if the entity is repeatable, false otherwise.
72       */
73      boolean isRepeatable();
74  
75      /**
76       * Tells about chunked encoding for this entity.
77       * The primary purpose of this method is to indicate whether
78       * chunked encoding should be used when the entity is sent.
79       * For entities that are received, it can also indicate whether
80       * the entity was received with chunked encoding.
81       * <br/>
82       * The behavior of wrapping entities is implementation dependent,
83       * but should respect the primary purpose.
84       *
85       * @return  <code>true</code> if chunked encoding is preferred for this
86       *          entity, or <code>false</code> if it is not
87       */
88      boolean isChunked();
89  
90      /**
91       * Tells the length of the content, if known.
92       *
93       * @return  the number of bytes of the content, or
94       *          a negative number if unknown. If the content length is known
95       *          but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE},
96       *          a negative number is returned.
97       */
98      long getContentLength();
99  
100     /**
101      * Obtains the Content-Type header, if known.
102      * This is the header that should be used when sending the entity,
103      * or the one that was received with the entity. It can include a
104      * charset attribute.
105      *
106      * @return  the Content-Type header for this entity, or
107      *          <code>null</code> if the content type is unknown
108      */
109     Header getContentType();
110 
111     /**
112      * Obtains the Content-Encoding header, if known.
113      * This is the header that should be used when sending the entity,
114      * or the one that was received with the entity.
115      * Wrapping entities that modify the content encoding should
116      * adjust this header accordingly.
117      *
118      * @return  the Content-Encoding header for this entity, or
119      *          <code>null</code> if the content encoding is unknown
120      */
121     Header getContentEncoding();
122 
123     /**
124      * Returns a content stream of the entity.
125      * {@link #isRepeatable Repeatable} entities are expected
126      * to create a new instance of {@link InputStream} for each invocation
127      * of this method and therefore can be consumed multiple times.
128      * Entities that are not {@link #isRepeatable repeatable} are expected
129      * to return the same {@link InputStream} instance and therefore
130      * may not be consumed more than once.
131      * <p>
132      * IMPORTANT: Please note all entity implementations must ensure that
133      * all allocated resources are properly deallocated after
134      * the {@link InputStream#close()} method is invoked.
135      *
136      * @return content stream of the entity.
137      *
138      * @throws IOException if the stream could not be created
139      * @throws IllegalStateException
140      *  if content stream cannot be created.
141      *
142      * @see #isRepeatable()
143      */
144     InputStream getContent() throws IOException, IllegalStateException;
145 
146     /**
147      * Writes the entity content out to the output stream.
148      * <p>
149      * <p>
150      * IMPORTANT: Please note all entity implementations must ensure that
151      * all allocated resources are properly deallocated when this method
152      * returns.
153      *
154      * @param outstream the output stream to write entity content to
155      *
156      * @throws IOException if an I/O error occurs
157      */
158     void writeTo(OutputStream outstream) throws IOException;
159 
160     /**
161      * Tells whether this entity depends on an underlying stream.
162      * Streamed entities that read data directly from the socket should
163      * return <code>true</code>. Self-contained entities should return
164      * <code>false</code>. Wrapping entities should delegate this call
165      * to the wrapped entity.
166      *
167      * @return  <code>true</code> if the entity content is streamed,
168      *          <code>false</code> otherwise
169      */
170     boolean isStreaming(); // don't expect an exception here
171 
172     /**
173      * This method is deprecated since version 4.1. Please use standard
174      * java convention to ensure resource deallocation by calling
175      * {@link InputStream#close()} on the input stream returned by
176      * {@link #getContent()}
177      * <p>
178      * This method is called to indicate that the content of this entity
179      * is no longer required. All entity implementations are expected to
180      * release all allocated resources as a result of this method
181      * invocation. Content streaming entities are also expected to
182      * dispose of the remaining content, if any. Wrapping entities should
183      * delegate this call to the wrapped entity.
184      * <p>
185      * This method is of particular importance for entities being
186      * received from a {@link HttpConnection connection}. The entity
187      * needs to be consumed completely in order to re-use the connection
188      * with keep-alive.
189      *
190      * @throws IOException if an I/O error occurs.
191      *
192      * @deprecated (4.1) Use {@link org.apache.http.util.EntityUtils#consume(HttpEntity)}
193      *
194      * @see #getContent() and #writeTo(OutputStream)
195      */
196     @Deprecated
197     void consumeContent() throws IOException;
198 
199 }