hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r1659788 - in /httpcomponents/httpcore/trunk: httpcore/src/main/java/org/apache/http/HttpEntity.java src/docbkx/fundamentals.xml
Date Sat, 14 Feb 2015 12:55:06 GMT
Author: olegk
Date: Sat Feb 14 12:55:05 2015
New Revision: 1659788

URL: http://svn.apache.org/r1659788
Log:
HTTPCORE-394: clarification of the HttpEntity#getContent method contract

Modified:
    httpcomponents/httpcore/trunk/httpcore/src/main/java/org/apache/http/HttpEntity.java
    httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml

Modified: httpcomponents/httpcore/trunk/httpcore/src/main/java/org/apache/http/HttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore/src/main/java/org/apache/http/HttpEntity.java?rev=1659788&r1=1659787&r2=1659788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore/src/main/java/org/apache/http/HttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/httpcore/src/main/java/org/apache/http/HttpEntity.java Sat
Feb 14 12:55:05 2015
@@ -134,12 +134,12 @@ public interface HttpEntity {
      * @return content stream of the entity.
      *
      * @throws IOException if the stream could not be created
-     * @throws IllegalStateException
-     *  if content stream cannot be created.
+     * @throws UnsupportedOperationException
+     *  if entity content cannot be represented as {@link java.io.InputStream}.
      *
      * @see #isRepeatable()
      */
-    InputStream getContent() throws IOException, IllegalStateException;
+    InputStream getContent() throws IOException, UnsupportedOperationException;
 
     /**
      * Writes the entity content out to the output stream.

Modified: httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml?rev=1659788&r1=1659787&r2=1659788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml (original)
+++ httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml Sat Feb 14 12:55:05 2015
@@ -227,17 +227,10 @@ c3 = c
                     </formalpara>
                 </listitem>
             </itemizedlist>
-            <para>
-            This distinction is important for connection management with incoming entities.
For
-            an application that creates entities and only sends them using the HttpCore framework,
-            the difference between streamed and self-contained is of little importance. In
that
-            case, we suggest you consider non-repeatable entities as streamed, and those
that
-            are repeatable as self-contained.
-            </para>
             <section>
                 <title>Repeatable entities</title>
                 <para>
-                An entity can be repeatable, meaning you can read its content more than once.
This
+                An entity can be repeatable, meaning its content can be read more than once.
This
                 is only possible with self-contained entities (like
                 <classname>ByteArrayEntity</classname> or <classname>StringEntity</classname>).
                 </para>
@@ -258,7 +251,12 @@ c3 = c
                 the <methodname>HttpEntity#getContent()</methodname> method,
which returns an
                 <classname>java.io.InputStream</classname>, or one can supply
an output stream to
                 the <methodname>HttpEntity#writeTo(OutputStream)</methodname>
method, which will
-                return once all content has been written to the given stream.
+                return once all content has been written to the given stream. Please note
that
+                some non-streaming (self-contained) entities may be unable to represent their
+                content as a <classname>java.io.InputStream</classname> efficiently.
It is legal
+                for such entities to implement <methodname>HttpEntity#writeTo(OutputStream)
+                </methodname> method only and to throw <classname>UnsupportedOperationException
+                </classname> from <methodname>HttpEntity#getContent()</methodname>
method.
                 </para>
                 <para>
                 The <classname>EntityUtils</classname> class exposes several
static methods to simplify 



Mime
View raw message