VisualVM Developer FAQ

This is the developer-oriented FAQ for VisualVM. Developer in this context means "person writing plugins for VisualVM".

Getting Started

What's the current status of the VisualVM APIs?

Under development. You are free to create plugins but you must realize that there will definitely be non-compatible changes in the coming months. However, all such changes will be clearly documented at the time of the related release.

How do I get started extending VisualVM?

Read Getting Started Extending VisualVM, which gives you some background information about VisualVM extensions, shows you how to set up your environment, walks you through a "Hello World" scenario, and gives you an overview of all the VisualVM public packages.

Where is the VisualVM Javadoc?

See https:///visualvm.github.io.

Do I have to use NetBeans IDE to extend Visual VM?

No. However, NetBeans IDE provides wizards and templates for VisualVM plugin development, while other IDEs do not (currently) have this kind of support.

Lifecycle

What is the lifecyle of a VisualVM plugin?

A plugin's life begins when it is installed into VisualVM. It can be installed through the VisualVM Plugin Manager (accessed from the Tools menu) or when you run it from NetBeans IDE.

The entry points implemented in a plugin must be initialized in a class that extends org.openide.modules.ModuleInstall. They must also be uninstalled through that class. Initialization occurs in the ModuleInstall.restored method and uninstallation through the ModuleInstall.uninstalled method.

Every example of VisualVM extension points includes an example of the entry points initialization and uninstallation, such as in the Getting Started Extending VisualVM document.

What about the layer.xml file?

If you have created modules on top of the NetBeans Platform before, you will be aware of a configuration file called layer.xml. This file is used to initialize entry points into the NetBeans Platform. However, the APIs that are specific to VisualVM do not use this approach. Instead, they use the org.openide.modules.ModuleInstall class, as described above.

However, since VisualVM is based on the NetBeans Platform, VisualVM is able to reuse several of the NetBeans Platform APIs. For example, VisualVM reuses the NetBeans APIs responsible for providing the main menubar's menu items and the main toolbars and toolbar buttons. Therefore, you will need to use the NetBeans Actions API when you want to add new menu items and toolbars to VisualVM. The NetBeans Actions API makes use of the layer.xml file and, therefore, in this case you would make use of the layer.xml file after all. However, if you're using NetBeans IDE, you would simply use the "New Action" wizard and then the wizard would populate the layer.xml file for you. If you have questions about the NetBeans Platform APIs, see the NetBeans Developer FAQ.

Data Sources

What is a DataSource?

A data source is the primary actor in the VisualVM APIs. Everything that happens in VisualVM happens in relation to a data source.

The most important data source from the user's perspective is the Application data source. This data source represents the applications that are monitored and managed in VisualVM. The other existing data sources exist to support the Application data source.

In VisualVM, each node in the explorer view (on the left of the application) is provided by a data source (and its supporting classes).

What are the default DataSources?

The following are the default data sources:

  • AbstractApplication
  • AbstractCoreDump
  • AbstractDataSource
  • AbstractHeapDump
  • AbstractHost
  • AbstractSnapshot
  • AbstractThreadDump
  • Application
  • CoreDump
  • DataSource
  • DataSourceContainer
  • DataSourceProvider
  • DataSourceRepository
  • DataSourceRoot
  • DefaultDataSourceContainer
  • DefaultDataSourceProvider
  • HeapDump
  • Host
  • Snapshot
  • ThreadDump

Why would I create a new DataSource?

Possibly, you want the user to be able to monitor, troubleshoot, or manage a source of data that VisualVM does not provide support for out of the box. In fact, VisualVM is simply a tool for displaying data, so you could create one or more of the following data sources:

  • Photo
  • ShoppingList
  • Task
  • Reminder

However, VisualVM is created specifically for monitoring, troubleshooting, and management purposes. Therefore, you are more likely to want to create new data sources that relate specifically to these purposes. In general, the need to create a new data source is likely to arise in only a very small number of cases.

How do I create a new DataSource?

A DataSource object is defined when you extend these classes:

  • com.sun.tools.visualvm.core.datasource.AbstractDataSource
  • com.sun.tools.visualvm.core.datasource.DefaultDataSourceProvider
  • com.sun.tools.visualvm.core.model.dsdescr.DataSourceDescriptor
  • com.sun.tools.visualvm.core.model.AbstractModelProvider

A complete example can be found here. In addition, you can read the VisualVM sources, because all the predefined data sources are defined there.

Views

What is a view?

A view in VisualVM consists of a tab and one or more subtabs, displayed in the main application area when "Open" is chosen on a data source in the explorer view.

  • A tab is, for example, "Overview", "Monitor", and "Threads".
  • A subtab is, for example, "JVM Arguments" and "System Properties", within the "Overview" tab.

How do I create new views (tabs, pluggable tabs, subtabs)?

You create new tabs by extending these classes:

  • com.sun.tools.visualvm.core.ui.DataSourceView
  • com.sun.tools.visualvm.core.ui.DataSourceViewProvider

A complete example for creating new tabs can be found here.

To make your tabs extendable, the following API must be extended:

  • com.sun.tools.visualvm.core.ui.PluggableViewSupport

A complete example for creating pluggable view can be found here.

You create new subtabs by extending these classes:

  • com.sun.tools.visualvm.core.ui.ViewPlugin
  • com.sun.tools.visualvm.core.ui.ViewPlugin.ViewDescriptor

A subtab can only be added to a tab if the tab is created to be pluggable, that is, only if the tab makes use of com.sun.tools.visualvm.core.ui.PluggableViewSupport. In the cases of the predefined tabs in VisualVM, you need to initialize the support class that relates to the pluggable view that you want to extend:

  • com.sun.tools.visualvm.core.dataview.monitor.MonitorViewSupport
  • com.sun.tools.visualvm.core.dataview.overview.OverviewViewSupport
  • com.sun.tools.visualvm.core.dataview.threads.ThreadsViewSupport
  • com.sun.tools.visualvm.core.heapdump.HeapDumpSupport
  • com.sun.tools.visualvm.core.threaddump.ThreadDumpSupport

A complete example for adding a subtab to the "Overview" tab can be found here.

What components can I use to design my view?

The VisualVM APIs provides a set of components that make it easy for you to integrate your tools into VisualVM:

  • com.sun.tools.visualvm.core.ui.components.DataViewComponent.MasterView
  • com.sun.tools.visualvm.core.ui.components.DataViewComponent.MasterViewConfiguration
  • com.sun.tools.visualvm.core.ui.components.DataViewComponent.DetailsView
  • com.sun.tools.visualvm.core.ui.components.DataViewComponent.DetailsAreaConfiguration
  • com.sun.tools.visualvm.core.ui.components.DataViewComponent.DisplayArea
  • com.sun.tools.visualvm.core.ui.components.DataViewComponent.ScrollableContainer

A complete example that works with most of the VisualVM ui components can be found in the Getting Started Extending VisualVM document.

Application Types

What is an application type?

An application type is a model that you need to create when you want VisualVM to cater to a new type of application. For example, the GlassFish plugin creates a new application type for applications that have com.sun.enterprise.server.PELaunch as their main class. Since that is the main class of the GlassFish application server, the application type is created whenever an instance of GlassFish is started.

What are the default application types?

The following are the predefined application types:

  • DefaultApplicationType
  • JavaPluginApplicationType
  • JavaWebStartApplicationType
  • MainClassApplicationType
  • NetBeans3xApplicationType
  • NetBeansApplicationType
  • NetBeansBasedApplicationType
  • VisualVMApplicationType

Why would I create my own application types?

You would create your own application type if you have an application that you want VisualVM in a special way. By default, the DefaultApplicationType will be used to handle your application. However, if your application is a deployment server, you probably want to display nodes for deployed applications as subnodes to the application node in the explorer view. In this case, you would need to model a new type of application and then create it via a factory class. Most typically, as done in the case of GlassFish, your factory class would create your application type if a started application has a main class that matches the main class defined in the application type implementation.

How do I create my own application types?

You create new application types by extending these classes:

  • com.sun.tools.visualvm.core.model.apptype.ApplicationType
  • com.sun.tools.visualvm.core.model.apptype.ApplicationTypeFactory

A complete example for creating a new application type can be found here.

How do I add subnodes to my application type?

to be done

How do I add contextual menu items to my application type?

You create new contextual menu items by extending these classes:

  • com.sun.tools.visualvm.core.explorer.ExplorerActionsProvider
  • javax.swing.AbstractAction

Note: If a DataSourceViewProvider returns true from the supportsViewFor() method, an "Open" menu item is automatically created for you, as explained here.

A complete example for creating new menu items can be found here.

How do I add contextual menu items to my application type's subnodes?

to be done

Hosts

What is a host?

The Host class provides the common interface for data sources that represent a localhost or remote host. It is a data source, just like Application is a data source. However, it is not as important to the end user as the Application data source. By default, VisualVM provides a tab per host, showing host-specific information, such as CPU and memory statistics, as well as the host IP and operating syste,.

How do I add additional views for the Host data source?

You create new tabs for the Host data source by extending these classes:

  • com.sun.tools.visualvm.core.ui.DataSourceView
  • com.sun.tools.visualvm.core.ui.DataSourceViewProvider<Host>

A complete example for creating new tabs for the Host data source can be found here.

How do I extend the Host "Overview" tab?

You create new tabs for the Host data source by extending these classes:

  • com.sun.tools.visualvm.core.ui.ViewPlugin.ViewDescriptor
  • com.sun.tools.visualvm.core.ui.ViewPlugin<Host>

A complete example for creating new tabs for the Host data source can be found here.

Enabling/Disabling Functionality

How do I ensure that the application has JMX enabled?

Possibly, you only want a view to be shown if JMX is enabled. For this reason, you have two classes at your disposal:

  • com.sun.tools.visualvm.core.model.jmx.JmxModel
  • com.sun.tools.visualvm.core.model.jmx.JmxModelFactory

Use your DataSourceViewProvider.supportsViewFor like this for these purposes: 

public boolean supportsViewFor(Application application) {
    JmxModel jmx = JmxModelFactory.getJmxModelFor(application);
    MBeanServerConnection mbsc = jmx.getMBeanServerConnection();
    return mbsc != null;
}

If false is returned, JMX is not enabled and the view will not be shown.

How do I ensure that an appropriate JVM is being used?

to be done

Distribution

How do I distribute my VisualVM plugins?

If you use NetBeans IDE to create your VisualVM plugin, you can right-click the project and choose "Create NBM". This gives you an NBM file, which is a ZIP file that VisualVM understands. That NBM file can be installed into VisualVM via the Plugin Manager. You can distribute your NBM file via e-mail or by putting it on a server and telling your users where to get it. You can also create something called an "update center", which is an XML file defining your NBM file's location and description, which your users can register in their Plugin Manager and which they can then use to access your VisualVM plugins.