Chapter 11. Configuring 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.

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.

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)

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

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:

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.