Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 8. Handling large messages

You can configure the broker to store messages as files whenever they exceed a specified minimum size. The broker does not hold these large messages in memory to avoid the possibility that a message exceeds the broker’s internal buffer size and causes unexpected errors.

You can specify a directory on disk or a database table in which the broker stores large message files.

When the broker stores a message as a large message, the queue retains a reference to the file in the large messages directory or database table.

Large message handling is available for the Core Protocol, AMQP, OpenWire and STOMP protocols.

For the Core Protocol and OpenWire protocols, clients specify the minimum large message size in their connection configurations. For the AMQP and STOMP protocols, you specify the minimum large message size in the acceptor defined for each protocol in the broker configuration.

Note

It is recommended that you do not use different protocols for producing and consuming large messages. To do this, the broker might need to perform several conversions of the message. For example, if you want to send a message by using the AMQP protocol and receive it by using OpenWire. In this situation, the broker must first read the entire body of the large message and convert it to use the Core protocol. Then, the broker must perform another conversion, this time to the OpenWire protocol. Message conversions such as these place significant processing demands on the broker.

The minimum large message size that you specify for any of the preceding protocols is affected by system resources such as the amount of disk space available and the size of the messages. It is recommended that you run performance tests by using several values to determine an appropriate size.

The procedures in this section show how to:

  • Configure the broker to store large messages
  • Configure acceptors for the AMQP and STOMP protocols for large message handling

This section also links to additional resources about configuring AMQ Core Protocol and AMQ OpenWire JMS clients to work with large messages.

You can change the default location in which the broker stores large message files on the filesystem or in a database table.

Procedure

  1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

  2. Specify where you want the broker to store large message files.

    1. If you are storing large messages on disk, add the large-messages-directory parameter within the core element and specify a file system location. For example: 

      <configuration>
  <core>
    ...
    <large-messages-directory>/path/to/my-large-messages-directory</large-messages-directory>
    ...
  </core>
</configuration>
      Copy to Clipboard Toggle word wrap
      Note

      If you do not explicitly specify a value for large-messages-directory, the broker uses a default value of <broker_instance_dir>/data/largemessages

    2. If you are storing large messages in a database table, add the large-message-table parameter to the database-store element and specify a value. For example: 

      <store>
  <database-store>
    ...
    <large-message-table>MY_TABLE</large-message-table>
    ...
  </database-store>
</store>
      Copy to Clipboard Toggle word wrap
      Note

      If you do not explicitly specify a value for large-message-table, the broker uses a default value of LARGE_MESSAGE_TABLE.

Additional resources

For messages originating from AMQP clients, you must specify the size threshold for large messages in the AMQP acceptor configuration. Any message exceeding this size threshold is classified as a large message.

Procedure

  1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

    The default AMQP acceptor in the broker configuration file looks as follows: 

    <acceptors>
    ...
    <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor>
    ...
</acceptors>
    Copy to Clipboard Toggle word wrap

  2. In the default AMQP acceptor (or another AMQP acceptor that you have configured), add the amqpMinLargeMessageSize property and specify a value. For example: 

    <acceptors>
    ...
    <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300;amqpMinLargeMessageSize=204800</acceptor>
    ...
</acceptors>
    Copy to Clipboard Toggle word wrap

    In the preceding example, the broker is configured to accept AMQP messages on port 5672. Based on the value of amqpMinLargeMessageSize, if the acceptor receives an AMQP message with a body larger than or equal to 204800 bytes (that is, 200 kilobytes), the broker stores the message as a large message. If you do not explicitly specify a value for this property, the broker uses a default value of 102400 (that is, 100 kilobytes).

    Note
    • If you set amqpMinLargeMessageSize to -1, large message handling for AMQP messages is disabled.
    • If the broker receives a persistent AMQP message that does not exceed the value of amqpMinLargeMessageSize, but which does exceed the size of the messaging journal buffer (specified using the journal-buffer-size configuration parameter), the broker converts the message to a large Core Protocol message, before storing it in the journal.

For messages originating from STOMP clients, you must specify the size threshold for large messages in the STOMP acceptor configuration. Any message exceeding this size threshold is classified as a large message.

Procedure

  1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

    The default AMQP acceptor in the broker configuration file looks as follows: 

    <acceptors>
    ...
    <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor>
    ...
</acceptors>
    Copy to Clipboard Toggle word wrap

  2. In the default STOMP acceptor (or another STOMP acceptor that you have configured), add the stompMinLargeMessageSize property and specify a value. For example: 

    <acceptors>
    ...
    <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true;stompMinLargeMessageSize=204800</acceptor>
    ...
</acceptors>
    Copy to Clipboard Toggle word wrap

    In the preceding example, the broker is configured to accept STOMP messages on port 61613. Based on the value of stompMinLargeMessageSize, if the acceptor receives a STOMP message with a body larger than or equal to 204800 bytes (that is, 200 kilobytes), the broker stores the message as a large message. If you do not explicitly specify a value for this property, the broker uses a default value of 102400 (that is, 100 kilobytes).

    Note

    To deliver a large message to a STOMP consumer, the broker automatically converts the message from a large message to a normal message before sending it to the client. If a large message is compressed, the broker decompresses it before sending it to STOMP clients.

8.4. Large messages and Java clients
Copy link

When developing JAVA clients, you can manage large messages by using instances of InputStream and OutputStream, or by directly streaming a JMS BytesMessage or StreamMessage.

Using instances of InputStream and OutputStream
A FileInputStream can be used to send a message taken from a large file on a physical disk. A FileOutputStream can then be used by the receiver to stream the message to a location on its local file system.
Using a JMS BytesMessage or StreamMessage directly

The following example shows how to stream a JMS BytesMessage or StreamMessage directly: 

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
}
Copy to Clipboard Toggle word wrap

Additional resources

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat