Geertjan is a DZone Zone Leader and has posted 466 posts at DZone. You can read more from them at their website. View Full User Profile

VisualVM Beta 2: Reorganization of APIs

04.21.2008
| 5775 views |
  • submit to reddit
Beta 2 of VisualVM was released a week or so ago. A significant API reorganization took place, in preparation for the final release. Let's look through it all and adapt existing VisualVM plugins accordingly.

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.
    The "plugins" folder is particularly useful if you want to create similar functionality yourself. For example, if you're interested in creating a VisualVM plugin for WebSphere, take a look at the GlassFish plugin and try and reuse as much of it as possible.
  • 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:

<filesystem>
<folder name="Actions">
<folder name="Other">
<file name="net-java-visualvm-btrace-actions-DeployBTraceScriptAction.instance"/>
<file name="net-java-visualvm-btrace-actions-UndeployBTraceScriptAction.instance"/>
</folder>
</folder>
<folder name="VisualVM">
<folder name="ExplorerPopupSelection">

<file name="net-java-visualvm-btrace-actions-DeployBTraceScriptAction.shadow">
<attr name="originalFile" stringvalue="Actions/Other/net-java-visualvm-btrace-actions-DeployBTraceScriptAction.instance"/>
<attr name="position" intvalue="3000"/>
</file>

<file name="net-java-visualvm-btrace-actions-UndeployBTraceScriptAction.shadow">
<attr name="originalFile" stringvalue="Actions/Other/net-java-visualvm-btrace-actions-UndeployBTraceScriptAction.instance"/>
<attr name="position" intvalue="3500"/>
</file>

</folder>
</folder>
</filesystem>

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:

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:

Feedback is always welcome, see the mailing lists that can be accessed from the VisualVM Project Home Page.

AttachmentSize
visual-vm-sources.png35.89 KB
vvm-reorg-samples-0.png57.88 KB
vvm-reorg-samples-2.png34.46 KB
vvm-reorg-samples-3.png64.22 KB
vvm-javadoc-1.png70.73 KB
vvm-javadoc-2.png92.43 KB
Published at DZone with permission of its author, Geertjan Wielenga.

Comments

Darin Rieck replied on Mon, 2008/04/21 - 12:52pm

This page is very helpful, especially for new users.

Gregg Sporar replied on Mon, 2008/04/21 - 2:22pm

+1, this is helpful.  Just wondering, though, what was the reason for the change from "implementing DataSourceViewsProvider, you now need to extend DataSourceViewProvider."

Markus Jais replied on Tue, 2008/04/22 - 1:24am

I want to say thanks to all the Visual VM developers. This is an amazing tool and very helpful. Looking forward to the final release.

Ingo Rockel replied on Tue, 2008/04/22 - 8:24am

Thanks for the Update on the API Changes!

Geertjan Wielenga replied on Tue, 2008/04/22 - 8:56am

Comments received from the VisualVM API authors: "API changes - not exactly incorrect but a bit simplified, for example DataSourceViewsProvider.getViews >>> DataSourceViewProvider.createView is not just renaming, DataSourceViewProvider has built-in caching, createView is called only once etc. I don't have time to describe all the differences but I believe they are clearly visible from the sources. The same for implements/extends - interface DataSourceViewsProvider providing multiple views for a DataSource was simply changed to abstract class DataSourceViewProvider providing single view for each DataSource. Main reason for changing interface to abstract class is mainly possibility to extend the API in future in a compatible way."

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.