mobile/android/thirdparty/ch/boye/httpclientandroidlib/HttpEntity.java@fc2d59ddac77
mobile/android/thirdparty/ch/boye/httpclientandroidlib/HttpEntity.java
Wed, 31 Dec 2014 07:22:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 07:22:50 +0100
- branch
- TOR_BUG_3246
- changeset 4
- fc2d59ddac77
- permissions
- -rw-r--r--
Correct previous dual key logic pending first delivery installment.
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 */
28 package ch.boye.httpclientandroidlib;
30 import java.io.IOException;
31 import java.io.InputStream;
32 import java.io.OutputStream;
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 {
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();
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();
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();
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();
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();
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;
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;
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
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 Use {@link ch.boye.httpclientandroidlib.util.EntityUtils#consume(HttpEntity)}
193 *
194 * @see #getContent() and #writeTo(OutputStream)
195 */
196 void consumeContent() throws IOException;
198 }
