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