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).
- 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.
- 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
New MBean Wizard - Step #2
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)
The "JUnit Test Generation" checkbox should be moved to the corresponding step (#5)
New
Java Class Wizard - Step #2
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.
MBean
Attributes and Operationds Definition - Step #3
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
- 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.
JUnit
JMX test - Step #5
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".
Agent
Wizard - Step #2
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.
Management Property File Wizard - Step #2
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.