Chapter 11. Configuring Paging

11.1. About Paging

JBoss EAP messaging supports many message queues with each queue containing millions of messages. The JBoss EAP messaging server runs with limited memory thereby making it difficult to store all message queues in memory at one time.

Paging is a mechanism used by the JBoss EAP messaging server to transparently page messages in and out of memory on an as-needed basis in order to accommodate large message queues in a limited memory.

JBoss EAP messaging starts paging messages to disk, when the size of messages in memory for a particular address exceeds the maximum configured message size.

Note

JBoss EAP messaging paging is enabled by default.

11.2. Page Files

There is an individual folder for each address on the file system which stores messages in multiple files. These files which store the messages are called page files. Each file contains messages up to the maximum configured message size set by the page-size-bytes attribute.

The system navigates the page files as needed and removes the page files as soon as all messages in the page were received by client.

Warning

For performance reasons, JBoss EAP messaging does not scan paged messages. Therefore, you should disable paging on a queue that is configured to group messages or to provide a last value. Also, message prioritization and message selectors will not behave as expected for queues that have paging enabled. You must disable paging for these features to work as expected

For example, if a consumer has a message selector to read messages from a queue, only the messages in memory that match the selector are delivered to the consumer. When the consumer acknowledges delivery of these messages, new messages are de-paged and loaded into memory. There may be messages that match a consumer’s selector on disk in page files but JBoss EAP messaging does not load them into memory until another consumer reads the messages in memory and provides free space. If the free space is not available, the consumer employing a selector may not receive any new messages.

11.3. Configuring the Paging Directory

You can read the configuration for the paging directory by using the management CLI command below. In this example, the output displays the default configuration.

/subsystem=messaging-activemq/server=default/path=paging-directory:read-resource
{
    "outcome" => "success",
    "result" => {
        "path" => "activemq/paging",
        "relative-to" => "jboss.server.data.dir"
    }
}

The paging-directory configuration element specifies the location on the file system to store the page files. JBoss EAP creates one folder for each paging address in this paging directory and the page files are stored within these folders. By default, this path is activemq/paging/. You can change the path location by using the following management CLI command.

/subsystem=messaging-activemq/server=default/path=paging-directory:write-attribute(name=path,value=PATH_LOCATION)

Also note the relative-to attribute in the example output above. When relative-to is specified, the value of the path attribute is treated as relative to the file path specified by the relative-to attribute. By default, this value is the JBoss EAP jboss.server.data.dir property. For standalone servers, jboss.server.data.dir is located at EAP_HOME/standalone/data/. For managed domains, each server will have its own serverX/data/activemq/ directory located under EAP_HOME/domain/servers/. You can change the value of relative-to using the following management CLI command.

/subsystem=messaging-activemq/server=default/path=paging-directory:write-attribute(name=relative-to,value=RELATIVE_LOCATION)

11.4. Configuring Paging Mode

When messages delivered to an address exceed the configured size, that address goes into paging mode.

Note

Paging is done individually per address. If you configure a max-size-bytes for an address, it means each matching address will have a maximum size that you specified. However it does not mean that the total overall size of all matching addresses is limited to max-size-bytes.

Even with page mode, the server may crash due to an out-of-memory error. JBoss EAP messaging keeps a reference to each page file on the disk. In a situation with millions of page files, JBoss EAP messaging can face memory exhaustion. To minimize this risk, it is important to set the attribute page-size-bytes to a suitable value. You must configure the memory for your JBoss EAP messaging server to be greater than two times the number of destinations times the max-size-bytes, otherwise an out-of-memory error can occur.

You can read the current maximum size in bytes (max-size-bytes) for an address by using the following management CLI command.

/subsystem=messaging-activemq/server=default/address-setting=ADDRESS_SETTING:read-attribute(name=max-size-bytes)

You can configure the maximum size in bytes (max-size-bytes) for an address by using the following management CLI command.

/subsystem=messaging-activemq/server=default/address-setting=ADDRESS_SETTING:write-attribute(name=max-size-bytes,value=MAX_SIZE)

Use a similar syntax when reading or writing the values for the other paging-related attributes of an address setting. The table below lists each attribute, along with a description and a default value.

The following table describes the parameters on the address settings:

Table 11.1. Paging Configuration for Address Settings

ElementDescription

address-full-policy

This value of this attribute is used for paging decisions. The valid valid values are listed below.

PAGE
Enables paging and page messages beyond the set limit to disk.
DROP
Silently drops messages that exceed the set limit.
FAIL
Drops messages and sends an exception to client message producers.
BLOCK
Blocks client message producers when they send messages beyond the set limit.

The default is PAGE.

max-size-bytes

This is used to specify the maximum memory size the address can have before entering into paging mode. The default is 10485760.

page-max-cache-size

The system will keep page files up to page-max-cache-size in memory to optimize Input/Output during paging navigation. The default is 5.

page-size-bytes

This is used to specify the size of each page file used on the paging system. The default is 2097152.

Important

By default, all addresses are configured to page messages after an address reaches max-size-bytes. If you do not want to page messages when the maximum size is reached, you can configure an address to drop messages, drop messages with an exception on client side, or block producers from sending further messages by setting the address-full-policy to DROP, FAIL and BLOCK respectively.

Be aware that if you change the address-full-policy from PAGE to BLOCK after any destination has started to page messages, consumers will no longer be able to consume paged messages.

Addresses with Multiple Queues

When a message is routed to an address that has multiple queues bound to it, there is only a single copy of the message in memory. Each queue only handles a reference to this original copy of the message, so the memory is freed up only when all the queues referencing the original message, have delivered the message.

Note

A single lazy queue/subscription can reduce the Input/Output performance of the entire address as all the queues will have messages being sent through an extra storage on the paging system.