JBoss Messaging 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 JBoss Messaging transparently pages messages into and out of memory as they are needed, thus allowing massive queues with a low memory footprint.
JBoss Messaging will start paging messages to disk, when either a) the size of the queue reaches a total configured maximum size or b) The total size of all queues reaches a configured maximum size.
These two modes of operation are called Address Paging Mode and Global Paging Mode .
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.
JBoss Messaging goes into global paging mode when the total memory used by all queues reaches a configured maximum value, determined by paging-max-global-size-bytes.
These messages are depaged back into memory once enough memory (global-page-size) has been freed up.
Global paging parameters are specified on the main configuration file.
<configuration xmlns="urn:jboss:messaging" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:jboss:messaging /schema/jbm-configuration.xsd"> ... <paging-max-global-size-bytes>20485760</paging-max-global-size-bytes> <global-page-size>1048576</global-page-size> ...
Table 23.1. Paging Configuration Parameters
| Property Name | Description | Default |
|---|---|---|
| paging-directory | Where page files are stored. JBoss Messaging will create one folder for each address being paged under this configured location. | data/paging |
| paging-max-global-size-bytes | JBoss Messaging enters into global page mode as soon as the total memory consumed by messages hits this value. | -1 (disabled) |
| global-page-size | The standard size of a page-file. JBoss Messaging will only read messages when there is enough space to read at least one page file, determined by this value. | 10MiB (10 * 1024 * 1024 bytes) |
It is also possible to configure paging at the address level. As soon as messages delivered to an address exceed the configured size, that address alone goes into page mode.
Address level configuration is done at the address settings.
<address-settings>
<address-setting match="jms.someaddress">
<max-size-bytes>-1</max-size-bytes>
<page-size-bytes>10485760</page-size-bytes>
<drop-messages-when-full>10485760</drop-messages-when-full>
</address-setting>
</address-settings>
This is the list of available parameters on the address settings.
Table 23.2. Paging Address Settings
| Property Name | Description | Default |
|---|---|---|
| max-size | What's the max memory the address could have before entering on page mode. | -1 (disabled) |
| page-size-bytes | The size of each page file used on the paging system | 10MiB (10 * 1024 * 1024 bytes) |
| drop-messages-when-full | if true, messages are dropped instead of paged when used-memory is greater than max-size | false |
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 to not get delivered.
For example:
An address has 10 queues
One of the queues does not deliver its messages (maybe because of a slow consumer).
Messages continually arrive at the address and paging is started.
The other 9 queues are empty even though messages have been sent.
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 9.1.32, “Paging” for an example which shows how to use paging with JBoss Messaging.