|
| |
| Sun Java System Message Queue 3 2005Q1 Administration Guide | |
Chapter 2
Administration Quick StartThis quick start focuses on basic administration tasks, using the Administration Console, a graphical interface for administering a Message Queue broker and object store. By following the instructions in this chapter, you will learn how to do the following:
The quick start sets up the physical destinations and administered objects needed to run a simple JMS-compliant application, HelloWorldMessageJNDI. The application is available in the helloworld subdirectory of the example applications directory (demo on the Solaris and Windows platforms or examples on Linux; see Appendix A, "Operating System-Specific Locations of Message Queue Data"). In the last part of the quick start, you run this application.
This quick start is provided mainly to guide you through performing basic administration tasks using the Administration Console. It is not a substitute for reading and referring to the documentation.
Some Message Queue administration tasks cannot be accomplished using the Administration Console. You must use command line utilities to perform such tasks as the following:
For more information on how to accomplish these tasks, see Chapter 6, "Managing Physical Destinations,"Chapter 9, "Working With Broker Clusters," and Chapter 7, "Managing Security."
Getting ReadyBefore you can start, you must install the Message Queue product. For more information, see the Message Queue Installation Guide. Note that this chapter is Windows-centric, with added notes for UNIX® users.
In this chapter, 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 ConsoleTo start the Administration Console, use one of the following methods:
You may need to wait a few seconds before the Console window is displayed.
Take a few seconds to examine the Console window.
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.
This chapter cannot 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
- Pull down the Help menu and choose Overview. A help window is displayed.
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.
- 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.
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.
- Click the Add Broker item in the Help window’s navigational pane.
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.
- Read through the help text.
- Close the Help window.
Starting a BrokerYou cannot start a broker using the Administration Console. Instead, use one of the following methods:
If you used the Windows Start menu, the command window appears. The command response appears, and indicates that the broker is ready by displaying lines like the following:
Loading persistent data...
Broker “imqbroker@stan:7676 ready.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 BrokerAdding 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
- Right-click on Brokers in the navigation pane and choose Add Broker.
- 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 box. These are the values you must 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.
- 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.
- Right-click on MyBroker and choose Properties from the popup menu.
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.
- Click Cancel to dismiss the dialog box.
Connecting to the BrokerTo Connect to the Broker
- Right-click MyBroker and choose Connect to Broker.
A dialog box appears and requests a user name and password.
By default, the Administration Console can connect to a broker as user admin with password admin. For this exercise, you use the default value. In a real-world environment, you should establish secure user names and passwords as soon as you can. See Authenticating Users for more information.
- Enter admin in the Password field.
Specifying the user name admin and supplying the correct password connects you to the broker, with administrative privileges.
- 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
- 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.
- Select the jms service by clicking on it in the results pane.
- 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.
- Choose Properties from the Actions menu.
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.
- Click OK or Cancel to close the Properties dialog box.
- Select the admin service in the results pane.
- 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.
- Choose Actions > Properties to view the properties of the admin service.
- Click OK or Cancel when you’re done.
Adding Physical Destinations to a Broker
By default, physical destination auto-creation is enabled for a broker. Auto-creation enables a broker to dynamically create physical destinations.
In a development environment, you do not have to explicitly create physical destinations in order to test client code.
In a production setting, it is advisable to explicitly create physical destinations. This allows you, the administrator, to be fully aware of the physical destinations that are in use on the broker.
You will now add a physical destination to the broker. Note the name that 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
- Right-click the Destinations node of MyBroker and choose Add Broker Destination.
The following dialog box is displayed:
- Enter MyQueueDest in the Destination Name field.
- Select the Queue radio button if it is not already selected.
- Click OK to add the physical destination.
The physical destination now appears in the results pane.
Administering 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
- Select the Destinations node of MyBroker.
Two physical destinations appear in the results panel, MyQueueDest and mq.sys.dmq. The mq.sys.dmq destination is a system-created queue that stores expired and rejected messages for the broker. For now, ignore this dead message queue.
- Select MyQueueDest in the results pane.
- Choose Actions > Properties.
The following dialog box is displayed:
Note that the dialog box displays current status information about the queue as well as some properties that you can change.
- Click Cancel to close the dialog box.
To Purge Messages From a Physical Destination
Purging messages removes the messages and leaves an empty destination.
To Delete a Destination
Deleting a physical destination purges the messages at that destination and removes the destination.
Getting Information About Topics
The broker topic destination properties dialog box includes an additional tab that lists information about durable subscriptions. This tab is disabled for queues.
You can use this dialog box to:
Working with Object StoresAn object store is used to store Message Queue administered objects. These administered objects encapsulate Message Queue-specific implementation and configuration information about objects that are used by client applications. An object store can be an LDAP directory server or a file system store (directory in the file system).
Administered objects can be instantiated and configured within client code. However, it is preferable that an administrator create, configure, and store these objects in an object store that client applications can access using JNDI. This allows client code to be provider-independent.
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
- If you do not already have a folder named Temp on your C drive, create it now.
The sample application used in this chapter 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.
- Right-click on Object Stores and choose Add Object Store.
The following dialog box is displayed:
- 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 must enter JNDI name/value pairs. These pairs are used by JMS-compliant applications for looking up administered objects.
- From the Name drop-down list, select 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.
- 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 LDAP Server Object Store.
- Click the Add button.
Notice that the property and its value are now listed in the property summary pane.
- From the Name drop-down list, 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.
- In the Value field, enter the following
file:///C:/Temp
(file:///tmp on Solaris and Linux)
- 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.
- Click OK to add the object store.
- 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 must 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
- Right click on MyObjectStore in the navigational pane.
- Choose Properties from the popup menu.
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.
- 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
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 Developer’s Guide for Java Clients.
To Add a Connection Factory to an Object Store
- If not already connected, connect to MyObjectStore (see Connecting to an Object Store)
- Right click on the Connection Factories node and choose Add Connection Factory Object.
The Add Connection Factory Object dialog box is displayed.
- Enter the name “MyQueueConnectionFactory” in the Lookup Name field.
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”)- Select the QueueConnectionFactory from the pull-down menu to specify the type of the connection factory.
- Click the Connection Handling tab.
- 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:
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 quick start example expects.
- 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.
- Click OK to create the queue connection factory.
- Look at the results pane: the lookup name and type of the newly created connection factory are listed.
Adding a Destination ObjectDestination administered objects are associated with physical destinations on the broker and they point to those destinations. Destination administered objects enable clients to look up and find physical destinations, independently of provider-specific destination names and configurations.
When a client sends a message, it either 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, as follows:
- 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 auto-creation 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 auto-creation of physical destinations is disabled, the broker cannot create a physical destination and cannot deliver the message.
In the next part of the quick start, you will be adding an administered object that corresponds to the physical destination you added earlier.
To Add a Destination to an Object Store
- Right-click on the Destinations node (under the MyObjectStore node) in the navigation pane.
- Choose Add Destination Object.
The Administration Console displays an Add Destination Object dialog box that you use to specify information about the object.
- 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”);
- Select the Queue radio button for the Destination Type.
- Enter MyQueueDest in the Destination Name field.
This is the name you specified when you added a physical destination on the broker (see Adding Physical Destinations to a Broker).
- Click OK.
- 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.
Viewing Administered Object PropertiesTo view or update the properties of an administered object, you 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
- Select the Destinations node of MyObjectStore in the navigational pane.
- Select MyQueue in the results pane.
- Choose Actions > Properties to view the Destination Object Properties dialog box.
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.
- Click Cancel to dismiss the dialog box.
Updating Console InformationWhether 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 ApplicationThe sample application HelloWorldMessageJNDI is provided for use with this quick start. It uses the physical destination and administered objects that you created:
The code creates a simple queue sender and receiver, and sends and receives a “Hello World” message.
To Run the HelloWorldMessageJNDI Application
- Make the directory that includes the HelloWorldmessageJNDI application your current directory; for example:
cd IMQ_HOME\demo\helloworld\helloworldmessagejndi (Windows)
cd /usr/demo/imq/helloworld/helloworldmessagejndi (Solaris)
cd /opt/sun/mq/examples/helloworld/helloworldmessagejndi (Linux)
You should find the HelloWorldMessageJNDI.class file present. (If you make changes to the application, you must re-compile it using the instructions for compiling a client application in the Quick Start Tutorial of the Message Queue Developer’s Guide for C Clients.) 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 Developer’s Guide for Java Clients for instructions on setting the CLASSPATH.
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 Developer’s Guide for Java Clients for additional information)
- 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.
- Run the HelloWorldMessageJNDI application by executing one of the commands below:
java HelloWorldMessageJNDI (Windows)
% java HelloWorldMessageJNDI file:///tmp ( Solaris and Linux)
If the application runs successfully, you should see the following output:
