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.hc.core5.http;
29
30 import java.io.Closeable;
31 import java.io.IOException;
32 import java.io.InputStream;
33 import java.io.OutputStream;
34 import java.util.List;
35
36 import org.apache.hc.core5.function.Supplier;
37
38 /**
39 * An entity that can be sent or received with an HTTP message.
40 * <p>
41 * There are three distinct types of entities in HttpCore,
42 * depending on where their {@link #getContent content} originates:
43 * </p>
44 * <ul>
45 * <li><b>streamed</b>: The content is received from a stream, or
46 * generated on the fly. In particular, this category includes
47 * entities being received from a {@link HttpConnection connection}.
48 * {@link #isStreaming Streamed} entities are generally not
49 * {@link #isRepeatable repeatable}.
50 * </li>
51 * <li><b>self-contained</b>: The content is in memory or obtained by
52 * means that are independent from a connection or other entity.
53 * Self-contained entities are generally {@link #isRepeatable repeatable}.
54 * </li>
55 * <li><b>wrapping</b>: The content is obtained from another entity.
56 * </li>
57 * </ul>
58 * <p>
59 * This distinction is important for connection management with incoming
60 * entities. For entities that are created by an application and only sent
61 * using the HTTP components framework, the difference between streamed
62 * and self-contained is of little importance. In that case, it is suggested
63 * to consider non-repeatable entities as streamed, and those that are
64 * repeatable (without a huge effort) as self-contained.
65 * </p>
66 *
67 * @since 4.0
68 */
69 public interface HttpEntity extends EntityDetails, Closeable {
70
71 /**
72 * Tells if the entity is capable of producing its data more than once.
73 * A repeatable entity's getContent() and writeTo(OutputStream) methods
74 * can be called more than once whereas a non-repeatable entity's can not.
75 * @return true if the entity is repeatable, false otherwise.
76 */
77 boolean isRepeatable();
78
79 /**
80 * Returns a content stream of the entity.
81 * {@link #isRepeatable Repeatable} entities are expected
82 * to create a new instance of {@link InputStream} for each invocation
83 * of this method and therefore can be consumed multiple times.
84 * Entities that are not {@link #isRepeatable repeatable} are expected
85 * to return the same {@link InputStream} instance and therefore
86 * may not be consumed more than once.
87 * <p>
88 * If this entity belongs to an incoming HTTP message, calling
89 * {@link InputStream#close()} on the returned {@code InputStream} will
90 * try to consume the complete entity content to keep the connection
91 * alive. In cases where this is undesired, e.g. when only a small part
92 * of the content is relevant and consuming the complete entity content
93 * would be too inefficient, <i>only</i> the HTTP message from which
94 * this entity was obtained should be closed (if supported).
95 * </p>
96 * <p>
97 * IMPORTANT: Please note all entity implementations must ensure that
98 * all allocated resources are properly deallocated after
99 * the {@link InputStream#close()} method is invoked.
100 * </p>
101 * @return content stream of the entity.
102 *
103 * @throws IOException if the stream could not be created
104 * @throws UnsupportedOperationException
105 * if entity content cannot be represented as {@link java.io.InputStream}.
106 *
107 * @see #isRepeatable()
108 */
109 InputStream getContent() throws IOException, UnsupportedOperationException;
110
111 /**
112 * Writes the entity content out to the output stream.
113 * <p>
114 * IMPORTANT: Please note all entity implementations must ensure that
115 * all allocated resources are properly deallocated when this method
116 * returns.
117 * </p>
118 *
119 * @param outStream the output stream to write entity content to
120 *
121 * @throws IOException if an I/O error occurs
122 */
123 void writeTo(OutputStream outStream) throws IOException;
124
125 /**
126 * Tells whether this entity depends on an underlying stream.
127 * Streamed entities that read data directly from the socket should
128 * return {@code true}. Self-contained entities should return
129 * {@code false}. Wrapping entities should delegate this call
130 * to the wrapped entity.
131 *
132 * @return {@code true} if the entity content is streamed,
133 * {@code false} otherwise
134 */
135 boolean isStreaming(); // don't expect an exception here
136
137 /**
138 * Returns supplier of message trailers - headers sent after message body.
139 * May return {@code null} if trailers are not available.
140 *
141 * @since 5.0
142 */
143 Supplier<List<? extends Header>> getTrailers();
144
145 }