[jboss-cvs] JBoss Messaging SVN: r6975 - trunk/docs/user-manual/en.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri May 22 02:03:14 EDT 2009
Author: ataylor
Date: 2009-05-22 02:03:13 -0400 (Fri, 22 May 2009)
New Revision: 6975
Modified:
trunk/docs/user-manual/en/large-messages.xml
Log:
more proof reading updates
Modified: trunk/docs/user-manual/en/large-messages.xml
===================================================================
--- trunk/docs/user-manual/en/large-messages.xml 2009-05-22 05:41:22 UTC (rev 6974)
+++ trunk/docs/user-manual/en/large-messages.xml 2009-05-22 06:03:13 UTC (rev 6975)
@@ -1,12 +1,15 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="large-messages">
<title>Large Messages</title>
- <para>JBoss Messaging supports sending and receiving of messages larger than it would fit on
- client's or server's memory. The only limit is the disk space.</para>
- <para>Large messages are broken into smaller pieces and sent through the transport and saved as
- files on the server. Flow control (<xref linkend="flow-control"/>) is used on the
- transmission to prevent overusing the channel or running out of memory during the
- transmission process, so it is possible to send and receive very large messages. </para>
+ <para>JBoss Messaging supports sending and receiving of arbitrarily large messages even when
+ larger than would fit in the client's or server's memory. The only limit is the disk
+ space.</para>
+ <para>Large messages are fragmented into smaller pieces and sent to the server individually. The
+ server persists these parts to disk and delivers them to a consumer in the same fashion. The
+ consumer then reconstructs the original message before final delivery. Flow control (<xref
+ linkend="flow-control"/>) is used on the transmission to prevent overusing the channel
+ or running out of memory during the transmission process, so it is possible to send and
+ receive very large messages without effecting any other messages being delivered. </para>
<para>For example, it is possible to send an 8GiB message even if you only had 50MiB of RAM on
either client and server. </para>
<section id="large.message.configuring">
@@ -62,38 +65,33 @@
</connection-factory>
...</programlisting>
<para>If the connection factory is being instantiate directly, the minimal large message
- size is specified by <literal
- >JBossConnectionFactory.setMinLargeMessageSize</literal>.</para>
+ size is specified by
+ <literal>JBossConnectionFactory.setMinLargeMessageSize</literal>.</para>
</section>
</section>
<section>
<title>Streaming large messages</title>
<para>JBoss Messaging supports setting the body of messages using input and output streams
(<literal>java.lang.io</literal>)</para>
- <para>This is a very efficient way of sending and receiving large messages, the stream will
- be used directly by JBoss Messaging during the transmission being a very fast
- process.</para>
- <para>For messages being sent it is possible to set the input stream and as the message is
- being transmitted the input stream is read.</para>
- <para>For messages being received it is possible to set the output stream and as the server
- sends more packets the output stream will receive the body of the message. </para>
- <para>You may choose to block while the output stream is recovered using the method <literal
- >ClientMessage.saveOutputStream</literal> or do it asynchronously using the method
- <literal>ClientMessage.setOutputstream</literal>. If you choose the non blocking
- method the caller of the method won't wait the transmission to finish after <literal
- >setOutputStream</literal> is called so you need to keep the message consumer
- active.</para>
+ <para>These streams are then used directly for sending (input streams) and receiving (output
+ streams) messages.</para>
+ <para>When receiving messages there are 2 ways to deal with the output stream you may choose
+ to block while the output stream is recovered using the method
+ <literal>ClientMessage.saveOutputStream</literal> or alternatively using the method
+ <literal>ClientMessage.setOutputstream</literal> which will asynchronously write the
+ message to the stream. If you choose the latter the consumer must be kept alive until
+ the message has been fully received.</para>
<para>You can use any kind of stream you like. The most common use case is to send files
- stored in your disk, but you could also send things like JDBC Blobs, <literal
- >SocketInputStream</literal>, things you recovered from <literal
- >HTTPRequest</literal> etc. Anything as long as it implements <literal
- >java.io.InputStream</literal> for sending messages or <literal
- >java.io.OutputStream</literal> for receiving them.</para>
+ stored in your disk, but you could also send things like JDBC Blobs,
+ <literal>SocketInputStream</literal>, things you recovered from
+ <literal>HTTPRequests</literal> etc. Anything as long as it implements
+ <literal>java.io.InputStream</literal> for sending messages or
+ <literal>java.io.OutputStream</literal> for receiving them.</para>
<section>
<title>Streaming over Core API</title>
- <para>The following table shows a list of methods available at <literal
- >ClientMessage</literal> which are also available through JMS by the use of
- object properties.</para>
+ <para>The following table shows a list of methods available at
+ <literal>ClientMessage</literal> which are also available through JMS by the use
+ of object properties.</para>
<table frame="topbot" id="large-messages.ClientMessageAPI">
<title>org.jboss.messaging.core.client.ClientMessage API</title>
<tgroup cols="3">
@@ -122,9 +120,10 @@
</row>
<row>
<entry>saveOutputStream(OutputStream)</entry>
- <entry>Save the content of the message to the <literal
- >OutputStream</literal>. It will block until the entire content
- is transferred to the <literal>OutputStream</literal>.</entry>
+ <entry>Save the content of the message to the
+ <literal>OutputStream</literal>. It will block until the entire
+ content is transferred to the
+ <literal>OutputStream</literal>.</entry>
<entry>JMS_JBM_SaveStream</entry>
</row>
</tbody>
@@ -156,9 +155,10 @@
</section>
<section id="large-messages.streaming.over.jms">
<title>Streaming over JMS</title>
- <para>When using JMS JBoss Messaging maps the streaming methods as object properties as
- seen on <xref linkend="large-messages.ClientMessageAPI"/>. You can use the method
- <literal>Message.setObjectProperty</literal> to set the streaming.</para>
+ <para>When using JMS, JBoss Messaging maps the streaming methods on the core API (see
+ <xref linkend="large-messages.ClientMessageAPI"/>) by setting object properties
+ . You can use the method <literal>Message.setObjectProperty</literal> to set the
+ input and output streams.</para>
<para>The <literal>InputStream</literal> can be defined through the JMS Object Property
JMS_JBM_InputStream on messages being sent:</para>
<programlisting>
@@ -192,18 +192,16 @@
messageReceived.setObjectProperty("JMS_JBM_InputStream", bufferedOutput);
</programlisting>
<warning>
- <para>When using JMS, Streaming Large Message is only supported on <literal
- >StreamMessage</literal> and <literal>BytesMessage</literal> because of the
- extra information required to process other types of messages</para>
+ <para>When using JMS, Streaming Large Messages is only supported on
+ <literal>StreamMessage</literal> and <literal>BytesMessage</literal>.</para>
</warning>
</section>
</section>
<section>
- <title>Not using streaming</title>
- <para>You may choose to not use the <literal>InputStream</literal> or <literal
- >OutputStream</literal> capability over JMS or core API even knowing streaming would
- be the most performatic approach. </para>
- <para>You could still access the data transparently both using the core API or JMS.</para>
+ <title>Streaming Alternative</title>
+ <para>If you choose not to use the <literal>InputStream</literal> or
+ <literal>OutputStream</literal> capability of JBoss Messaging You could still access
+ the data directly in an alternative fashion.</para>
<para>On the Core API just get the bytes of the body as you normally would.</para>
<programlisting>ClientMessage msg = consumer.receive();
@@ -239,10 +237,10 @@
</section>
<section>
<title>Resending a large message</title>
- <para>As large messages are broken into smaller packets, we send them as a streaming from
- server to client. Those message bodies are not kept in memory so once they are read
- their body is gone therefore it is not possible to resend a large message.</para>
- <para>As a result resending large messages after reading them will not work as seen on this
+ <para>As large messages are broken into smaller packets the fragmented packets are delivered
+ individually from server to client. The message fragments are not kept in memory so once
+ they are delivered it is not possible to resend them.</para>
+ <para>As a result resending a large messages after consumption will not work as seen on this
example:</para>
<programlisting>BytesMessage bm = (BytesMessage)cons.receive(1000);
@@ -253,8 +251,8 @@
</section>
<section id="large-messages.example">
<title>Large message example</title>
- <para>The <ulink url="../../../../examples/jms/large-message/readme.html"><literal
- >large-message</literal> Example</ulink> shows how large message is configured
- and used with JMS.</para>
+ <para>The <ulink url="../../../../examples/jms/large-message/readme.html"
+ ><literal>large-message</literal> Example</ulink> shows how large message is
+ configured and used with JMS.</para>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list