VisualVM Beta 2: Reorganization of APIs
First of all, let's look through the source structure. When you go to visualvm.dev.java.net and download the ZIP file you find there, the sources you will end up with are shown below:
A brief overview of everything you see there:
- plugins. The sources of the plugins that are available for VisualVM.
- btrace: Sources for the btrace plugin for VisualVM.
- consumerentrypoints: Sources for an experimental plugin providing "entry points" into VisualVM (come to JavaOne, where a BOF will be presented on this topic).
- consumervisualvm: Sources for an experimental plugin providing an API for creating entry points in VisualVM.
- glassfish: Sources for the plugin that enables VisualVM to monitor, manage, and troubleshoot applications deployed to GlassFish.
- jconsole: Sources for the plugin that enables JConsole plugins to be plugged into VisualVM.
- mbeans: Sources for "mbeans" tab plugin, familiar to those who know JConsole, which provides the same tab.
- nbproject: NetBeans project folder containing meta data that enables the whole "plugins" folder to be opened as a module suite in NetBeans IDE.
- samples. Two samples that can be opened in NetBeans IDE and inspected,as shown below:
The first, "hellovvm", provides a new "Hello World" view for VisualVM applications:
The second, "jvmcap", adds a new subtab in each application's "Overview" tab, listing details provided by the JVM for the application in question (below, the new subtab is in the lower right of the screenshot):
- visualvm.The sources of VisualVM, consisting of the VisualVM APIs and their implementations. The main ones are as follows:
- application, applicationviews, appui: API and implementation of "Application" data source.
- core. The infrastructure of VisualVM, which you could potentially reuse as the basis of your own application on top of VisualVM.
- coredump. API and implementation of "CoreDump" data source.
- heapdump. API and implementation of "HeapDump" data source.
- host, hostviews. API and implementation of "Host" data source.
- jmx, jvm, jvmstat. APIs for interacting with these technologies.
- profiler. API and implementation of "Profiler" functionality.
- threaddump. API and implementation of "ThreadDump" data source.
The VisualVM Javadoc, which you can also download from the visualvm.dev.java.net site, reflects a similar structure:
Especially if you are migrating plugins you created using the earlier version of the APIs, you are highly recommended to read the above Javadoc:
VisualVM Beta 2 API Changes
Now that you have a basic overview of what the ZIP file consists of, let's look at the most important API changes between VisualVM Beta and VisualVM Beta 2.
- Repackaging. Previously, APIs for the various data sources were within the "core" package; now, they have been split into a subpackage per data source. For example, do you want to create a new view for applications? You will need the "application" package. Want to create a new view for heap dumps? You will need the "heapdump" package, and so on.
- Overview Tab Can Be Saved. This makes it possible to compare overview tabs at different points of the application. In accordance with this enhancement, there are two new methods on DataSourceViewProvider, "supportsSaveViewsFor" (which returns a boolean) and "saveViews" (which can do something when the former method is set to true).
- Signature Changes. Instead of implementing DataSourceViewsProvider, you now need to extend DataSourceViewProvider. (Note the singular instead of the plural in the name of the view provider.)
- Constructor Changes. For DataSourceViews, the call to the superclass now begins with the application instance and ends with a boolean signifiying whether the view should be saved or not. Therefore, there are two new arguments for the superclass.
- Class Renaming. There have been several tweaks and renamings that make the Beta 2 version of the APIs incompatible with the Beta version, such as these:
- DataSourceWindowFactory >>> DataSourceViewsManager
- DataSourceViewsProvider >>> DataSourceViewProvider
- Method Renaming. Similarly, some methods have been renamed, such as the following:
- DataSourceViewsProvider.getViews >>> DataSourceViewProvider.createView
- DataSourceViewsProvider.supportsViewsFor >>> DataSourceViewProvider.supportsViewFor
- DataSourceView.getView >>> DataSourceView.createComponent
As can be seen, the above summary applies mainly to views. Similar changes are found throughout the APIs. In summary, the APIs that relate to VisualVM are now as follows:
Layer Registration for Explorer Actions
Another change is that actions on the explorer nodes now need to be registered in the layer.xml file. For an example, look at the "btrace" plugin sources, which has a layer.xml file with the following content:
<attr name="originalFile" stringvalue="Actions/Other/net-java-visualvm-btrace-actions-DeployBTraceScriptAction.instance"/>
<attr name="position" intvalue="3000"/>
<attr name="originalFile" stringvalue="Actions/Other/net-java-visualvm-btrace-actions-UndeployBTraceScriptAction.instance"/>
<attr name="position" intvalue="3500"/>
Templates for Getting Started
To help you get started, in addition to the two samples pointed out above, there are two templates that should get you set up, using the VisualVM Beta 2 APIs:
- VisualVM View Template:
- VisualVM Application Type Template:
These templates have been tried out on NetBeans IDE 6.1 Beta. They could/should work in other IDE versions after that, but no guarantees. When you install the first plugin, you will have a new wizard in NetBeans IDE for creating a new view. On completion of the wizard, all the correct dependencies will be set and you will have useful stubs for beginning with views. The second plugin is interesting if you have an application which you'd like to be represented in VisualVM with its own icon, menu items, views, etc. It lets you specify the main class of your application and then it generates the basic stubs of an application plugin for VisualVM. As with the first plugin, it declares all the necessary dependencies for you.
Related JavaLobby Resources
The following articles on JavaLobby should give further background, if needed, and progress sequentially:
- VisualVM: Free and Open Source Java Troubleshooter
- Examining the Pluggability of VisualVM Beta
- Porting a Hot Java Thread Detector to VisualVM
Feedback is always welcome, see the mailing lists that can be accessed from the VisualVM Project Home Page.