blob-messages.xml

<div class="wiki-content maincontent"><h2 id="BlobMessages-BlobMessages">Blob Messages</h2>

<p>A common requirement these days is to send around massive files for processing by consumers. Folks want to take advantage of the message broker's features such as reliable, transactional load balancing of queues with smart routing but still manage to deal with huge logical files.</p>

<p>So we are introducing a BlobMessage API which allows massive BLOBs (Binary Large OBjects) to be sent around in some out-of-band transport mechanism. Possible out-of-band mechanisms could be HTTP or FTP or SCP or some other point-to-point protocol.</p>

<p>There are now new createBlobMessage() methods on the ActiveMQSession that you can use for sending BLOBs. </p>

<h3 id="BlobMessages-SendingBlobMessages">Sending BlobMessages</h3>

<p>You can send a URL around the JMS network, such as a file or URL which exists on some shared file system or web server using the following code</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[
BlobMessage message = session.createBlobMessage(new URL(&quot;http://some.shared.site.com&quot;);
producer.send(message);
]]></script>
</div></div>

<p>Or if you are creating files or streams dynamically on the client you may want to upload the file to the broker or some server (Jetty, FTP, WebDav or whatever). In which case you'd use one of the following methods</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[
// lets use a local file
BlobMessage message = session.createBlobMessage(new File(&quot;/foo/bar&quot;);
producer.send(message);
]]></script>
</div></div>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[
// lets use a stream
InputStream in = ...;
BlobMessage message = session.createBlobMessage(in);
producer.send(message);
]]></script>
</div></div>

<h3 id="BlobMessages-ReceivingBlobMessages">Receiving BlobMessages</h3>

<p>A <a shape="rect" class="external-link" href="http://activemq.apache.org/maven/activemq-core/apidocs/org/apache/activemq/BlobMessage.html">BlobMessage</a> is a regular JMS message so it can be received just like any other message...</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[
public class MyListener implements MessageListener {
  public void onMessage(Message message) {
    if (message instanceof BlobMessage) {
      BlobMessage blobMessage = (BlobMessage) message;
      InputStream in = blobMessage.getInputStream();

      // process the stream...
    }
  }
}
]]></script>
</div></div>


<h3 id="BlobMessages-ConfiguringtheBLOBTransferPolicy">Configuring the BLOB Transfer Policy</h3>

<p>You can explicitly configure the BlobTransferPolicy on an ActiveMQConnectionFactory, ActiveMQConnection or ActiveMQSession. Typically its done on the factory either via Java code or Spring.</p>

<p>You can use the <a shape="rect" href="connection-configuration-uri.xml">Connection Configuration URI</a> to configure these things via a URI.</p>

<p>For example you can connect to a broker also specifying the uploadUrl to use via</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[
tcp://localhost:61616?jms.blobTransferPolicy.uploadUrl=http://foo.com
]]></script>
</div></div>
</div>