JEUS MQ Server Configuration

This chapter describes how to configure the JMS engines and resources that are used to run a JEUS MQ server.

1. Overview

A JEUS MQ server functions as a JMS engine in JEUS, and a single JEUS MQ server can run on each JEUS server. For more information about each component of JEUS, refer to Introduction in JEUS Server Guide.

1.1. Directory Structure

The following figure shows the location of files that are needed to set and manage JEUS and JEUS MQ servers. "JEUS_HOME" is the JEUS installation directory path.

{JEUS_HOME}
   |--bin
   |   |--[01]jeusadmin
   |--logs

* Legend
- [01]: binary or executable file
- [X] : XML document
- [J] : JAR file
- [T] : Text file
- [C] : Class file
- [V] : java source file
- [DD] : deployment descriptor
jeusadmin

A console tool for managing JEUS Manager. It provides overall management functions for JEUS including JEUS Manager and server control. For more information about how to use the tool, refer to jeusadmin in JEUS Reference Guide.

2. Configuring JMS Resources

JMS Resource consists of the following two elements.

  • Destination

    JEUS MQ server destination setting section. Like Queues or Topics, JEUS MQ servers register destinations in JEUS JNDI Service by reading the domain configuration. For more information, refer to Configuring Destinations.

  • Durable Subscription

    Durable Subscriber setting section for JEUS MQ. For more information, refer to Configuring Durable Subscription.

2.1. Configuring Destinations

Destinations such as Queues and Topics also read domain settings and register with the JEUS JNDI service when the JEUS MQ server starts.

Default Settings

The following is an example of setting Destinations in domain.xml. The setting values are configured within the <destination> tag.

domain.xml
<domain>
  ...
    <jms-resource>
        <destination>
            <type>queue</type>
            <name>ExamplesQueue</name>
            <export-name>jms/ExamplesQueue</export-name>
        </destination>

        <destination>
            <type>topic</type>
            <name>ExamplesTopic</name>
            <export-name>jms/ExamplesTopic</export-name>
        </destination>
    </jms-resource>
</domain>

The following describes each configuration tag.

Tag Description

<type>

The type of a destination. Can be set to either a queue or a topic.

<export-name>

Destinations can be looked up in JNDI with <export-name> just like Connection Factory. If <export-name> is not specified, the <name> value is used.
Configuring Message Flow Control

If the message listener is registered in a queue or topic, and when messages arrive, the messages will be immediately sent to the clients. If the client cannot process the messages fast enough, the messages are accumulated on the client and an OutOfMemory error occurs. To prevent this error, you need to specify the maximum number of messages that can accumulate on the client after which the server suspends sending messages for a given time.

The following is an example of defining message flow control settings by destination in domain.xml. The settings are configured within the <destination> tag.

domain.xml
<domain>
  ...
    <jms-resource>
        <destination>
            <type>queue</type>
            <name>ExamplesQueue</name>
            <export-name>jms/ExamplesQueue</export-name>
            <max-pending-limit>1000</max-pending-limit>
            <resume-dispatch-factor>0.5</resume-dispatch-factor>
        </destination>
    </jms-resource>
</domain>

The following describes each configuration tag.

Tag Description

<max-pending-limit>

The maximum number of messages. (Default: 8192)

<resume-dispatch-factor>

Specifies the proportion of the <max-pending-limit> value. When the JEUS MQ server stops sending messages due to the limitation set in <max-pending-limit>, message transmission will resume once the number of accumulated messages in the client decreases to this proportion. (Default: 0.4)

For example, if set as described above, the server will stop sending messages when the number of accumulated messages in the client reaches 1,000, and will resume transmission once the number of messages drops to 500.

2.2. Configuring Durable Subscription

Since durable subscribers are typically created by clients, any messages sent to the topic before the durable subscriber creation cannot be delivered to the client. To avoid this issue, JEUS MQ registers a durable subscriber by configuring the durable subscription before the server starts so that it can send a message when a client is connected.

Similar to invoking the Session.createDurableSubscriber() method, the client ID, subscription name, and topic must be specified when configuring a durable subscription using JEUS WebAdmin. A message selector can also be configured.

domain.xml
<domain>
  ...
    <jms-resource>
        <durable-subscription>
            <client-id>client_id1</client-id>
            <name>subscription1</name>
            <destination-name>ExamplesTopic</destination-name>
        </durable-subscription>
    </jms-resource>
</domain>

3. Configuring JMS Quotas

3.1. Configuring Quotas

If messages fail to be sent to a client and accumulate at the destination, an OutOfMemoryError may occur on the JVM and the server may be terminated. To avoid this problem, JEUS MQ provides quota configuration to apply different memory management for each JMS destination.

JEUS MQ servers hold strong references to message contents when the destination does not use a lot of memory. JEUS MQ servers operate according to the 'Quota' property settings.

  • If the amount of memory used exceeds the 'Quota' value, messages from the clients trigger a JMSException.

  • If the amount of memory used exceeds 75% of the 'Quota' value, the memory can no longer manage the stored messages.

Even after a message at a destination is deleted from the memory, the message will not be lost. Since the message is saved in the storage, a JEUS MQ server can read and process the message in the storage when necessary. The processing speed is slower when using the storage than memory.

The memory of a JEUS MQ server always keeps the messages that are not saved in the storage. The 'Quota' property is applicable only when a storage is configured and a message is set to DeliveryMode.PERSISTENT.

After configuring quota, you can configure the destination to use quota functionality. For more information, refer to Configuring Destinations.

4. Configuring JMS Engines

You can configure the JMS engine by writing the domain.xml file.

4.1. Basic Information

JEUS MQ server can be configured within the <jms-engine> tag. The JMS engine provides an environment for using the JMS server on the server. It runs when the server boots, and only one JMS engine is supported on one server.

The JMS engine configuration contains basic options including engine roll, JEUS MQ failover, and quota, as well as advanced options for the JMS engines. To enable recovery from a server or network failure, you can configure the failover settings. For more information about the failover settings, refer to JEUS MQ Failover.

  • Engine Memory Management

    The quota information for JMS memory management can be configured through 'Max Bytes' and 'Max Messages' items on the basic JMS engine configuration. JEUS MQ server manages memory by using the quota settings for the JMS engine, which manages the memory of all destinations within the server, and the quota settings for each destination. For more information about memory management policies, refer to Configuring JMS Quotas.

    The following is an example of configuring the engine memory settings on the server.

    domain.xml
    <domain>
  ...
    <jms-engine>
        <max-byte>128M</max-byte>
        <max-message>0</max-message>
    </jms-engine>
</domain>

    The following describes each configuration tag.

    Tag Description

    <max-byte>

    Specifies the maximum memory size that can be used by the JMS Engine. It can be set by adding 'K' (KiloBytes), 'M' (MegaBytes), or 'G' (GigaBytes) after the number. (Default: 128MBytes)

    <max-message>

    Specifies the maximum number of messages that can be used by the JMS Engine. If not set, there is no limit on the number of messages.

  • Advanced Options

    In the advanced options configuration of the JMS engine, you can specify the thread pool settings.

    There are two main types of message handling in the JMS engine. First, a generic message is processed as a single thread by the event manager in order to avoid contention and concurrency. Other special functions, message transfer between cluster, transaction control, and JMS engine control are handled by a thread pool according to each type.

    The following is an example of thread settings on the server.

    domain.xml
    <domain>
  ...
    <jms-engine>
        <thread-pool>
             <min>10</min>
             <max>20</max>
             <keep-alive-time>300</keep-alive-time>
        </thread-pool>
    </jms-engine>
</domain>

    The following describes each configuration tag.

    Tag Description

    <min>

    Specifies the minimum size of the thread pool.

    <max>

    Specifies the maximum size of the thread pool.

    <keep-alive-time>

    Specifies the duration (in seconds) for which unused threads, exceeding the <min> value, can remain idle before being destroyed. (Default: 300)

4.2. Configuring Service Channels

A JEUS MQ server communicates with a client through a service channel. Each JEUS MQ server must have one service channel, and it is possible to set a different network such as a service URL for each service channel.

The name of a listener used by the service channel is set with <listener-name> under <service-config>. For detailed information on listener settings, refer to Listener Configuration in JEUS Server Guide.

The following sets a service channel on the server.

domain.xml
<domain>
  ...
    <jms-engine>
        <service-config>
             <name>default</name>
             <listener-name>jms</listener-name>
             <client-limit>1000</client-limit>
             <client-keepalive-timeout>20</client-keepalive-timeout>
        </service-config>
    </jms-engine>
</domain>

The following describes each configuration tag. At least one must be set for the service channel to provide the messaging service.

Tag Description

<name>

Specifies the name of a service channel. Required to specify channel information to the Connection Factory.

<listener-name>

Specifies a listener for the service channel. Must be selected from the settings that already exist on the server. If not set, the Base-listener is used.

<client-limit>

Specifies the maximum number of clients allowed by the service channel.

<client-keepalive-timeout>

Specifies the time period (in seconds) to wait for reconnection when the client connection is abnormally terminated. When the specified time elapses, all client resources are returned to the server. Since the clientID value is maintained during this period, this setting should only be used when network conditions are poor. If set to a value less than 0, resources are returned immediately without waiting.

4.3. Configuring Connection Factories

A connection factory is a JMS management object that contains the connection information needed to access the JMS server and basic information for the client. It is created when the JEUS MQ server boots, and registered in the JEUS JNDI service.

The following is an example of configuring a connection factory on the server.

domain.xml
<domain>
  ...
    <jms-engine>
        <connection-factory>
            <type>nonxa</type>
            <name>ConnectionFactory</name>
            <export-name>jms/ConnectionFactory</export-name>
        </connection-factory>
    </jms-engine>
</domain>

The following describes each configuration tag.

Tag Description

<type>

Specifies the type of a connection factory.

<name>

Specifies the name of a connection factory used for management purposes within the JMS system.

<export-name>

Specifies the name with which the connection factory is bound to the Naming Server. If not set, the Name property is used as is.

4.4. Configuring Persistence Stores

A persistence store is needed to restore messages, subscriptions, or transactions to the previous state when the server restarts. If a persistence store is not configured, a message that the client sent in the DeliveryMode.PERSISTENT mode cannot be properly delivered if the server fails. JEUS MQ provides two types of persistence stores, journal log and database.

Persistence store can be configured in <persistence-store> under <jms-engine>.

The following is an example of configuring a persistence store on the server.

domain.xml
<domain>
  ...
    <jms-engine>
        <persistence-store>
          <journal>
            <base-dir>/home/example/store/jeusmq</base-dir>
            <!--<initial-log-file-count>5</initial-log-file-count>-->
            <!--<max-log-file-count>10</max-log-file-count>-->
            <!--<log-file-size>128M</log-file-size>-->
            <!--<property>-->
              <!--<key>jeus.store.journal.overflow-factor</key>-->
              <!--<value>0.3</value>-->
            <!--</property>-->
          </journal>
          <!--<jdbc>-->
            <!--<data-source>datatsource1</data-source>-->
            <!--<vendor>oracle</vendor>-->
            <!--<destination-table>TEST_DEST</destination-table>-->
            <!--<durable-subscriber-table>TEST_DSUB</durable-subscriber-table>-->
            <!--<message-table>TEST_MESG</message-table>-->
            <!--<subscription-message-table>TEST_SMSG</subscription-message-table>-->
            <!--<transaction-table>TEST_TRAN</transaction-table>-->
          <!--</jdbc>-->
        </persistence-store>
    </jms-engine>
</domain>

The following is a description of each child tag for the Store setting of <persistence-store>.

  • <journal>

    Uses journal log mode.

    Tag Description

    <base-dir>

    Specifies the name of a directory in which the Store will be created. This directory name must be unique for each Store.

    <initial-log-file-count>

    Specifies the number of log files that will be initially generated when creating a Journal Store.

    <max-log-file-count>

    Specifies the maximum number of log files to create.

    <log-file-size>

    Specifies the size of a log file. It can be set by appending 'K' (KiloBytes), 'M' (MegaBytes), or 'G' (GigaBytes) after an integer type value or number.

  • <jdbc>

    Uses database mode. Currently compatible external databases are 'Oracle Database 9i or later (Enterprise Edition)', 'Tibero 3 SP2 or later', and 'Altibase 4.x (5 or later is not supported)'.

    The Data Source property specifies the JNDI name of a data source to be used as a persistence store. For more information about adding data sources to JEUS, refer to DB Connection Pool and JDBC in JEUS Server Guide.

    The JNDI configuration is used to change the names of tables in the database. If the aforementioned basic configurations are used, the JEUS MQ server that is in operation can be tested by changing the table names, without having to install additional persistence stores. The following tables in the database are used by default if table names are not configured. <SERVER-NAME>_DEST, <SERVER-NAME>_DSUB, <SERVER-NAME>_MESG, <SERVER-NAME>_SMSG, and <SERVER-NAME>. For detailed information about each column of the tables created when JDBC is configured, refer to JDBC Persistence Store Columns.

    Tag Description

    <data-source>

    Set the data source of the database.

    <destination-table>

    Changes the destination table name. Lowercase is not allowed.

4.5. Message Sorting

For more information about message sorting, refer to JEUS MQ Message Sort.

5. Management and Monitoring

JEUS MQ servers should be managed with the following functions in order to guarantee seamless services without message loss.

  • Manages and monitors the resources on running JEUS MQ servers.

    The following resources are managed and monitored.

    • JMS management objects including connection factories and destinations

    • Messages in destinations and durable subscriptions

    • Connections, sessions, and message producers and consumers

    • Memory space occupied by JEUS MQ servers

    • Persistent storage used by JEUS MQ servers

  • Handles failures and recovers JEUS MQ servers from them.

This section introduces how to manage and monitor JEUS MQ servers with jeusadmin, a JEUS console tool.

5.1. Server Management

The following describes how to manage servers using jeusadmin.

Using the console tool

You can manage the server resources by executing various commands in the console tool. The console tool is found in the following directory.

JEUS_HOME/bin/

The following are the jeusadmin commands.

  • Connection Factory

    Command Description

    add-jms-connection-factory

    Adds connection factories.

    remove-jms-connection-factory

    Deletes connection factories.

  • Destination

    Command Description

    add-jms-destination

    Adds destinations.

    remove-jms-destination

    Deletes destinations.

  • Durable Subscriber

    Command Description

    add-jms-durable-subscription

    Adds durable subscriptions.

    remove-jms-durable-subscription

    Deletes durable subscriptions.

For detailed descriptions of these commands, refer to JMS Engine Commands in JEUS Reference Guide.

5.2. Server Monitoring

This section explains how to monitor servers using jeusadmin.

Using the console tool

You can manage the server resources by executing various commands in the console tool. The console tool is found in the following directory.

JEUS_HOME/bin/

The following commands are provided for server monitoring.

  • Connection Factory

    Command Description

    list-jms-connection-factories

    Checks the connection factory list and displays connection factory information.

  • Destination

    Command Description

    list-jms-destinations

    Checks the destination list and displays destination information.

    control-jms-destination

    Controls the state of a specified destination.

  • Messages

    Command Description

    list-jms-messages

    Searches for messages in a specified destination.

    view-jms-message

    Searches for the detailed information of a specified message.

    move-jms-messages

    Moves the specified messages to another destination in the cluster or server.

    delete-jms-messages

    Deletes the specified messages from the destination.

    export-jms-messages

    Sends the specified messages in the XML format.

    import-jms-messages

    Retrieves the exported XML messages to the specified destination.

  • Durable Subscription

    Command Description

    list-jms-durable-subscriptions

    Searches the list of Durable Subscriptions or the information about a specified Durable Subscription.

  • Clients

    Command Description

    list-jms-clients

    Searches the list of clients and displays the client information.

    ban-jms-client

    Forcibly closes the connection with the client.

  • Transactions

    Command Description

    list-jms-pending-transactions

    Displays the list of pending transactions.

    commit-jms-pending-transaction

    Forcibly commits the specified pending transaction.

For detailed descriptions of these commands, usage, and usage examples, refer to JMS Engine Commands JEUS Reference Guide.