Large messages are stored on a disk directory on the server side, as configured on the main configuration file.

The configuration property large-messages-directory specifies where large messages are stored.

<configuration xmlns="urn:hornetq"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="urn:hornetq /schema/hornetq-configuration.xsd">

...

<large-message-directory>/data/large-messages</large-message-directory>

...

</configuration

By default the large message directory is data/largemessages

For the best performance we recommend large messages directory is stored on a different physical volume to the message journal or paging directory.

Any message larger than a certain size is considered a large message. Large messages will be split up and sent in fragments. This is determined by the parameter min-large-message-size

The default value is 100KiB.

ClientSessionFactory factory = 
            HornetQClient.createClientSessionFactory(new 
            TransportConfiguration(NettyConnectorFactory.class.getName()), null);
factory.setMinLargeMessageSize(25 * 1024);

...
<connection-factory name="ConnectionFactory">
<connectors>
   <connector-ref connector-name="netty"/>
</connectors>
<entries>
   <entry name="ConnectionFactory"/>
   <entry name="XAConnectionFactory"/>
</entries>
                
<min-large-message-size>250000</min-large-message-size>
</connection-factory>
...

HornetQ supports setting the body of messages using input and output streams (java.lang.io)

These streams are then used directly for sending (input streams) and receiving (output streams) messages.

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 ClientMessage.saveOutputStream or alternatively using the method ClientMessage.setOutputstream 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.

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, SocketInputStream, things you recovered from HTTPRequests etc. Anything as long as it implements java.io.InputStream for sending messages or java.io.OutputStream for receiving them.

...
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); 
...
                
            

...
ClientMessage msg = session.createMessage();
msg.setInputStream(dataInputStream);
...
            

BytesMessage message = session.createBytesMessage();

FileInputStream fileInputStream = new FileInputStream(fileInput);

BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream);

message.setObjectProperty("JMS_HQ_InputStream", bufferedInput);

someProducer.send(message);

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);
            

// This won't wait the stream to finish. You need to keep the consumer active.
messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);
            

If you choose not to use the InputStream or OutputStream capability of HornetQ You could still access the data directly in an alternative fashion.

On the Core API just get the bytes of the body as you normally would.

ClientMessage msg = consumer.receive();
         
byte[] bytes = new byte[1024];
for (int i = 0 ;  i < msg.getBodySize(); i += bytes.length)
{
   msg.getBody().readBytes(bytes);
   // Whatever you want to do with the bytes
}

If using JMS API, BytesMessage and StreamMessage also supports it transparently.

BytesMessage rm = (BytesMessage)cons.receive(10000);

byte data[] = new byte[1024];

for (int i = 0; i < rm.getBodyLength(); i += 1024)
{
   int numberOfBytes = rm.readBytes(data);
   // Do whatever you want with the data
}        

Large messages are transferred by streaming from server to client. The message is broken into smaller packets and as the message is read more packets will be received. Because of that the body of the large message can be read only once, and by consequence a received message can be sent to another producer only once. The JMS Bridge for instance won't be able to resend a large message in case of failure

To solve this problem, you can enable the property cache-large-message-client on the connection factory. If you enable this property the client consumer will create a temporary file to hold the large message content, so it would be possible to resend large messages.

Please see Section 11.1.22, “Large Message” for an example which shows how large message is configured and used with JMS.