11
Administration GUI

This chapter describes the features of the Oracle Message Broker Manager. The Oracle Message Broker Manager creates and manages configuration information stored in the Oracle Message Broker's LDAP Directory. This chapter covers the following Oracle Message Broker Manager topics:

• Terminology

• Starting Oracle Message Broker Manager

• Connecting to a Directory Server

• Navigating Oracle Message Broker Manager

• Disconnecting from a Directory Server

• Performing Administration Tasks

  Note: Oracle Message Broker Manager allows you to work with configuration information that is stored as directory entries in an LDAP Directory. The directory entries are OMB entries. OMB entries are entries that are created with the Oracle Message Broker administrative tools. An LDAP Directory also contains non-OMB entries. For non-OMB entries, Oracle Message Broker Manager allows you to view and delete the entries, but not to modify the entries.

For a list of the terms used in this chapter, see "Terminology".

Terminology

Throughout this chapter, we use the following terminology:

DN	Refers to an LDAP distinguished name
RDN	Refers to an LDAP relative distinguished name

Starting Oracle Message Broker Manager

The Oracle Message Broker administration command, ombadmin starts the Oracle Message Broker Manager. To start the Oracle Message Broker Manager, follow the instructions for your platform:

Platform	Instructions
Windows NT	You can either: Type at the Run command: ombadmin or Type at a DOS command prompt: ombadmin
Sun Solaris	Type at the system prompt: ombadmin

The executable is in the $OMB_HOME/bin directory (or %OMB_HOME%\bin on Windows NT systems).

Connecting to a Directory Server

When you start Oracle Message Broker Manager, you need to connect to an LDAP Directory server. The LDAP Connection dialog box (Figure 11-1) prompts you for the server name, port number, initial context, authentication DN, and password for the LDAP server. The program supplies default values for these fields using the OMB_LP environment variable. If you want to change the default values, make your selections in the dialog box.

Figure 11-1 LDAP Connection Dialog Box

In each field of the LDAP Connection dialog, type the information specific to the LDAP Directory you want to use.

Field	Description
Server Name	The name of the server running the LDAP Directory that you want to view or modify. The icon to the right of the Server Name field presents the Select Directory Server window that allows you to select a server name and port combination. Using this window, you can also save or edit entries on the list.
Port	The port number for the server running the LDAP Directory.
Initial Context	The initial context for the Oracle Message Broker configuration entries stored in the LDAP Directory. This is the DN of the LDAP entry that serves as the base entry. Leave this field blank to connect to the root context of the directory. The icon to the right of the Initial Context field presents the Quick List containing saved DNs that can be selected for the Initial Context field. Using this window, you can also save or edit Quick List entries
Authentication DN	The DN of a user entry for LDAP Directory authentication. For information on LDAP authentication and recommended security roles, see "LDAP Server Security".
Password	The password for the user associated with the specified Authentication DN. For information on LDAP authentication and recommended security roles, see "LDAP Server Security".

When you select the Connect button, a connection to the specified LDAP Directory is created. If you select the Cancel button, the Oracle Message Broker Manager screen comes up and a connection is not attempted. From the Manager screen, you can connect and disconnect to LDAP servers, view entries, create new entries, delete entries, and modify entries.

Figure 11-2 shows the Oracle Message Broker Manager opening window.

Figure 11-2 Oracle Message Broker Manager Opening Window

Navigating Oracle Message Broker Manager

The Oracle Message Broker Manager window serves as the main window for the application. From this window, menu options and toolbar buttons allow you to perform tasks such as:

• Connecting to a directory server

• Viewing Oracle Message Broker entries

• Creating and Modifying Oracle Message Broker entries

• Deleting Oracle Message Broker entries

The Navigator pane (left side of the double window interface) contains a tree structure to browse entries that are relative to the initial context of the current server connection. Entries above the initial context are not accessible. To change the initial context or the server, you need to disconnect and then connect.

When Oracle Message Broker Manager first opens, the Navigator pane shows only one tree item, "<Initial Context>." By clicking the plus sign(+) next to the tree item, subcomponents of that tree item appear. Tree items that have plus signs in front of them may have their own sub-tree items. The plus sign becomes a minus sign (-) when the entry is expanded. You can expand and contract the tree by clicking the plus signs and minus signs.

For example, if you click the plus sign next to <Initial Context> in the opening window Navigator pane, the tree expands to show the top level entries in the initial context to which you are connected, as shown in Figure 11-2.

You can navigate around Oracle Message Broker Manager using one or a combination of the following options.

• Select menu items from the menus across the top of the window.

• Use buttons on the toolbar across the top of the left pane to perform such actions as create, create-like, and delete.

• Click the tree items in the Navigator pane. For example, as shown in Figure 11-3, clicking the Navigator tree item testomb causes the tree item to be highlighted and the entry's attributes to be displayed in the right panel. The attributes shown can be modified by selecting Show Assigned Attributes Only from the Prefs menu.

Attribute names in Oracle Message Broker Manager are shown in a bold, normal, or grayed out font.

• Bold names indicate mandatory attributes, where a value is required when the attribute is created (see cn in Figure 11-3).

• Names using a regular font indicate optional attributes (these can be modified after creation).

• Grayed out names indicate read only attributes that cannot be changed using the Oracle Message Broker Manager.

  Figure 11-3 Manager Entry View

  
  

Oracle Message Broker Manager Menu Bar

Table 11-1 lists the menus you can access by using the menu bar, and describes the items in each menu. Menu items may become enabled or disabled depending on the item you are displaying in Oracle Message Broker Manager.

Note: Many menu options are disabled if a server connection is not currently established.

Table 11-1  Menu Bar Items

Menu	Menu Items
File	Create - Adds an entry. Dialogs guide you through the creation process. Create Like - Adds a new entry by using the entry selected in the Navigator pane as a template. Connect - Establishes a new server connection. Once a connection is established you must disconnect before connecting to another server. Disconnect - Disconnects the current server connection. Exit - Exits Oracle Message Broker Manager.
Edit	Modify - Displays a dialog which allows you to modify the attributes for the currently selected entry. This option only allows Oracle Message Broker entries to be modified. Delete - Deletes the currently selected entry. Quick List - Save information displayed by the Oracle Message Broker Manager in a quick list that is saved between invocations of the Manager. Refresh - Refreshes the information displayed in the Manager window.
Prefs	Show Assigned Attributes Only - This checkbox, when selected, tells the Oracle Message Broker Manager to only display attributes that currently have an assigned value. When not selected, all attributes are displayed. Confirm Delete - This checkbox, when selected, enables the confirmation dialog when entries are deleted. When this is not selected, there is no confirmation for deletes. The default value is to confirm for deletes.
Tools	Provides options to run the available OMB Wizards that create entries using a series of dialogs. For more information, see "Using the Configuration Wizards to Add Entries".
Help	Contents - Displays the Contents tab page of the Help Navigator. Hide - Hides the help window, if it is currently displayed. Index - Displays the help index. Search for Help On...- Displays the Help Search dialog box which you use to search for words in the online help guide. About - Displays Oracle Message Broker Manager version information.

Oracle Message Broker Manager Toolbar

Figure 11-4 and the accompanying table illustrate and describe the Oracle Message Broker Manager toolbar. Buttons become enabled or disabled depending on the item you are displaying in the Oracle Message Broker Manager and the current state, connected or disconnected.

Figure 11-4 Oracle Message Broker Manager Toolbar

Button	Purpose
1	Connect/Disconnect - Connects or disconnects to or from a directory server.
2	Refresh - Updates data for objects stored in memory to reflect changes in the directory.
3	Create - Adds a new entry
4	Create Like - Adds a new entry by using another entry as a template
5	Modify - Modifies an entry
6	Delete - Deletes an entry. This can also delete subentries when an entry contains subentries
7	Help - Displays the Help Navigator

Disconnecting from a Directory Server

To disconnect from a directory server using Oracle Message Broker Manager, go to the File menu and select Disconnect or select the disconnect icon in the toolbar. Also, when you exit Oracle Message Broker Manager, the connection is closed.

Performing Administration Tasks

This section gives step-by-step instructions for several common Oracle Message Broker Manager tasks, including:

• Viewing Entries

• Adding Entries

• Deleting Entries

• Modifying Entries

• Using the Configuration Wizards to Add Entries

Viewing Entries

In the Navigator pane, expand the <Initial Context> to show the top level entries in the directory. The initial context, (top) of the tree is listed first, and then the second level and so forth, moving from left to right. The subtree lists the RDN of each entry in hierarchical order. To see the lower level entries within any subtree, click the plus (+) sign to the left of the parent entry. Once you are at the entry you want to view, select the entry to view its attributes.

The right panel displays the attributes for a selected entry. This panel can show all available attributes, or only the attributes which have an assigned value (to change this option, use the Prefs menu item, "Show Assigned Attributes Only").

Attribute names in Oracle Message Broker Manager are shown in a bold, normal, or grayed out font. Bold names indicate mandatory attributes, where a value is required. Names using a regular font indicate optional attributes. Grayed out names indicate read only attributes that cannot be changed using the Oracle Message Broker Manager.

Adding Entries

You can use Oracle Message Broker Manager to add entries as described in the following sections:

• Adding A New Entry

• Adding an Entry by Copying an Existing Entry

Adding A New Entry

To add entries with Oracle Message Broker Manager, you must have an active connection to a directory server.

To add a new entry:

1. Either click the Create button on the toolbar or select Create from the File menu. The New Entry dialog box appears (Figure 11-5).

   Figure 11-5 Adding a New Entry

   
   
2. Select the desired type from the Type list.

3. Select the parent for the new entry from the Parent list. The Parent list contains all valid parents within the initial context that may contain the type of entry you are adding. This list shows <Initial Context> if the only available parent is the entry corresponding to the initial context. This list shows nothing if no entries currently exist that can serve as a parent for the selected entry type. The parent entry must be created before a child entry.

4. Enter the name for the entry you are adding in the Name field and press OK. The name for some entry types is fixed. For entries with fixed names, you cannot modify the Name field and the field is grayed out.

5. After you press OK in the New Entry dialog, the New Entry Attributes dialog appears (see Figure 11-6). This dialog allows you to view all the attributes for the new entry, and to supply values for attributes that can be modified.

6. Using the New Entry Attributes dialog, enter the desired attribute values and press OK to add the entry, or Cancel to cancel the operation.

   Figure 11-6 Setting New Entry Attributes

   
   

The left panel in Figure 11-6 shows the attributes and provides fields to enter values or menus containing values for each attribute.

The right panel shows the meta data for the attribute with the current focus. Moving the mouse over an attribute in the left panel changes the focus to that attribute. Meta data lists information such as limits for the data allowed for an attribute, whether a default value is available, and other attribute information.

Notes for Adding a New Entry

1. There is a fixed hierarchy that governs the parent and child relationship between OMB entry types. The Parent list presented in the New Entry dialog box contains only the entries that can serve as the parent of the entry type that is being added (see Figure 11-5). If the parent does not exist, it must be created prior to creating an entry. For example, a queue_container entry must exist before a queue entry can be created.

2. The omb_instance type corresponds to the cn=OMB entry. This entry is created by the Install process, along with the other entries making up the cn=OMB, cn=Products, cn=OracleContext DN. The omb_instance_container type is the topmost entry that can be created using Oracle Message Broker Manager.

3. An attribute of type Distinguished Name requires a string with an LDAP distinguished name syntax. Specify the full DN for such an attribute; a DN relative to the initial context is not sufficient. For example, a topic or queue entry has a server_dn attribute of type Distinguished Name, which must be the full DN of an existing msg_broker, aq_server, aqlite_server, mq_server, rv_server, or mcast_server entry. Obtain the full DN for an entry from the Oracle Message Broker Manager window which displays the currently selected entry's DN in a text field along the top of the window.

Adding an Entry by Copying an Existing Entry

You can use Oracle Message Broker Manager to create a new entry by copying from an existing entry. When you copy from an existing entry, you need to select the entry that you want to use as the template for the new entry, and you need to select the name and the parent for the new entry.

To add an entry by copying an existing entry:

1. In the Navigator pane, expand the <Initial Context>. Once you have reached the entry that you want to copy, select the entry.

2. Either click the Create Like button on the toolbar or select Create Like from the File menu. The New Entry dialog box appears (see Figure 11-7). Modify the attributes that you want to change in the new entry.

3. The value in the Type field matches the type of the item you selected. Select the parent for the new entry from the available choices in the Parent list.

4. Finally, type the name for the entry you want to add and press OK.

   Figure 11-7 New Entry Dialog Box

   
   
5. After you press OK in the New Entry dialog, the New Entry Attributes dialog appears (see Figure 11-6). All the values from the selected entry are copied in their respective fields to the new entry. Change the fields you need to tailor your new entry.

   Keep the following in mind when editing the attributes for the new entry:

   • Carefully look over the new attributes in the New Entry Attributes dialog. If any entries are not correct for the new entry, change them. In particular, if you are using create like with different OMB Instances as parents, make sure that the new entry uses DNs that point to entries within its OMB Instance, and not to DNs that point to entries within the parent of the selected entry.

   • If you are using create like to add a new queue or a topic, make sure that the DN specified for the server_dn attribute that the queue or topic points to in the copied entry exists within its parent's OMB Instance.

   • If you are using create like to add a new queue or topic, make sure that the value of provider_queue_name attribute is correct. If the value for this attribute is not correct, results are unpredictable.

6. Finally, press OK to add the entry, or Cancel to cancel the operation.

Deleting Entries

You can use Oracle Message Broker Manager to delete directory entries. You can delete OMB entries, which are entries created with the Oracle Message Broker administrative tools. You can also delete non-OMB entries. The confirm delete preference is available for deleting entries. When selected, this preference enables the confirmation dialog for each delete operation. When Confirm Delete is not selected, there is no confirmation for delete operations.

Warning: Deleting entries removes the entries from the directory. When you delete entries, be certain that you are not selecting entries that you, or other users need. It may be very difficult to recover deleted entries.

To delete an entry:

1. In the Navigator pane, expand the Initial Context to show entries in the directory. Select the entry that you want to delete.

2. Either click the Delete button on the toolbar or select Delete from the Edit menu.

3. Delete presents a confirmation dialog. Press Yes to delete the entry, or No to cancel the operation.

Modifying Entries

You can use Oracle Message Broker Manager to modify the attributes of an existing entry. Non-OMB entries cannot be modified using Oracle Message Broker Manager. If you need to modify a non-OMB entry, you need to use another tool, for example oidadmin, or ldapmodify.

Note: Always use Oracle Message Broker administration tools to create, modify, and delete OMB entries. Do not use other tools, such as oidadmin or ldapmodify to create, modify, or delete OMB entries.

To modify an entry:

1. In the Navigator pane, expand the <Initial Context> to show entries in the directory. Once you have reached the entry that you want to modify, select the entry.

2. Either click the Modify button on the toolbar or select Modify from the Edit menu. The Edit Entry Attributes dialog appears. The Edit Entry Attributes dialog looks and behaves similar to the New Entry Attributes dialog (see Figure 11-6).

3. Edit the attribute values that you want to modify, and press OK to modify the entry or Cancel to cancel the operation.

Using the Configuration Wizards to Add Entries

You can use Oracle Message Broker Manager to create entries and subentries by selecting a configuration wizard from the Tools menu. The tools menu provides the following wizards:

• OMB Instance Configuration Wizard - this wizard helps you configure an OMB Instance. An OMB Instance contains all of the directory entries required to run the Oracle Message Broker.

• Queue Wizard - this wizard helps you create one or more queues.

• Topic Wizard - this wizard helps you create one or more topics.

• Propagation Configuration Wizard - this wizard helps you to configure the entries required to setup the Oracle Message Broker for propagation.

• Propagation Job Wizard - this wizard helps you create and configure propagation jobs.

To run a wizard, do the following:

1. Select, the desired wizard from the Tools menu. For example, if you select the OMB Instance Configuration Wizard, this wizard appears (see Figure 11-8).

2. Follow the instructions provided with the wizard to create and configure the entries associated with the wizard.

   Figure 11-8 New OMB Instance Wizard Dialog