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 * IMPORTANT: Please note all entity implementations must ensure that 89 * all allocated resources are properly deallocated after 90 * the {@link InputStream#close()} method is invoked. 91 * </p> 92 * @return content stream of the entity. 93 * 94 * @throws IOException if the stream could not be created 95 * @throws UnsupportedOperationException 96 * if entity content cannot be represented as {@link java.io.InputStream}. 97 * 98 * @see #isRepeatable() 99 */ 100 InputStream getContent() throws IOException, UnsupportedOperationException; 101 102 /** 103 * Writes the entity content out to the output stream. 104 * <p> 105 * IMPORTANT: Please note all entity implementations must ensure that 106 * all allocated resources are properly deallocated when this method 107 * returns. 108 * </p> 109 * 110 * @param outStream the output stream to write entity content to 111 * 112 * @throws IOException if an I/O error occurs 113 */ 114 void writeTo(OutputStream outStream) throws IOException; 115 116 /** 117 * Tells whether this entity depends on an underlying stream. 118 * Streamed entities that read data directly from the socket should 119 * return {@code true}. Self-contained entities should return 120 * {@code false}. Wrapping entities should delegate this call 121 * to the wrapped entity. 122 * 123 * @return {@code true} if the entity content is streamed, 124 * {@code false} otherwise 125 */ 126 boolean isStreaming(); // don't expect an exception here 127 128 /** 129 * Returns supplier of message trailers - headers sent after message body. 130 * May return {@code null} if trailers are not available. 131 * 132 * @since 5.0 133 */ 134 Supplier<List<? extends Header>> getTrailers(); 135 136 }