Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Message Queue 3.5 SP1 Administration Guide 

Chapter 4
Administration Console Tutorial

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

The tutorial is designed to set up the destinations and administered objects needed to run a simple JMS-compliant application, HelloWorldMessageJNDI, which is available in the helloworld subdirectory of the example applications /demo directory (see Appendix A, "Location of Message Queue Data"). 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 Message Queue Java Client Developer’s Guide or other chapters of this Administration Guide.

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


Getting Ready

Before you can start this tutorial you must install the Message Queue product. For more information, see the Message Queue 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:

    To Start the Administration Console
  1. Choose Start > Programs > Sun Java System Message Queue 3.5 SP1 > Administration.
  2. 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:

    /usr/bin/imqadmin (on Solaris)

    /opt/imq/bin/imqadmin (on Linux)

  3. Take a few seconds to examine the Console window.
  4. The Console features a menu bar at the top, a tool bar just underneath the menu bar, a navigational pane to the left, a results pane to the right (now displaying graphics identifying the Sun Java System Message Queue product), and a status pane at the bottom.


    Startup screen for Sun Java System Message Queue. Treeview in left pane; contents in right pane.

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.

  2. Message Queue Administration Console window. Tree view on left: schematic view of display on right.

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

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

  3. Look at the Help window’s navigational 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 dialog boxes containing multiple tabs; each file provides help for a simple dialog box or tab.
  4. 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.

  5. Click the Add Broker item in the Help window’s navigational pane.
  6. Note that the results 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 box. Field names are shown in bold text.

  7. Read through the help text.
  8. Close the Help window.


Working With Brokers

A broker provides delivery services for a Message Queue 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:

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 in the following procedure (also, see Chapter 5, "Starting and Configuring a Broker").

    To Start a Broker
  1. Choose Start > Programs >Sun Java System Message Queue 3.5 SP1 > Message Broker.
  2. Non-Windows: enter the following command to start a broker.

    /usr/bin/imqbrokerd (on Solaris)

    /opt/imq/bin/imqbrokerd (on Linux)

    The command prompt window is displayed and indicates that the broker is ready.


    Message Broker command line interface window.

  3. 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.
  3. This provides a label that identifies the broker in the Administration Console.


    Add Broker dialog. Buttons from left to right: OK, Reset to Defaults, Cancel, Help.

    Note the default host name (localhost) and primary port (7676) specified in the dialog box. 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.

  4. Click OK to add the broker.
  5. 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.


    Message Queue Administration Console window. Broker selected in tree view.

  6. Right-click on MyBroker and choose Properties from the popup menu.
  7. The broker properties dialog box is displayed. You can use this dialog box to update any of the properties you specified when you added the broker.

  8. Click Cancel to dismiss the dialog box.

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. By default, the Administration Console can connect to a broker as user admin with password admin. For improved security, it is 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.
  3. imqusermgr update -u admin -p abracadabra

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

Although clients use a different connection service than administrators, you are also assigned a default user name and password so that you can test Message Queue 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.
  2. A dialog box is displayed that allows you to specify your name and password.


    Connect to Broker dialog. Buttons from left to right: OK, Cancel, Help.

  3. Enter admin in the Password field or whatever value you specified for the password in "Changing the Administrator Password".
  4. Specifying the user name admin and supplying the correct password connects you to the broker, with administrative privileges.

  5. 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.
  2. Available services are listed in the results pane. For each service, its name, port number, and state is provided.


    Message Queue Administration Console window. Broker services node selected. Contents of node displayed in the contents pane.

  3. Select the jms service by clicking on it in the results pane.
  4. Pull down the Actions menu and note the highlighted items.
  5. You have the option of pausing the jms service or of viewing and updating its properties.

  6. Choose Properties from the Actions menu.
  7. Note that by using the Service Properties dialog box, you can assign the service a static port number and you can change the minimum and maximum number of threads allocated for this service.


    Service Properties dialog. Buttons from left to right: OK, Cancel, Help.

  8. Click OK or Cancel to close the Properties dialog box.
  9. Select the admin service in the results pane.
  10. Pull down the Actions menu.
  11. 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.

  12. Choose Actions > Properties to view the properties of the admin service.
  13. Click OK or Cancel when you’re done.

Adding Physical Destinations to a Broker

By default destination auto-creation is enabled for a broker, which allows it to create physical destinations dynamically. Thus, in a development environment, you do not have to explicitly create destinations in order to test client code.

However, in a production setting, it is advisable to explicitly create physical destinations. 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.
  2. The following dialog box is displayed:


    Add Broker Destination Dialog. Buttons from left to right: OK, Reset To Defaults, Cancel, Help.

  3. Enter MyQueueDest in the Destination Name field.
  4. Select the Queue radio button if it is not already selected.
  5. Click OK to add the physical destination.
  6. 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 following procedures:

    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.
  4. The following dialog box is displayed:


    Broker Destinations Properties dialog. Buttons from left to right: OK, Cancel, Help.

    Note that the dialog box displays current status information about the queue as well as some properties that you can change.

  5. Click Cancel to close the dialog box.
    To Purge Messages From a Destination
  1. Select the physical destination in the results pane.
  2. Choose Actions > Purge Messages.
  3. A confirmation dialog box 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.
  3. A confirmation dialog box is displayed.


    Note

    Do not delete the MyQueueDest queue destination.


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

Getting Information About Topic Destinations

The broker topic destination properties dialog box includes an additional tab that lists information about durable subscriptions. This tab is disabled for queue destinations.

Diagram showing how the client runtime supports session queues for consuming clients. Figure explained in text.

You can use this dialog box to:


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 Message Queue administered objects that encapsulate Message Queue-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, as administrator, create and configure these objects and store them in an object store that can be accessed by client applications using JNDI. This allows client code to be provider-independent.

For more information about administered objects, see "Message Queue 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.
  2. 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.

  3. Right-click on Object Stores and choose Add Object Store.
  4. The following dialog box is displayed:


    Add Object Store dialog. Buttons from left to right: Ok, Clear, Cancel, Help.

  5. Enter MyObjectStore in the field named ObjectStoreLabel.
  6. 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.

  7. From the Name drop-down list, select java.naming.factory.initial.
  8. 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.

  9. In the Value field, enter the following
  10. 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 "LDAP Server Object Store".

  11. Click the Add button.
  12. Notice that the property and its value are now listed in the property summary pane.

  13. From the Name drop-down list, choose java.naming.provider.url.
  14. 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.

  15. In the Value field, enter the following
  16. file:///C:/Temp

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

  17. Click the Add button.
  18. 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.

  19. Click OK to add the object store.
  20. If the node MyObjectStore is not selected in the navigation pane, select it now.
  21. The Administration Console now looks like this:


    Message Queue Administration Console window. Object store node selected in tree view pane.

    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.
  3. A dialog box 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.

  4. Click OK or Cancel to dismiss the dialog box.

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.
  3. 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 Message Queue Java Client Developer’s Guide.


Note

The Administration Console lists and displays only Message Queue administered objects. If an object store should contain a non-Message Queue 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.
  3. The Add Connection Factory Object dialog box is displayed.


    Add Connection Factory Object dialog; Connection Handling tab shown. Buttons from left to right: OK, Reset to Defaults, Cancel, Help.

  4. Enter the name “MyQueueConnectionFactory” in the LookupName field.
  5. This is the name that the client code uses when it looks up the connection factory as shown in the following line from HelloWorldMessageJNDI.java:

    qcf=(javax.jms.QueueConnectionFactory)
        ctx.lookup(“MyQueueConnectionFactory”)

  6. Select the QueueConnectionFactory from the pull-down menu to specify the type of the connection factory.
  7. Click the Connection Handling tab.
  8. The Message Server Address List field is where you would normally enter the address of the broker to which the client will connect. An example for this field looks like this:
  9. mq://localhost:7676/jms

    You do not need to enter a value since, by default, the connection factory is configured to connect to a broker running on the localhost on port 7676, which is the configuration that the tutorial example expects.

  10. Click through the tabs for this dialog box 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 box to get information about individual tabs. Do not change any of the default values for now.
  11. Click OK to create the queue connection factory.
  12. 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 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:

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 (under the MyObjectStore node) in the navigation pane.
  2. Choose Add Destination Object.
  3. The Administration Console displays an Add Destination Object dialog box that you use to specify information about the object.


    Add Destination Object dialog. Buttons from left to right: OK, Reset to Defaults, Cancel, Help.

  4. Enter “MyQueue” in the Lookup Name field.
  5. 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”);

  6. Select the Queue radio button for the Destination Type.
  7. Enter MyQueueDest in the Destination Name field.
  8. This is the name you specified when you added a physical destination on the broker (see "Adding Physical Destinations to a Broker").

  9. Click OK.
  10. 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.

  11. Message Queue Administration Console window. Destinations selected in tree view. Destination objects displayed in contents 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 the Destinations node of MyObjectStore in the navigational pane.
  2. Select MyQueue in the results pane.
  3. Choose Actions > Properties to view the Destination Object Properties dialog box.
  4. Note that the only values you can change are 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.

  5. Click Cancel to dismiss the dialog box.

  6. Destination Object Properties dialog. Buttons from left to right: OK, Cancel, Help.


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 HelloWorldMessageJNDI is provided for use with this tutorial (for the location, see Step 1, below). It uses the physical destination and administered objects that you created in the foregoing tutorial: a queue physical destination named   MyQueueDest, a queue connection factory administered object and queue administered object with JNDI lookup names MyQueueConnectionFactory and MyQueue respectively.

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

    To Run the HelloWorldMessageJNDI Application
  1. Make the directory that includes the HelloWorldmessageJNDI application your current directory; for example:
  2. cd IMQ_HOME\demo\helloworld\helloworldmessagejndi (on Windows)

    cd /usr/demo/imq/helloworld/helloworldmessagejndi (on Solaris)

    cd /opt/imq/demo/helloworld/helloworldmessagejndi (on Linux)

    You should find the HelloWorldMessageJNDI.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 Message Queue C Client Developer’s Guide.)

  3. Set the CLASSPATH variable to include the current directory containing the file HelloWorldMessageJNDI.class as well as the following jar files that are included in the Message Queue product: jms.jar, imq.jar, and fscontext.jar. See the Message Queue Java Client Developer’s Guide for instructions on setting the CLASSPATH.
  4. The JNDI jar file (jndi.jar) file is bundled with JDK 1.4. If you are using this JDK, you do not have to add jndi.jar to your CLASSPATH setting. If you are using an earlier version of the JDK, you must include jndi.jar in your CLASSPATH. See the Message Queue Java Client Developer’s Guide for additional information)

  5. Before you run the application, open the source file HelloWorldMessageJNDI.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.
  6. Run the HelloWorldMessageJNDI application by executing one of the commands below:
  7. java HelloWorldMessageJNDI (Windows)

    % java HelloWorldMessageJNDI file:///tmp ( Solaris and Linux)

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

    java HelloWorldMessageJNDI

    Using file:///C:/Temp for Context.PROVIDER_URL

    Looking up Queue Connection Factory object with lookup name: MyQueueConnectionFactory

    Queue Connection Factory object found.

    Looking up Queue object with lookup name: MyQueue

    Queue object found.

    Creating connection to broker.

    Connection to broker created.

    Publishing a message to Queue: MyQueueDest

    Received the following message: Hello World



Previous      Contents      Index      Next     


Copyright 2003 Sun Microsystems, Inc. All rights reserved.