Configuring Open MQ using standalone tools

Open MQ is shipped with a collection of utilities that can be used to configure and administer its runtime environment and resources. In this section, we provide a brief introduction to these utilities. For a detailed description of these utilities, you can refer to the Open MQ document set, located at http://docs.sun.com/app/docs/coll/1307.6.

Starting and stopping the Open MQ broker

The imqbrokerd utility is used to start a message broker. To start the default broker configured for GlassFish, open a command-line terminal, and enter the following commands:

# cd $AS_INSTALL/imq/bin
# ./imqbrokerd -tty

You should see an output describing the information about the broker, and the confirmation of the successful start of the broker.

If we do not specify a broker name, the imqbrokerd command will try to start the default broker named imqbroker. We can also supply a name <broker_name>. If the broker named <brokername> is already created, then the imqbrokerd command starts it; otherwise, a new broker of this name is created and then started.

To shutdown the message broker, enter Ctrl+C in the terminal where imqbrokerd is running.

Refer to the Open MQ documentation for information on how to run Open MQ brokers as a service.

Administering the Open MQ Broker using imqcmd

The main CLI utility we use to manage the Open MQ is imqcmd. It supports a long list of commands that can be used to create, destroy, modify, and display the information of a resource, such as a broker or a physical destination, and so on. To show the commands and options supported, enter the following commands in a terminal:

# cd $AS_INSTALL/imq/bin
# ./imqcmd -h

As the first example, we can use the following command to display the status information of the currently running broker:

# cd $AS_INSTALL/imq/bin
# ./imqcmd query bkr -u admin

Once you are prompted to enter the password, enter the default password admin. You should see an output describing the information regarding the currently running broker.

We can store the password in a password file and use the -passfile option to point to this file.

As another example, the following command queries the physical queue destination named PSQueueDest, and displays its information in the command-line terminal.

# cd $AS_INSTALL/imq/bin
# ./imqcmd query dst -t q -n PSQueueDest -u admin

In this example, the option –t specifies the type of the destination as a topic, and the option –n PSQueueDest specifies the name of the physical destination.

Refer to the help information and the MQ Administration Guide for a detailed description of the imqcmd utility.

Using the imqadmin administration console

The imqadmin utility is the primary GUI-based administration console of the Open MQ. It supports more of the functions of the imqcmd utility. Besides, it can also manage and confi gure the administration objects used by applications, such as specifying a naming service provider, and registering connection factories and destination resources in the naming service.

To start the administration console, open a command-line terminal, and type the following command:

# cd $AS_INSTALL/imq/bin
# ./imqadmin

You should see the administrator console window displayed. The administration console’s navigation pane contains two top-level nodes, Brokers and Object Stores. The Brokers node organizes all the registered Open MQ brokers being managed by the administration console. The Object Stores node organizes the naming service providers to which the JMS administration objects (connection factories and destination resources) are registered.

The following steps walk you through the typical process of adding a broker, and managing the broker resources.

1. From the navigation pane of the administrator console, right click the Brokers node, and choose Add Broker. You should see a dialog box displayed.
2. Fill out the Add Broker dialog according to the following screenshot, enter admin in the password field, and click OK.



Now you should see the broker PSBroker is listed under the Brokers node with a red X on its icon, which indicates that the broker is not currently connected to the administrator console yet.

Adding a broker does not create or start a new physical broker. It merely registers an existing broker to the administration console, and once we connect the administration console, we will be able to manage the resources of the broker.

3. From the navigation pane, right click PSBroker under the Brokers node, and choose Connect to Broker. Once you connect to the broker, you should see the red X disappeared on the Brokers node.
4. From the navigation pane, click Services under PSBroker. In the result pane, you should see all the available connection services listed for the broker, as shown in the following screenshot.



5. From the navigation pane, right click Destinations under PSBroker, and select Add Broker Destination. You should see a dialog displayed.
6. Enter PSQueueDest in the Destination Name field, select Queue radio button if not already selected. Keep all the other settings unchanged, and click OK to add the physical destination.
7. From the navigation pane, click Destinations under PSBroker, the newly added PSQueueDest should appear.

With physical destinations created, we can go through the following steps to configure the connection factory and destination resources in the Object Stores:

1. Right click the Object Stores node in the navigation pane, and choose Add Object Store.
2. Enter the following information in the dialog, and click OK to add the Object Store.

• Enter PSStore in the Object Store Label field.
• From the Name pull-down menu, select java.naming.factory.initial, and enter com.sun.jndi.fscontext.RefFSContextFactory in the value field.
• Click the Add button. These steps set the JNDI service provider you will use, to a filesystem based object store.
• From the Name pull-down menu, select java.naming.provider.url, and enter file:///tmp in the value field.
• Click the Add button. These steps set the exact location of the object store to the directory /tmp.

In the navigation pane, you will see the object store PSStore you just added is listed under the Object Stores node with a red X on its icon, which indicates that the object store is not currently connected to the administrator console yet.

From the navigation pane, right click PSStore under the Object Stores node, and choose Connect to Object Store. Once you connect to the object store, you should see that the red X has disappeared on the Object Stores node.

From the navigation pane of the Open MQ administrator console, right click Destinations under PSStore node, and select Add Destination Object. You should see a dialog box displayed.

Enter PSQueue in the Lookup Name field, select Queue from the Destination Type radio button. Enter PSQueueDest in the Destination Name field, and click OK to add the queue destination, as shown in the following screenshot.

Now that we have seen how Open MQ is integrated with GlassFish, let’s look at another very popular open source JMS implementation, ActiveMQ.

Configuring ActiveMQ for GlassFish

ActiveMQ is a very popular open source provider that is fully JMS 1.1 compliant. Besides, Active MQ has several very appealing features, such as cross language support for client development, high availability support, and support for REST API, and so on. For a more detailed description of the ActiveMQ product, visit the ActiveMQ project website hosted by Apache: http://activemq.apache.org.

GlassFish is shipped with a generic JMS JCA resource adapter. In this section, we use ActiveMQ as an example to demonstrate how this generic resource adapter allows GlassFish to integrate with third-party JMS providers.

Many JMS providers, including ActiveMQ includes its own JCA resource adapters for integrating with a Java EE application server. In this book, we do not cover this topic. You can refer to the JMS provider’s documentation to enable this. For example, integrating ActiveMQ into GlassFish using ActiveMQ’s resource adapter is actually quite similar to using the GlassFish resource adapter.

Installing and configuring ActiveMQ

The first step of integrating with ActiveMQ is to install it. Installing ActiveMQ is very straight forward. Simply download the latest ActiveMQ binary distribution (ZIP format for Window, and GZIP for UNIX/Linux/Mac OS X) from http://activemq.apache.org, and extract it to a target directory. For example, /opt. Next, let’s start the ActiveMQ broker with the following commands:

# cd /opt/apache-activemq-5.3.0/bin
# ./activemq-admin start

There are a variety of ways to configure ActiveMQ. The most comprehensive mechanism is to work with XML-based configuration files. This approach can be used to define all aspects of a message broker and its components, such as message destination. For a detailed discussion, please refer to the ActiveMQ documentation for more information on this.

ActiveMQ also provides a simple web-based user interface for basic administrative tasks, such as creating/deleting message destinations (both topics and queues), sending messages to a destination for testing, and browsing messages in a destination, and so on.

Now let’s use the administrative user interface to configure a queue. To do this, complete the following steps:

Open a browser, and access the ActiveMQ admin URL http://localhost:8161/admin. The ActiveMQ administration page appears.

Click Queues.

The browser lists the message queues configured for the ActiveMQ broker. By default, a queue named example.A is configured, as shown in the following screenshot.

In the next section, we show you how to integrate this sample queue into GlassFish.