Chapter 4   Administration Console Tutorial

This tutorial focuses on the use of the Administration Console, a graphical interface for administering a Sun™ ONE Message Queue (MQ) message server. By following this tutorial, you will learn how to do the following:

• Start a broker and use the Console to connect to it and manage it
• Create physical destinations on the broker
• Create an object store and use the Console to connect to it
• Add administered objects to the object store

The tutorial is designed to set up the destinations and administered objects needed to run a simple JMS-compliant application, SimpleJNDIClient. In the last part of the tutorial you run this application.

This tutorial is provided mainly to guide you through performing basic administration tasks using the Administration Console. It is not a substitute for reading through the MQ Developer's Guide or other chapters of this Administrator's Guide.

Some MQ administration tasks cannot be accomplished using graphical tools; you will need to use command line utilities to perform such tasks as the following:

• Configuring certain broker properties

Some broker properties cannot be configured using the Administration Console. These can be configured as described in Chapter 5, "Starting and Configuring a Broker" or in "Updating a Broker".

• Creating broker clusters

See"Working With Clusters (Enterprise Edition)" for more information.

• Managing a user database

See "Authenticating Users" for more information.

Getting Ready

---

Before you can start this tutorial you must install the MQ product. For more information, see the MQ Installation Guide. Note that this tutorial is Windows-centric, with added notes for unix users.

In this tutorial, choosing Item1 > Item2 > Item3 means that you should pull down the menu called Item1, choose Item2 from that menu and then choose Item3 from the selections offered by Item2.

Starting the Administration Console

---

The Administration Console is a graphical tool that you use to do the following:

• Create references to and connect to brokers
• Administer brokers
• Create physical destinations on the brokers, which are used by the broker for message delivery
• Connect to object stores in which you place MQ administered objects

Administered objects allow you to manage the messaging needs of JMS-compliant applications. For more information, see "MQ Administered Objects".

To start the Administration Console

1. Choose Start > Programs > Sun ONE Message Queue 3.0> Administration.

You may need to wait a few seconds before the Console window is displayed.

Non-Windows users: enter the following command at the command prompt:

$IMQ_HOME/bin/imqadmin (/usr/bin/imqadmin on Solaris)

2. Take a few seconds to examine the Console window.





The Console features a menu at the top, a tool bar just underneath the menu, a navigation pane to the left, a larger pane to the right (now displaying graphics identifying the Sun ONE Message Queue product), and a status pane at the bottom.

No tutorial can provide complete information, so let's first find out how to get help information for the Administration Console.

Getting Help

Locate the Help menu at the extreme right of the menu bar.

To display Administration Console help information

1. Pull down the Help menu and choose Overview. A help window is displayed.





Notice how the help information is organized. The left pane shows a table of contents; the right pane shows the contents of any item you select on the left.

Look at the right pane of the Help window. It shows a skeletal view of the Administration Console, identifying the use of each of the Console's panes.

2. Look at the Help window's contents pane. It organizes topics in three areas: overview, object store management, and broker management. Each of these areas contains files and folders. Each folder provides help for dialogs containing multiple tabs; each file provides help for a simple dialog or tab.

Your first Console administration task, "Adding a Broker", will be to create a reference to a broker you manage through the Console. Before you start, however, check the online help for information.

3. Click the Add Broker item in the Help window's contents pane.

Note that the contents pane has changed. It now contains text that explains what it means to add a broker and that describes the use of each field in the Add Broker dialog. Field names are shown in bold text.

4. Read through the help text.
5. Close the Help window.

Working With Brokers

---

A broker provides delivery services for an MQ messaging system. Message delivery is a two-phase process: the message is first delivered to a physical destination on a broker and then it is delivered to one or more consuming clients.

Working with brokers involves the following tasks:

• Start and configure the broker

You can start the broker from the Start > Programs menu on Windows or by using the imqbrokerd command. If you use the imqbrokerd command, you can specify broker configuration information using command line options. If you use the Programs menu, you can specify configuration information using the Console and in other ways described in Chapter 5, "Starting and Configuring a Broker."




---

Note	You cannot start a broker instance using the Administration Console .

---




• Manage the broker and its services either by using the Administration Console or by using the Command command-line utility (imqcmd).
• Create the physical destinations needed by client applications
• Monitor resource use to improve throughput and reliability

The broker supports communication with both application clients and administration clients. It does this by means of different connection services, and you can configure the broker to run any or all of these services. For more information about connection services, see "Connection Services".

Starting a Broker

You cannot start a broker using the Administration Console. Start the broker as described below (also, see Chapter 5 "Starting and Configuring a Broker").

To start a broker

1. Choose Start > Programs >Sun ONE Message Queue 3.0 > Broker.

Non-Windows: enter the following command to start a broker.

%$IMQ_HOME/bin/imqbrokerd (/usr/bin/imqbrokerd on Solaris)

A broker process window is displayed. The name of the broker is specified as is the fact that it is ready.





2. Bring the Administration Console window back into focus. You are now ready to add the broker to the Console and to connect to it.

You do not have to start the broker before you add a reference to it in the Administration Console, but you must start the broker before you can connect to it.

Adding a Broker

Adding a broker creates a reference to that broker in the Administration Console. After adding the broker, you can connect to it.

To add a broker to the Administration Console

1. Right-click on Brokers in the navigation pane and choose Add Broker.
2. Enter MyBroker in the Broker Label field.

This provides a label that identifies the broker in the Administration Console.





Note the default host name (localhost) and primary port (7676) specified in the dialog. These are the values you will need to specify later, when you configure the connection factory that the client will use to set up connections to this broker.

Leave the Password field blank. Your password will be more secure if you specify it at connection time.

3. Click OK to add the broker.

Look at the navigation pane. The broker you just added should be listed there under Brokers. The red X over the broker icon tells you that the broker is not currently connected to the Console.





4. Right-click on MyBroker and choose Properties from the popup menu.

The broker properties dialog is displayed. You can use this dialog to update any of the properties you specified when you added the broker.

Changing the Administrator Password

When you connect to the broker, you are prompted for a password if you have not specified one when you added the broker. For improved security, it's a good idea to change the default administrator password (admin) before you connect.

To change the administrator password

1. Open a command-prompt window or, if one is already opened, bring it forward.
2. Enter a command like the following, substituting your own password for abracadabra. The password you specify then replaces the default password of admin.

imqusermgr update -u admin -p abracadabra

(On Solaris and Linux, you must be root to perform this operation.)

The change takes effect immediately. You must then specify the new password whenever you use one of the MQ command line utilities or the Administration Console.

Although clients use a different connection service than administrators, they are also assigned a default user name and password so that you can test MQ without having to do extensive administrative set up. By default, a client can connect to the broker as user guest with the password guest. You should, however, establish secure user names and passwords for clients as soon as you can. See "Authenticating Users" for more information.

Connecting to the Broker

To connect to the broker

1. Right-click MyBroker and choose Connect to Broker.

A dialog is displayed that allows you to specify your name and password.





2. Enter admin in the Password field or whatever value you specified for the password in "Changing the Administrator Password".

Specifying the user name admin and supplying the correct password connects you to the broker, with administrative privileges.

3. Click OK to connect to the broker.

After you connect to the broker, you can choose from the Actions menu to get information about the broker, to pause and resume the broker, to shutdown and restart the broker, and to disconnect from the broker.

Viewing Connection Services

A broker is distinguished by the connection services it provides and the physical destinations it supports.

To view available connection services

1. Select Services in the navigation pane.

Available services are listed in the results pane. For each service, its name, port number, and state is provided.





2. Select the jms service by clicking on it in the results pane.
3. Pull down the Actions menu and note the highlighted items.

You have the option of pausing the jms service or of viewing and updating its properties.

4. Choose Properties from the Actions menu.

Note that by using the Service Properties dialog, you can assign the service a static port number and you can change the minimum and maximum number of threads allocated for this service.





5. Click OK or Cancel to close the Properties dialog.
6. Select the admin service in the results pane.
7. Pull down the Actions menu.

Notice that you cannot pause this service (the pause item is disabled). The admin service is the administrator's link to the broker. If you paused it, you would no longer be able to access the broker.

8. Choose Actions > Properties to view the properties of the admin service.
9. Click OK or Cancel when you're done.

Adding Physical Destinations to a Broker

You must explicitly create physical destinations on the broker so that JMS-compliant applications can run properly. You do not need to do this if the broker has destination auto-creation enabled, which allows it to create physical destinations dynamically.

Destination auto-creation is acceptable in a development environment. However, in a production setting, it is advisable to turn it off and have the broker use physical destinations that you have explicitly created. This allows you, the administrator, to be fully aware of the destinations that are in use on the broker.

You control whether the broker can add auto-created destinations by setting the imq.autocreate.topic or imq.autocreate.queue properties. For more information, see "Auto-Created (vs. Admin-Created) Destinations".

In this section of the tutorial, you will add a physical destination to the broker. You should note the name you assign to the destination; you will need it later when you create an administered object that corresponds to this physical destination.

To add a queue destination to a broker

1. Right-click the Destinations node of MyBroker and choose Add Broker Destination.

The following dialog is displayed:





2. Enter MyQueueDest in the Destination Name field.
3. Select the Queue radio button if it is not already selected.
4. Make sure the Queue Delivery Policy is selected as Single.
5. Click OK to add the physical destination.

The destination now appears in the results pane.

Working With Physical Destinations

Once you have added a physical destination on the broker, you can do any of the following tasks, as described in the procedures below:

• View and update the properties of a physical destination
• Purge messages at a destination
• Delete a destination

To view the properties of a physical destination

1. Select the Destinations node of MyBroker.
2. Select MyQueueDest in the results pane.
3. Choose Actions > Properties.

The following dialog is displayed:





Note that the only properties you can change for a queue have to do with the size and number of messages that are delivered to that queue.

4. Click Cancel to close the dialog.

To purge messages from a destination

1. Select the physical destination in the Results pane.
2. Choose Actions > Purge Messages.

A confirmation dialog is displayed.

Purging messages removes the messages and leaves an empty destination.

To delete a destination

1. Select the physical destination in the results pane.
2. Choose Edit > Delete.

Deleting a destination purges the messages at that destination and removes the destination.

Getting Information About Topic Destinations

The dialog about topic destinations includes an additional tab that lists information about durable subscriptions.

You can use this dialog to:

• purge durable subscriptions, removing all messages associated with a durable subscription
• delete durable subscriptions, purging all messages associated with a durable subscription and also removing the durable subscription

Working with Object Stores

---

An object store, be it an LDAP directory server or a file system store (directory in the file system), is used to store MQ administered objects that encapsulate MQ-specific implementation and configuration information about objects that are used by client applications.

Although administered objects can be instantiated and configured within client code, it is preferable that you, the administrator, create and configure these objects and store them in an object store that is accessed by client applications through standard JNDI lookup code. This allows client code to be provider-independent.

For more information about administered objects, see "MQ Administered Objects".

You cannot use the Administration Console to create an object store. You must do this ahead of time as described in the following section.

Adding an Object Store

Adding an object store creates a reference to an existing object store in the Administration Console. This reference is retained even if you quit and restart the Console.

To add a file-system object store

1. If you do not already have a folder named Temp on your C drive, create it now.

The sample application used in this tutorial assumes that the object store is a folder named Temp on the C drive. In general, a file-system object store can be any directory on any drive.

Non-Windows: you can use the /tmp directory, which should already exist.

2. Right-click on Object Stores and choose Add Object Store.

The following dialog is displayed:





3. Enter MyObjectStore in the field named ObjectStoreLabel.

This simply provides a label for the display of the object store in the Administration Console.

In the following steps, you will need to enter JNDI name/value pairs. These pairs are used by JMS-compliant applications for looking up administered objects.

4. From the Name pull-down menu, choose java.naming.factory.initial.

This property allows you to specify what JNDI service provider you wish to use. For example, a file system service provider or an LDAP service provider.

5. In the Value field, enter the following

com.sun.jndi.fscontext.RefFSContextFactory

This means that you will be using a file system store. (For an LDAP store, you would specify com.sun.jndi.ldap.LdapCtxFactory.)

In a production environment, you will probably want to use an LDAP directory server as an object store. For information about setting up the server and doing JNDI lookups, see "Object Store Attributes".

6. Click the Add button.

Notice that the property and its value are now listed in the property summary pane.

7. From the Name pull down menu, choose java.naming.provider.url.

This property allows you to specify the exact location of the object store. For a file system type object store, this will be the name of an existing directory.

8. In the Value field, enter the following

file:///C:/Temp

(file:///tmp on Solaris and Linux)

9. Click the Add button.

Notice that both properties and their values are now listed in the property summary pane. If you were using an LDAP server, you might also have to specify authentication information; this is not necessary for a file-system store.

10. Click OK to add the object store.
11. If the node MyObjectStore is not selected in the navigation pane, select it now.

The Administration Console now looks like this:





The object store is listed in the navigation pane and its contents, Destinations and Connection Factories, are listed in the results pane. We have not yet added any administered objects to the object store, and this is shown in the Count column of the results pane.

A red X is drawn through the object store's icon in the navigation pane. This means that it is disconnected. Before you can use the object store, you will need to connect to it.

Checking Object Store Properties

While the Administration Console is disconnected from an object store, you can examine and change some of the properties of the object store.

To display the properties of an object store

1. Right click on MyObjectStore in the navigational pane.
2. Choose Properties from the popup menu.

A dialog is displayed that shows all the properties you specified when you added the object store. You can change any of these properties and click OK to update the old information.

3. Click OK or Cancel to dismiss the dialog.

Connecting to an Object Store

Before you can add objects to an object store, you must connect to it.

To connect to an object store

1. Right click on MyObjectStore in the navigational pane.
2. Choose Connect to Object Store from the popup menu.

Notice that the object store's icon is no longer crossed out. You can now add objects, connection factories and destinations, to the object store.

Adding a Connection Factory
Administered Object

You can use the administration console to create and configure a connection factory. A connection factory is used by client code to connect to the broker. By configuring a connection factory, you can control the behavior of the connections it is used to create.

For information on configuring connection factories, see the online help and the MQ Developer's Guide.

---

Note	The Administration Console lists and displays only MQ administered objects. If an object store should contain a non-MQ object with the same lookup name as an administered object that you wish to add, you will receive an error when you attempt the add operation.

---

To add a connection factory to an object store

1. If not already connected, connect to MyObjectStore (see "Connecting to an Object Store")
2. Right click on the Connection Factories node and choose Add Connection Factory Object.

The Add Connection Factory Object dialog is displayed.





3. Enter the name "MyQueueConnectionFactory" in the LookupName field.

This is the name that the client code uses when it looks up the connection factory as shown in the following line from SimpleAdmin.java:

qcf=(javax.jms.QueueConnectionFactory)
                  ctx.lookup("MyQueueConnectionFactory")

4. Select the QueueConnectionFactory from the pull-down menu to specify the type of the connection factory.
5. Enter the host name and port for the broker to which the client is planning to connect, in the Broker Host Name and Broker Host Port fields.

In this tutorial, the client connects to the default broker--that is, a broker on localhost at port 7676, so you do not have to change these fields.

6. Click through the tabs for this dialog to see the kind of information that you can configure for the connection factory. Use the Help button in the lower right hand corner of the Add Connection Factory Object dialog to get information about individual tabs. Do not change any of the default values for now.
7. Click OK to create the queue connection factory.
8. Look at the results pane: the lookup name and type of the newly created connection factory are listed.

Adding a Destination Administered Object

Destination administered objects are associated with physical destinations on the broker; they point to those destinations, as it were, allowing clients to look up and find physical destinations, independently of the provider-specific ways in which those destinations are named and configured.

When a JMS client sends a message, it looks up (or instantiates) a destination administered object and references it in the send() method of the JMS API. The broker is then responsible for delivering the message to the physical destination that is associated with that administered object:

• If you have created a physical destination that is associated with that administered object, the broker delivers the message to that physical destination.
• If you have not created a physical destination and the autocreation of physical destinations is enabled, the broker itself creates the physical destination and delivers the message to that destination.
• If you have not created a physical destination and the autocreation of physical destinations is disabled, the broker cannot create a physical destination and cannot deliver the message.

In the next part of the tutorial, you will be adding an administered object that corresponds to the physical destination you added earlier.

To add a destination to an object store

1. Right-click on the Destinations node in the navigation pane.
2. Choose Add Destination Object.

The Administration Console displays an Add Destination Object dialog that you use to specify information about the object.





3. Enter "MyQueue" in the Lookup Name field.

The lookup name is used to find the object using JNDI lookup calls. In the sample application, the call is the following:

queue=(javax.jms.Queue)ctx.lookup("MyQueue");

4. Select the Queue radio button for the Destination Type.
5. Enter MyQueueDest in the Destination Name field.

This is the name you specified when you added a physical destination on the broker.

6. Click OK.
7. Select Destinations in the navigation pane and notice how information about the queue destination administered object you have just added is displayed in the results pane.

Administered Object Properties

To view or update the properties of an administered object, you need to select Destinations or Connection Factories in the navigation pane, select a specific object in the results pane, and choose Actions > Properties.

To view or update the properties of a destination object

1. Select Destinations in the navigation pane.
2. Select MyQueue in the results pane.
3. Choose Actions > Properties to view the Destination Object Properties dialog.

Note that the only value you can change is the destination name and the description. To change the lookup name, you would have to delete the object and then add a new queue administered object with the desired lookup name.

Updating Console Information

---

Whether you work with object stores or brokers, you can update the visual display of any element or groups of elements by choosing View > Refresh.

Running the Sample Application

---

The sample application SimpleJNDIClient is provided for use with this tutorial. It uses the administered objects and destination that you created in the foregoing tutorial: a queue destination named MyQueueDest, a queue connection factory administered object named MyQueueConnectionFactory and a queue administered object named MyQueue.

The code creates a simple queue sender and receiver, and sends and receives a "Hello World" message.

To run the SimpleJNDIClient application

1. Make sure the JAVA_HOME environment variable points to the directory where the JDK is installed.
2. Make the directory that includes the SimpleJNDIClient application your current directory; for example:

cd IMQ_HOME/demo/jms (/usr/demo/imq/jms on Solaris)

You should find the SimpleJNDIClient.class file present. (If you make changes to the application, you will need to re-compile it using the instructions for compiling a client application in the Quick Start Tutorial of the MQ Developer's Guide.)

3. Set the CLASSPATH variable to include the current directory containing SimpleJNDIClient.java as well as the following jar files: jms.jar, imq.jar, and fscontext.jar.
4. Before you run the application, open the source file, SimpleJNDIClient.java, and read through the source.

It is short, but it is amply documented and it should be fairly clear how it uses the administered objects and destinations you have created using the tutorial.

5. Run the SimpleJNDIClient application.

C:> java SimpleJNDIClient (Windows)

% java SimpleJNDIClient file:///tmp (on Solaris and Linux)

If the application runs successfully, you should see the following output:

---

================================================== $JAVA SimpleJDNIClient file:///tmp Usage: java SimpleJDNIClinet [Context.PROVIDER_URL] On Unix:         java SimpleJDNIClient file:///tmp On Windows:         java SimpleJDNIClient file:///C:Temp Using Windows default file:///C/Temp for Context.PROVIDER_URL Publishing a message to Queue: MyQueueDest Received the following message: Hello World. ==================================================

---