You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by gg...@apache.org on 2013/07/19 14:34:14 UTC
svn commit: r1504858 - in /httpcomponents/httpcore/trunk/src/docbkx:
fundamentals.xml nio-ext.xml
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
+ 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
<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>.
Re: svn commit: r1504858 - in /httpcomponents/httpcore/trunk/src/docbkx:
fundamentals.xml nio-ext.xml
Posted by sebb <se...@gmail.com>.
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