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 }