You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by sebb <se...@gmail.com> on 2013/07/21 00:05:22 UTC
Re: svn commit: r1504858 - in /httpcomponents/httpcore/trunk/src/docbkx:
fundamentals.xml nio-ext.xml
On 19 July 2013 13:34, <gg...@apache.org> wrote:
> Author: ggregory
> Date: Fri Jul 19 12:34:14 2013
> New Revision: 1504858
>
> URL: http://svn.apache.org/r1504858
> Log:
> More edits from proof-reading. About 1/2 way done w fundamentals.
>
> Modified:
> httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml
> httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml
>
> Modified: httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml
> URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml?rev=1504858&r1=1504857&r2=1504858&view=diff
> ==============================================================================
> --- httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml (original)
> +++ httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml Fri Jul 19 12:34:14 2013
> @@ -237,8 +237,8 @@ c3 = c
> <section>
> <title>Repeatable entities</title>
> <para>
> - An entity can be repeatable, meaning its content can be read more than once. This
> - is only possible with self contained entities (like
> + An entity can be repeatable, meaning you can read its content more than once. This
> + is only possible with self-contained entities (like
> <classname>ByteArrayEntity</classname> or <classname>StringEntity</classname>).
> </para>
> </section>
> @@ -246,7 +246,7 @@ c3 = c
> <title>Using HTTP entities</title>
> <para>
> Since an entity can represent both binary and character content, it has support
> - for character encodings (to support the latter, ie. character content).
> + for character encodings (to support the latter, i.e. character content).
> </para>
> <para>
> The entity is created when executing a request with enclosed content or when the
> @@ -261,10 +261,10 @@ c3 = c
> return once all content has been written to the given stream.
> </para>
> <para>
> - The <classname>EntityUtils</classname> class exposes several static methods to
> - more easily read the content or information from an entity. Instead of reading
> - the <classname>java.io.InputStream</classname> directly, one can retrieve the whole
> - content body in a string / byte array by using the methods from this class.
> + The <classname>EntityUtils</classname> class exposes several static methods to read
> + more easily the content or information from an entity. Instead of reading
Again, the original read better.
Would be better as:
the content or information from an entity more easily
> + the <classname>java.io.InputStream</classname> directly, one can retrieve the complete
> + content body in a string or byte array by using the methods from this class.
> </para>
> <para>
> When the entity has been received with an incoming message, the methods
> @@ -338,8 +338,7 @@ if (entity != null) {
> <section>
> <title>Creating entities</title>
> <para>
> - There are a few ways to create entities. The following implementations are provided
> - by HttpCore:
> + There are a few ways to create entities. HttpCore provides the following implementations:
> </para>
> <itemizedlist>
> <listitem>
> @@ -402,11 +401,11 @@ if (entity != null) {
> <section id="basic-entity">
> <title><classname>BasicHttpEntity</classname></title>
> <para>
> - This is exactly as the name implies, a basic entity that represents an underlying
> - stream. This is generally used for the entities received from HTTP messages.
> + Exactly as the name implies, this basic entity represents an underlying stream.
> + In general, use this class for entities received from HTTP messages.
> </para>
> <para>
> - This entity has an empty constructor. After construction it represents no content,
> + This entity has an empty constructor. After construction, it represents no content,
> and has a negative content length.
> </para>
> <para>
> @@ -424,9 +423,9 @@ myEntity.setContentLength(340); // sets
> <section id="byte-array-entity">
> <title><classname>ByteArrayEntity</classname></title>
> <para>
> - <classname>ByteArrayEntity</classname> is a self contained, repeatable entity
> - that obtains its content from a given byte array. This byte array is supplied
> - to the constructor.
> + <classname>ByteArrayEntity</classname> is a self-contained, repeatable entity
> + that obtains its content from a given byte array. Supply the byte array to the
> + constructor.
> </para>
> <programlisting><![CDATA[
> ByteArrayEntity myEntity = new ByteArrayEntity(new byte[] {1,2,3},
> @@ -436,7 +435,7 @@ ByteArrayEntity myEntity = new ByteArray
> <section id="string-entity">
> <title><classname>StringEntity</classname></title>
> <para>
> - <classname>StringEntity</classname> is a self contained, repeatable entity that
> + <classname>StringEntity</classname> is a self-contained, repeatable entity that
> obtains its content from a <classname>java.lang.String</classname> object. It has
> three constructors, one simply constructs with a given <classname>java.lang.String
> </classname> object; the second also takes a character encoding for the data in the
> @@ -466,13 +465,13 @@ HttpEntity myEntity3 = new StringEntity(
> <title><classname>InputStreamEntity</classname></title>
> <para>
> <classname>InputStreamEntity</classname> is a streamed, non-repeatable entity that
> - obtains its content from an input stream. It is constructed by supplying the input
> - stream and the content length. The content length is used to limit the amount of
> - data read from the <classname>java.io.InputStream</classname>. If the length matches
> + obtains its content from an input stream. Construct it by supplying the input
> + stream and the content length. Use the content length to limit the amount of data
> + read from the <classname>java.io.InputStream</classname>. If the length matches
> the content length available on the input stream, then all data will be sent.
> - Alternatively a negative content length will read all data from the input stream,
> - which is the same as supplying the exact content length, so the length is most
> - often used to limit the length.
> + Alternatively, a negative content length will read all data from the input stream,
> + which is the same as supplying the exact content length, so use the length to limit
> + the amount of data to read.
> </para>
> <programlisting><![CDATA[
> InputStream instream = getSomeInputStream();
> @@ -482,9 +481,9 @@ InputStreamEntity myEntity = new InputSt
> <section id="file-entity">
> <title><classname>FileEntity</classname></title>
> <para>
> - <classname>FileEntity</classname> is a self contained, repeatable entity that
> - obtains its content from a file. Since this is mostly used to stream large files
> - of different types, one needs to supply the content type of the file, for
> + <classname>FileEntity</classname> is a self-contained, repeatable entity that
> + obtains its content from a file. Use this mostly to stream large files of different
> + types, where you need to supply the content type of the file, for
> instance, sending a zip file would require the content type <literal>
> application/zip</literal>, for XML <literal>application/xml</literal>.
> </para>
> @@ -506,13 +505,13 @@ HttpEntity entity = new FileEntity(stati
> <title><classname>BufferedHttpEntity</classname></title>
> <para>
> <classname>BufferedHttpEntity</classname> is a subclass of <classname>
> - HttpEntityWrapper</classname>. It is constructed by supplying another entity. It
> + HttpEntityWrapper</classname>. Construct it by supplying another entity. It
> reads the content from the supplied entity, and buffers it in memory.
> </para>
> <para>
> This makes it possible to make a repeatable entity, from a non-repeatable entity.
> - If the supplied entity is already repeatable, calls are simply passed through to the
> - underlying entity.
> + If the supplied entity is already repeatable, it simply passes calls through to
> + the underlying entity.
> </para>
> <programlisting><![CDATA[
> myNonRepeatableEntity.setContent(someInputStream);
> @@ -533,8 +532,8 @@ BufferedHttpEntity myBufferedEntity = ne
> addresses.
> </para>
> <para>
> - It is important to bear in mind that HTTP connections are not thread-safe. It is strongly
> - recommended to limit all interactions with HTTP connection objects to one thread. The only
> + It is important to bear in mind that HTTP connections are not thread-safe. We strongly
> + recommend limiting all interactions with HTTP connection objects to one thread. The only
> method of <interfacename>HttpConnection</interfacename> interface and its sub-interfaces
> which is safe to invoke from another thread is <methodname> HttpConnection#shutdown()
> </methodname>.
> @@ -562,14 +561,14 @@ System.out.println(metrics.getSentBytesC
> <para>
> HTTP connection interfaces, both client and server, send and receive messages in two
> stages. The message head is transmitted first. Depending on properties of the message
> - head it may be followed by a message body. Please note it is very important to always
> + head, a message body may follow it. Please note it is very important to always
> close the underlying content stream in order to signal that the processing of
> the message is complete. HTTP entities that stream out their content directly from the
> - input stream of the underlying connection must ensure the content of the message body
> - is fully consumed for that connection to be potentially re-usable.
> + input stream of the underlying connection must ensure they fully consume the content
> + of the message body for that connection to be potentially re-usable.
> </para>
> <para>
> - Over-simplified process of client side request execution may look like this:
> + Over-simplified process of request execution on the client side may look like this:
> </para>
> <programlisting><![CDATA[
> Socket socket = <...>
> @@ -589,7 +588,7 @@ if (entity != null) {
> }
> ]]></programlisting>
> <para>
> - Over-simplified process of server side request handling may look like this:
> + Over-simplified process of request handling on the server side may look like this:
> </para>
> <programlisting><![CDATA[
> Socket socket = <...>
> @@ -630,10 +629,10 @@ conn.sendResponseEntity(response);
> incoming data. They merely inject an appropriate content codec based on the properties
> of the incoming message. The content can be retrieved by reading from the content input
> stream of the enclosed entity using <methodname>HttpEntity#getContent()</methodname>.
> - The incoming data will be decoded automatically, and completely transparently to the data
> + The incoming data will be decoded automatically and completely transparently to the data
> consumer. Likewise, HTTP connections rely on <methodname>
> HttpEntity#writeTo(OutputStream)</methodname> method to generate the content of an
> - outgoing message. If an outgoing messages encloses an entity, the content will be
> + outgoing message. If an outgoing message encloses an entity, the content will be
> encoded automatically based on the properties of the message.
> </para>
> </section>
> @@ -660,7 +659,7 @@ conn.sendResponseEntity(response);
> <para>
> The end of the content entity is demarcated by closing the underlying
> connection (end of stream condition). For obvious reasons the identity encoding
> - can only be used on the server side. Max entity length: unlimited.
> + can only be used on the server side. Maximum entity length: unlimited.
> </para>
> </formalpara>
> </listitem>
> @@ -668,7 +667,7 @@ conn.sendResponseEntity(response);
> <formalpara>
> <title>Chunk coding:</title>
> <para>
> - The content is sent in small chunks. Max entity length: unlimited.
> + The content is sent in small chunks. Maximum entity length: unlimited.
> </para>
> </formalpara>
> </listitem>
>
> Modified: httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml
> URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml?rev=1504858&r1=1504857&r2=1504858&view=diff
> ==============================================================================
> --- httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml (original)
> +++ httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml Fri Jul 19 12:34:14 2013
> @@ -1126,7 +1126,7 @@ if (encoder instanceof FileContentEncode
> <section id="bytearray-n-entity">
> <title><classname>NByteArrayEntity</classname></title>
> <para>
> - This is a simple self contained repeatable entity, which receives its content from
> + This is a simple self-contained repeatable entity, which receives its content from
> a given byte array. This byte array is supplied to the constructor.
> </para>
> <programlisting><![CDATA[
> @@ -1136,7 +1136,7 @@ NByteArrayEntity entity = new NByteArray
> <section id="string-n-entity">
> <title><classname>NStringEntity</classname></title>
> <para>
> - It's is a simple, self contained, repeatable entity that retrieves its data from a
> + It's is a simple, self-contained, repeatable entity that retrieves its data from a
It's is ?? => It is
> <classname>java.lang.String</classname> object. It has 2 constructors, one simply
> constructs with a given string where the other also takes a character encoding for
> the data in the <classname>java.lang.String</classname>.
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org