JMX Support UI Specification Review

Author: Jiri Kopsa
$Revision: 1.3 $ $Date: 2005/03/14 09:03:22 $

This is a review of the JMX Support UI specification, which can be found at:

http://j2se.sfbay.sun.com/web/bin/view/JMX/JMXNetBeans

Table of Contents

    Functional Specification and Use Cases

    UI Specification Review Findings

       Workflow: "One-way" Managed Bean Development
       Workflow: Generated Code
       Workflow: Manager Development
       Workflow: Runtime Support, Launching JConsole, Configuration Management
       Style: MBean Wizard
       Style: Agent Wizard
       Style: Management Property File Wizard
       Style: Options

    Conclusion

Functional Specification and Use Cases

This paragraph outlines the JMX API and functionality provided by the JMX Support module.

The JMX API brings standardisation to management and monitoring of components. The API provides the infrastructure and interfaces. Simply said: a managed resource (Managed Bean - MBean), which implements a certain interface of the JMX API, is instantiated and registered in a MBean server by an agent. The manager (a "client" application) can then lookup the registered resources and call certain methods on them (remotely), thus manage and monitor them.

From the development point of view, there are several use cases:

UC1: Create a Managed Bean

UC2: Create an Agent

UC3: Create a Manager

A Manager can be represented by a Sun or 3rd party provided Management Console. There comes a JConsole application with the JDK 1.5, which can be used for monitoring purposes. Thus the other use case is:

UC4: Use JConsole to monitor and manage resources of an application being developed and runned (debugged) from NetBeans IDE

UC5: Use JConsole to monitor and manage resources of an application being runned in a remote JVM

The JVM of the J2SE 1.5 is itself a "managed resource", so the following use cases are relevant as well:

UC6: Monitor and manage a JVM that runs an application being developed in the NetBeans IDE

UC7: Monitor and manage a remote JVM

We are refering to these use cases in the following text.

UI Specification Review Findings

We have evaluated the UI specification in regards to the Tools User Interface Styleguide, Java Look and Feel Design Guidelines and to the common NetBeans workflow practices. The findings cover two areas: Workflow and Style. Their severity is marked with the priority P1 (most important) to P4.

Workflow: "One-way" Managed Bean Development

The module provides the New JMX Bean wizard to fulfill the use case UC1. It creates two files - an interface and an implementation class. In the step #2, the user is supposed to add attributes and operations. The attributes are simple JavaBean properties (i.e. fields with getters and setters) exposed in the interface; the operations are simple methods exposed in interface. In the step #3, the user can add notifications - a call back messages being sent to the manager.

Once the wizard is finished the interface and implementation class are generated and the relevant code is added; however new attributes and operations has to be added by hand (i.e. for adding an attribute, the user needs to add the field, getter and setter and expose it in the interface). A better approach is to use the "Add / Property" action from the "Bean Patterns" context menu, however the methods still need to be exposed in the interface by hand.

This is very close to the functionality of Enterprise JavaBean development (see UI spec). Every EJB is represented by an implementation class and a set of interfaces. We provide a functionality as "Add Business Method" that adds a method to all relevant files.

P2: Provide functionality similar to the EJB or JavaBeans development

It would be optimal to provide such functionality also for Managed Beans. A good approach might be extending the context menus of a Java class nodes in case it implements the MBean interface (or extends relevant class). Then the wizard wouldn't need to contain steps #2 and #3 and would become consistent with the New EJB Wizards and New JavaBean wizard. Part of this effort would also be decoupling the JUnit tests generation (which could be then omitted from the wizard).

Workflow: Generated Code

P2: Minor changes to the generated code might improve its usability

1. The wording of the genereated javadoc of an Agent class might be rather:
"You may use the New JMX Bean wizard to create a Managed Bean."

2. There is probably an error in the init method of the Agent class (inaccessible agent variable).

3. The purpose of the CacheManagerDynamicSupport should be clearly stated in the javadoc.

4. The editor folds could be used to shield the user from "plumbing" methods. This is allready used in other class templates (Servlet, EJB), e.g. the EJB implementation class contains:

// <editor-fold defaultstate="collapsed" desc="EJB infrastructure methods. Click the + sign on the left to edit the code.">
...
// </editor-fold>

Workflow: Manager Development

The use case UC3 is not supported by any functionality.

P3: Provide a wizard or functionality for the manager development

The learning curve might be improved if the module had provided a functionality to "call" the Managed Bean (i.e. instantiating JMXServiceURL and connecting to the bean). See "Source Editor: Call Enterprise Bean" action of the EJB UI spec.

Workflow: Runtime Support, Launching JConsole, Configuration Management

The JMX support module provides an UI that should fulfill the use cases UC4 - UC5. It is represented by:

• Options panel: "Options / ... / Management / JConsole"
  
• Options panel: "Options / ... / Management / Runtime settings"
• Menu item: "Tools / Management / JConsole"
• Menu item: "Management / Run Main Project with Local Management"
• Menu item: "Management / Run Main Project with Remote Management"
• New File Wizard: "Management / Management Properties File"
  

P1: The UI is confusing and not well designed; it should be more focused on use cases rather then on features and parameters of JVM and JConsole

The findings can be summarized in following points:

• Adding a top level menu is not necessary (only two actions).
• The user might want to debug the application with the JConsole running (not supported by current design).
• The "Management Properties File" creates a property file in its default location "JRE_HOME/lib/management/management.properties" (Question: it this true?), which is not a correct behaviour for a "New File" wizard
  

• This feature is probably aimed in the support of multiple configuration. Such functionality should be rather smoothly integrated within the NetBeans UI. (A Wizard and an option panel is not a good solution).

Here are several hints that might be used in the design enhancement:

• Replace the "Management / Run ..." actions with new items in the Run menu: "Run Main Project with JConsole" and optionally "Debug Main Project with JConsole".
• Add a panel with monitoring options to the Project Properties dialog
• Introduce a new action: "Run / Attach JConsole" (with an option to start a JConsole without attaching).
  (and remove "Tools / Management / JConsole" action)
  
• Replace the "Management Properties File" with a configuration management (within the Project Properties dialog or Options)
• OR update the wizard in a way, that the properties file can be stored within the project (and referenced for example from the Project Properties dialog)
• Replace the "Options / Runtime settings/ Connect JConsole" with an action or move it to the Project Properties dialog (to be used in a similar way as "Display Browser on Run" of a web application Project Properties dialog - see Web Application UI spec)
• Replace the "Options / Runtime settings / Management properties" item with a more flexible widget (related to the project, if the Management Properties File are created within project) or replace it with a configuration management UI - thus omit the configuration files completely
• "Options / Runtime settings / RMI port" - could be also moved to the project related property (to be aligned with the rest). This value could be probably shared with the potential "Management Properties / RMI port" item (currently located in a properties file)
  
• "Options / JConsole settings / Classpath" should be probably also moved to a project related item (and project classpath might be automatically added - Question: or how exactly is this working/intented?)
• "Options / JConsole settings / Default URL" could be removed with a "Attach JConsole" dialog text field
• RMI and SNMP Port text fields of the Management Property file wizard (or its replacement) should have default values.
  

There are also some items which are not specified in the UI spec and their behaviour could not be tested on current implementation. Their purpose and behaviour needs to be specified.

• The "Edit" button next to the "Authenticate" checkbox.
• The "Edit" button next to the "Other properties" checkbox.

Note: If none of these solutions is fulfilled, the "Management" main menu item should be at least changed to a verb as this is a guideline.

Style: MBean Wizard

P1: The layout and usage of UI widgets does not comply with the guidelines

Step #2 - MBean Definition


There are following issues/suggestions:

• The name of the step should be changed to "Name, Location and Type" to be consistent with other wizards.
  
• The panel should not have any border.
• The wizard should not resize itself, if the components don't fit on one page, they should be breaken into several pages.
• The top label "Specify a name and optionally ..." should be removed.
  
• The MBean Definition TitledBorder should be removed
  
• The layout of top components should correspond to their counterpart of New Java Class Wizard

• Starting on the top of the panel
  

• The order should be: Name, Project, Location, Package, Description
• Location should be changed to a combobox with source folders
• Description field should have a border
• The labels should be appended with colons (this applies to other steps and wizards as well)
  

Help Button should be disabled if none help is provided (this applies to all steps)

The MBean options should be removed since they are redundant with next steps. If the user does not want to create any attributes or operations, he simply does not fill the next steps.
The "JUnit Test Generation" checkbox should be moved to the corresponding step (#5)

The MBeanType TitledBorder should be replaced with a label "Specify the MBean Type:", which should be separated from top components with a separator (see New Java Class Wizard).

The Finish button should be enabled.

Step #3 - MBean Attributes and Operations Definition

• The name of the step should be changed to "Specify Attributes and Operations"
• The label of the attribute name column should be "Attribute Name".
• The "Add" and "Remove" buttons should be aligned to left.
• The tables should fill the remaining space.
• The default value should be simple without brackets.
• The name of the "Read/Write" access should be changed to "Read / Write" (including extra spaces).
• The behaviour of the "..." needs to be specified.
  

Step #4 - MBean Notification Definition

• The name of the step should be changed to "Add Notifications".
• The table has same issues as the tables in Step #3
  

Step #5 - JUnit Test Definition

• The panel should have any border.
  
• The name of the step should be changed to "Specify JUnit Test"
• The label "Junit JMX test" and separator should be removed.
• The layout of the top components should correspond with New Java Class Wizard (incl. behaviour of the Location component)
  
• The top components should be preceded with a check box "Create a JUnit Test" (which would disable all the remaining components if unchecked).
• The label "Class test" should be changed to "Class Name:".
• The label "Package name" should be changed to "Package:".
• The panel that contains checkboxes should not have any border and should be separated from the top components with a separator.

Step #6 - Summary

Current practice in NetBeans design is not including a summary step if the steps are not very complex. This rule can be also applied to this wizard, thus the Step #6 should be removed.

Style: Agent Wizard

P1: The layout and usage of UI widgets does not comply with the guidelines

Step #2 - Agent Class Definition

• The name of the step should be changed to "Name and Location" to be consistent with other wizards.
• The panel should have any border.
• The top label "Specify a name and optionally ..." should be removed.
• The TitledBorder "Agent Defintion" should be removed.
• The layout of the top components should correspond to the New Java Class wizard (see Style: MBean Wizard).
• The Agent Options TitledBorder should be removed.
• The two checkboxes should be separated from the top components with a separator.
  
• The "Main Method Generation" should be replaced with "Create Main Method"
• "The "MBean Registration ..." should be replaced with "Add Managed Bean Registration Sample Code".
  

Style: Management Property File Wizard

P1: The layout and usage of UI widgets does not comply with the guidelines

Step #2 - Management Property File Wizard

• The name of the step should be changed to "Specify Management Properties"
• The panel should not have a border.
• The "RMI" and "SNMP" labels should be changed to "Use RMI" or better/more descriptive label.
• The size of buttons should be equal to the buttons of the bottom pane.
• The wizard should not resize itself.

Style: Options

P1: The labels of the options categories and options items should be correctly capitalised.

Conclusion

We have conducted a review of a UI specification. Except several minor issues (P2, P3), there are crucial (P1) issues in the use of widgets, layout and style. Morover the UI supporting use cases UC4 to UC7 is confusing and probably should be redesigned.