JBoss.orgCommunity Documentation

Chapter 24. Paging

24.1. Page Files
24.2. Configuration
24.3. Paging Mode
24.3.1. Configuration
24.4. Dropping messages
24.5. Blocking producers
24.6. Caution with Addresses with Multiple Queues
24.7. Paging and message selectors
24.8. Paging and browsers
24.9. Paging and unacknowledged messages
24.10. Example

HornetQ transparently supports huge queues containing millions of messages while the server is running with limited memory.

In such a situation it's not possible to store all of the queues in memory at any one time, so HornetQ transparently pages messages into and out of memory as they are needed, thus allowing massive queues with a low memory footprint.

HornetQ will start paging messages to disk, when the size of all messages in memory for an address exceeds a configured maximum size.

By default, HornetQ does not page messages - this must be explicitly configured to activate it.

Messages are stored per address on the file system. Each address has an individual folder where messages are stored in multiple files (page files). Each file will contain messages up to a max configured size (page-size-bytes). When reading page-files all messages on the page-file are read, routed and the file is deleted as soon as the messages are recovered.

You can configure the location of the paging folder

Global paging parameters are specified on the main configuration file (hornetq-configuration.xml).

<configuration xmlns="urn:hornetq"
            xsi:schemaLocation="urn:hornetq /schema/hornetq-configuration.xsd">

As soon as messages delivered to an address exceed the configured size, that address alone goes into page mode.

Instead of paging messages when the max size is reached, an address can also be configured to just drop messages when the address is full.

To do this just set the address-full-policy to DROP in the address settings

Instead of paging messages when the max size is reached, an address can also be configured to block producers from sending further messages when the address is full, thus preventing the memory being exhausted on the server.

When memory is freed up on the server, producers will automatically unblock and be able to continue sending.

To do this just set the address-full-policy to BLOCK in the address settings

In the default configuration, all addresses are configured to block producers after 10 MiB of data are in the address.

When a message is routed to an address that has multiple queues bound to it, e.g. a JMS subscription, there is only 1 copy of the message in memory. Each queue only deals with a reference to this. Because of this the memory is only freed up once all queues referencing the message have delivered it. This means that if not all queues deliver the message we can end up in a state where messages are not delivered.

For example:

In this example we have to wait until the last queue has delivered some of its messages before we depage and the other queues finally receive some more messages.

See Section 11.1.41, “Paging” for an example which shows how to use paging with HornetQ.