activemq-artemis/docs/user-manual/zh/large-messages.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
<!--                                                                               -->
<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
<!--                                                                               -->
<!-- An explanation of CC-BY-SA is available at                                    -->
<!--                                                                               -->
<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
<!--                                                                               -->
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
<!-- of it, you must provide the URL for the original version.                     -->
<!--                                                                               -->
<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
<!-- permitted by applicable law.                                                  -->
<!-- ============================================================================= -->
<chapter id="large-messages">
    <title>大消息</title>
    <para>ActiveMQ支持超大消息的发送和接收。消息的大小不受客户端或服务器端的内存限制。它只受限于你的磁盘空间的大小。
        在我们作过的测试中，消息最大可达8GiB，而客户端和服务器端的内存只有50MiB！</para>
    <para>要发送一个大消息，用户需要为大消息提供一个<literal>InputStream</literal>，当大消息被发送时，
        ActiveMQ从该<literal>InputStream</literal>读取消息。例如，要将一个磁盘中的大文件以消息形式发送，可以
        使用<literal>FileInputStream</literal>。</para>
    <para>数据从<literal>InputStream</literal>读出并分解为一个个数据片段向服务器以流的形式发送。服务器在收到
        这些片段后将它们保存到磁盘上。当服务器准备向接收者传递消息时，它将这些片段读回，同样以片段流的形式向接收者
        一端发送。当接收者开始接收时，最初收到的只是一个空的消息体。它需要为其设置一个<literal>OutputStream</literal>
        以便向大消息保存到磁盘上或其它地方。从发送到接收整个过程中不需要整个消息都在内存中。</para>
    <section id="large.message.configuring">
        <title>服务器端的配置</title>
        <para>大消息在服务器端是直接保存在磁盘目录中。这一目录可以在ActiveMQ的配置文件中定义。</para>
        <para>这个参数的名字是<literal>large-messages-directory</literal>：</para>
        <programlisting>&lt;configuration xmlns="urn:activemq"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd">

...

&lt;large-messages-directory>/data/large-messages&lt;/large-messages-directory>

...

&lt;/configuration</programlisting>
        <para>默认的大消息保存目录是<literal>data/largemessages</literal>。</para>
        <para>为了提高性能，我们建议将大消息的保存目录定义到与消息日志（journal）或分页转存目录分开的物理卷上。</para>
    </section>
    <section>
        <title>设定限制</title>
        <para>参数<literal>min-large-message-size</literal>定义了大消息的最小值。
              任何消息的大小如果超过了该值就被视为大消息。一旦成为大消息，它将被分成小的
              片段来传送。</para>
        <para>默认值是100KiB.</para>
        <section id="large-messages.core.config">
            <title>使用核心的API</title>
            <para>如果使用ActiveMQ的核心，<literal>ClientSessionFactory.setMinLargeMessageSize</literal>方法
                  可以设置大消息的最小值。</para>
            <programlisting>ClientSessionFactory factory = 
            ActiveMQClient.createClientSessionFactory(new 
            TransportConfiguration(NettyConnectorFactory.class.getName()), null);
factory.setMinLargeMessageSize(25 * 1024);</programlisting>
            <para><xref linkend="configuring-transports.client.side"/>对于如何实例化一个会话工厂（session factory）
                给出了进一步的说明。</para>
        </section>
        <section>
            <title>使用JMS</title>
            <para>如果连接工厂是通过JNDI方式获得的，则需要在<literal>activemq-jms.xml</literal>文件中定义：</para>
            <programlisting>...
&lt;connection-factory name="ConnectionFactory">
&lt;connectors>
   &lt;connector-ref connector-name="netty"/>
&lt;/connectors>
&lt;entries>
   &lt;entry name="ConnectionFactory"/>
   &lt;entry name="XAConnectionFactory"/>
&lt;/entries>
                
&lt;min-large-message-size>250000&lt;/min-large-message-size>
&lt;/connection-factory>
...</programlisting>
            <para>如果是直接实例化连接工厂，则使用<literal
                    >ActiveMQConnectionFactory.setMinLargeMessageSize</literal>方法来定义。</para>
        </section>
    </section>
    <section>
        <title>大消息与流（stream）</title>
        <para>在ActiveMQ中可以定义大消息所使用的输入和输出流（<literal>java.lang.io</literal>)。</para>
        <para>ActiveMQ将使用定义的流来发送（输入流）和接收（输出流）大消息。</para>
        <para>在使用输出流接收大消息时，有两种选择：你可以用<literal>ClientMessage.saveOutputStream</literal>方法
            以阻塞的方式保存大消息；或者你可以使用<literal>ClientMessage.setOutputstream</literal>方法
            以异步方法保存大消息。在采用后一种方法时，必须保证接收者（consumer）在大消息的接收过程中保持
            有效状态。</para>
        <para>根据需要选择所适合的流。最常见的情况是将磁盘文件以消息方式发送，也有可能是JDBC的Blob数据，
            或者是一个<literal>SocketInputStream</literal>，或是来自<literal>HTTPRequests</literal>
            的数据等等。只要是实现了<literal>java.io.InputStream</literal>和
            <literal>java.io.OutputStream</literal>的数据源都可以作为大消息传送。</para>
        <section>
            <title>核心API中流的使用</title>
            <para>下表列出了<literal>ClientMessage</literal>上可以使用的方法。
                  通过相应的对象属性也可以在JMS中应用。</para>
            <table frame="topbot" id="large-messages.ClientMessageAPI">
                <title>org.apache.activemq.api.core.client.ClientMessage API</title>
                <tgroup cols="3">
                    <colspec colname="Name" colnum="1"/>
                    <colspec colname="Descr" colnum="2"/>
                    <colspec colname="JMS" colnum="3"/>
                    <thead>
                        <row>
                            <entry>名称</entry>
                            <entry>说明</entry>
                            <entry>JMS相对应的属性</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>setBodyInputStream(InputStream)</entry>
                            <entry>设定大消息发送时所使用的输入流。</entry>
                            <entry>JMS_HQ_InputStream</entry>
                        </row>
                        <row>
                            <entry>setOutputStream(OutputStream)</entry>
                            <entry>设定异步接收大消息所使用的输出流。</entry>
                            <entry>JMS_HQ_OutputStream</entry>
                        </row>
                        <row>
                            <entry>saveOutputStream(OutputStream)</entry>
                            <entry>设定保存大消息所使用的输出流。这个方法将会阻塞直到大消息全部
                                   保存完毕才返回。</entry>
                            <entry>JMS_HQ_SaveStream</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
            <para>下面代码中设定了接收核心消息所用的输出流： </para>
            <programlisting>
...
ClientMessage msg = consumer.receive(...);


// This will block here until the stream was transferred
msg.saveOutputStream(someOutputStream); 

ClientMessage msg2 = consumer.receive(...);

// This will not wait the transfer to finish
msg.setOutputStream(someOtherOutputStream); 
...
                
            </programlisting>
            <para> 设定发送核心消息所用的输入流： </para>
            <programlisting>
...
ClientMessage msg = session.createMessage();
msg.setInputStream(dataInputStream);
...
            </programlisting>
        </section>
        <section id="large-messages.streaming.over.jms">
            <title>在JMS中使用流</title>
            <para>使用JMS时，ActiveMQ根据定义的属性值调用对应的核心接口（参见 <xref
                    linkend="large-messages.ClientMessageAPI"/>）来使用流。你只需要用
                  <literal>Message.setObjectProperty</literal>方法设置适当的输入／输出流即可。</para>
            <para>输入流<literal>InputStream</literal>可以通过JMS属性JMS_HQ_InputStream来定义：</para>
            <programlisting>
BytesMessage message = session.createBytesMessage();

FileInputStream fileInputStream = new FileInputStream(fileInput);

BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream);

message.setObjectProperty("JMS_HQ_InputStream", bufferedInput);

someProducer.send(message);</programlisting>
            <para>输出流<literal>OutputStream</literal>可以通过JMS属性JMS_HQ_SaveStream来定义。下面是阻塞式方法：</para>
            <programlisting>
BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000);
                
File outputFile = new File("huge_message_received.dat");
                
FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
                
BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
                
// This will block until the entire content is saved on disk
messageReceived.setObjectProperty("JMS_HQ_SaveStream", bufferedOutput);
            </programlisting>
            <para>也可以使用JMS_HQ_OutputStream属性以非阻塞式（异步）方法来定义输出流<literal>OutputStream</literal>：</para>
            <programlisting>
// This won't wait the stream to finish. You need to keep the consumer active.
messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);
            </programlisting>
            <note>
                <para>使用JMS时，只有<literal>StreamMessage</literal>和<literal>BytesMessage</literal>才支持大消息的传送。</para>
            </note>
        </section>
    </section>
    <section>
        <title>不使用流的方式</title>
        <para>如果不想使用输入流与输出流来传送大消息，可以用另外一种方法。</para>
        <para>使用核心接口时，可以直接从消息中读字节。</para>
        <programlisting>ClientMessage msg = consumer.receive();
         
byte[] bytes = new byte[1024];
for (int i = 0 ;  i &lt; msg.getBodySize(); i += bytes.length)
{
   msg.getBody().readBytes(bytes);
   // Whatever you want to do with the bytes
}</programlisting>
        <para>使用JMS接口时，<literal>BytesMessage</literal>和<literal>StreamMessage</literal>
            本身提供这样的支持。</para>
        <programlisting>BytesMessage rm = (BytesMessage)cons.receive(10000);

byte data[] = new byte[1024];

for (int i = 0; i &lt; rm.getBodyLength(); i += 1024)
{
   int numberOfBytes = rm.readBytes(data);
   // Do whatever you want with the data
}        </programlisting>
    </section>
    <section id="large-messages.cache.client">
        <title>在客户端缓存大消息</title>
        <para>大消息通过流在服务器和客户端之间传输。每个大消息被分割成很多小的数据包传递。因此大消息只能被
            读取一次。这样一个大消息在收到后就不能再被再次传送。例如，JMS Bridge在发送大消息时如果在出现故障，
            将不能把它重新发送。</para>
        <para>要解决这个问题，可以在连接工厂上设置<literal>cache-large-message-client</literal>属性。
            这个属性可以使客户端接收者创建一个临时的文件保存收到的大消息，这样就可以在需要时能够重新发送该消息。</para>
        <note>如果JMS Bridge用来发送大消息，可以在它使用的连接工厂上使用它。</note>
    </section>
    <section id="large-messages.example">
        <title>大消息例子</title>
        <para>我们在<xref linkend="examples.large-message"/>提供了一个在JMS中配置和使用大消息的例子。</para>
    </section>
</chapter>