Finding the missing link
The missing link, understanding the issue
How many times has your custom Eclipse plugin or feature failed after exporting to another Eclipse-based application?
Finding and satisfying all of your plugin dependencies in the new environment is simplified. In the past, manual validation of plugins was required, but today, Eclipse's Dependency Visualization tool, part of the Eclipse Incubator project, removes or reduces that necessity. Let's explore the issue in detail, look at the available solutions, and consider possible modifications to make plugin dependency analysis tasks easier.
OSGi, the boon
Eclipse has changed the way Java™ and other language programmers develop applications, as well as facilitated the creation of big applications brick-by-brick. While not a new concept, having all the dependencies clearly defined in neatly packed bundles is bliss for many developers.
The advent of Open Services Gateway Initiative (OSGi), and its beautiful mechanism of updating applications by replacing/adding/deleting bundles, created new possibilities. Updating Eclipse-based applications on client machines is now as common and simple as updating web-based applications.
We should remember that for the whole update mechanism to work properly, there is a lot of hard work in the background. We know any Eclipse-based application can be updated by simply dropping the bundles in proper folders, but what about the dependencies? How many times have you lost functionality or gotten the dreaded Eclipse load error, leaving no clue as to what happened?
The problem can be seen in two scenarios:
- Installation of third-party features—Chances of missing dependencies are lessened. In a best-case scenario, these are handled prior to release, but we know this is not always the case.
- Creation of a feature—Eclipse provides numerous APIs, and many programmers fail to utilize the target platform. Upon exporting the bundles, the Eclipse installation fails.
The culprit is the failure to identify and document the minimum set of bundles, hereafter referred to as dependencies, for the new feature.
We faced this scenario recently while planning to use SWTBot testing tool in one of our projects. Like other automation testing tools, a part of SWTBot should sit in the application to be tested (AUT) for automation to work. If the SWTBot feature is installed into an application using Equinox P2 update feature, it will take care of the dependencies. Many times, however, that is not possible, for example, when the application is not P2 enabled.
Nothing to fear (not yet); let's move to the next section.
The (not so good) solution
We can resolve this problem plausibly in a couple of ways:
launch the OSGi console while starting the application
- Search the unresolved plugins one-by-one for their dependencies
If you are lucky, you will get a simple error message like "Could not resolve bundle ABC due to missing required bundle XYZ."
If not, you will see "Could not resolve bundle ABC due to missing package XYZ" because you must identify which bundle exports the specified package.
You cannot use the
package<package name> command to find
the bundle because it will work only when the bundle in question is
resolved. If it was resolved, you would not have received the error.
There is an added unfavorable dimension to the console approach. Consider a situation where things work fine on your end, but not on a remote machine where the users are not technical enough to use the console. Even if you get a savvy user, you don't want them scratching their heads and wondering about the skills of the developer.
Lastly, Eclipse-based applications often use a custom mechanism to start,
for example a custom script when it's not possible to provide the
-console option directly.
With that in mind, let's have a look at a better solution.
A better solution
The background work mentioned earlier doesn't always have to be hard. We'd rather work smart, and the Eclipse Project helps us do that.
This article demonstrates the use of Eclipse Project tool Dependency Visualization, which displays the dependencies of plugins without starting the target application. This helps identify the unresolved plugins even before the application is launched.
Eclipse PDE project – Dependency Visualization
Note: The Dependency Visualization plugin for showing the dependency graph works with Eclipse version 3.5.X or higher.
Setup and usage
- Install the feature using the Eclipse update repository feature. Go to
Help>Install New Softwareand paste in http://download.eclipse.org/eclipse/pde/incubator/visualization/site. Uncheck the Group items by category check box.
Then go to
Window>Show View>Other>Graph Plug-in Dependencies view, or press Ctrl+3 and select Graph Plug-in Dependencies view as in Figure 1.
Figure 1. Graph Plug-in Dependencies view
- Go to
Window>Preferences>Plug-in Development>Target Platformand point the Eclipse target platform to include plugins from <application_install>/dropins and <application_install>/plugins and set it to active. Click Apply.(See Figure 2.)
- Right click and select Focus On. Select the plugin
under dropins for which you want to see the dependency graph. Here
Three dependency analysis tools have been added to the control panel. By selecting a bundle, the shortest path, all paths, and smart path to this bundle can be highlighted. Shortest and all paths are self-explanatory. Smart path shows all the shortest paths from the directly required bundles to plugin that is selected. Figure 3 shows an example.
Figure 3. Smart path view of dependencies
- To help plugin developers track and fix errors, an error reporting
feature has been added to highlight paths to bundles that cannot be
resolved. (See Figure 4.)
Figure 4. Visual error reporting
- The search text box can be used to highlight all plugins matching a
particular string. In this case, all the bundles containing the string
org.eclipse.mylyn are highlighted. Figure 5 shows an example.
Figure 5. Visual searching
- The screenshot tool can be used to create a PNG from the Plug-in
Dependency Graph. (See Figure 6.)
Figure 6. Plug-in Dependency Graph snapshot
- Several zoom levels have been predefined and are available through the
view's context menu. (See Figure 7.)
Figure 7. Setting zoom levels
- A version number toggle is available to show plugin developers which
particular bundle has been resolved. (See Figure 8.)
Figure 8. Bundle version number view
- The option to see the callers and callee of the selected plugin is
available as in Figure 9.
Figure 9. Showing callers and callees
By using these features, the selected plugin from the <application_install>/dropins folder (here org.eclipse.emf.core) would be validated with all the plugins in the <application_install>/dropins and <application_install>/plugins folders for dependency check, and errors would be reported.
Going one step ahead
What the Eclipse team has done is commendable, yet this functionality can be extended further. The tool shows the dependency for a single plugin at a time, but as we discussed in the first section, we need to find if all the plugins and bundles in our feature are fully resolved. Instead of focusing on the bundles one-by-one, it is more efficient to provide a folder path to the Dependency Visualization tool and let it check the dependencies for all the bundles in that folder in one go.
Apart from that, the tool scans the target platform for plugins mentioned
Required Bundle section of MANIFEST.MF and reports
missing plugins. But, what about unresolved imported packages?
We wrote a small code on top of the Eclipse PDE project to implement these to make plugin dependencies analysis much simpler and easier. Below are the details:
Set up and use
- Revert back the installation done in section 2.1. Please see the documentation for reverting back to previous Eclipse installation at http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.platform.doc.user/tasks/tasks-123.htm.
- Copy the
org.eclipse.pde.visualization.dependency_1.0.0.jarprovided with this article to your Eclipse/plugins directory and restart Eclipse. (See Download.)
- Go to
Window>Show View>;Other>Graph Plug-in Dependencies viewor press Ctrl+3 and select Graph Plug-in Dependencies view for opening the tool.
Validating all plugins in a folder
This enables validating all the plugins in the folder specified. This feature saves time as you don't have to right click and select Focus On… for each and every plugin. The report for unresolved bundles is consolidated and displayed at a single place.
Note: The plugins in the folder specified under Plug-ins Location should be included in the active target platform as well. (See Figure 10.)
Figure 10. Setting plugin location
Click Apply and a list of all the unresolved bundles should be displayed under the hyperlink in red. Figure 11 shows 32 errors were detected with dependency graph of the last bundle in the specified folder.
Figure 11. Showing count of unresolved bundles
Basically, our code:
- Goes through all the plugins in the specified folder,
- Checks through the dependencies for each plugin, and
- Adds all the unresolved dependencies to the "errors detected."
To view the dependency graph of each plugin, use the Back and Forward options either on right click or on the tool bar. (See Figure 12.)
Figure 12. Moving through the element tree
Remaining functionalities, such as
- Show bundle version,
- Show dependency path,
- Show callees, and
- Show callers,
work the same way as before.
Reporting unresolved import packages errors
The dependencies of a bundle can either be specified under
Imported Packages under
Dependencies section of
MANIFEST.MF. The bundle is fully resolved only when the "Required
Plug-ins" and the ones exporting the packages mentioned in "Imported
Packages" are available. The Eclipse PDE project reports errors for
missing "Required Plug-ins" only and skips the unresolved packages.
We did further changes to show unresolved import packages (with version range) for the selected bundle. (See Figure 13.)
- The list of errors would contain all the missing "Required Plug-ins" first and then unresolved packages.
- The optional imports are skipped.
Figure 13. Unresolved import package errors
Please note, while using the feature mentioned in section 3.2, only missing "Required Plug-ins" would be reported in the error report for all the plugins in the specified folder and not the unresolved import packages.
The missing import details are provided at the single plugin level and can be seen using Back and Forward options either on right click or on the tool bar. Further changes can be made to include this functionality at the folder level and can be extended to generate a comprehensive log file or simply displaying over the console.
In all cases, the unresolved import packages would be displayed in the error report only (the link in red) and not in the graph because the tool has no clue which plugin would export this unresolved package.
Again, the rest of functionalities, such as
- Show bundle version,
- Show dependency path,
- Show callees, and
- Show callers,
work the same way as before.
Limitations and common pitfalls
- The tool provides dependency analysis for plugins only and not fragments.
- It validates a particular plugin with others mentioned in the active target platform only. There is no way for the tool to suggest resolution of the missing required plugins or unresolved imports.
- The code has been compiled and tested with IBM JRE version 1.5.
This article demonstrates the Dependency Visualization tool given by Eclipse PDE with some custom modifications aiming to provide a set of views to assist with plugin dependency analysis tasks. In particular, the views will provide cognitive support to developers as they attempt to understand the dependencies between their plugins.
- All Eclipse IDE project articles and tutorials Browse this comprehensive list of articles and tutorials about Eclipse IDE development. View the list by product, title, topic, or keyword and sort your results.
- developerWorks on Twitter: Follow us for the latest news.
- Eclipse's Dependency Visualization tool: Download the tool from the project web page.
- Eclipse Marketplace is a convenient portal where you can find open source and commercial Eclipse-related offerings. If you downloaded Indigo through a package, you'll have access to the Eclipse Marketplace client.