Dependency Visualization

Finding the missing link

In OSGi framework, the bundles clearly specify what they provide and what they need, but finding these dependencies manually can be difficult. That's where the Dependency Visualization tool comes in.

Nikhil Mayaskar (nikhil.mayaskar@in.ibm.com), Software Engineer, IBM

Photo of Nikhil MayaskarNikhil Mayaskar works with IBM Cognos team in India Software Labs, Pune. His areas of experience and interests are Java/J2EE, OSGi and web technologies. He has written developerWorks articles and IBM Redpapers. In his free time, Nikhil enjoys listening to music and watching movies. He holds a B-Tech degree in Electrical Engineering from IT-BHU, India.



Amit Mittal (amit_mittal@in.ibm.com), Technical Team Leader, Problem Management, IBM  

Photo of Amit MittalAmit Mittal is from the Cognos team in IBM India Software Labs, Pune. His areas of expertise are Java/J2EE, OSGi, and various other development tools. Amit completed his Masters in Computer Applications in 2002 and has over nine years of software development experience. In his free time he enjoys watching movies, listening to music, and looking out for advancement in science and technology.



11 October 2011

Also available in Chinese Russian Japanese

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.

The problem

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:

  1. <Application Executable> -clean -console

    launch the OSGi console while starting the application
  2. 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

  1. Install the feature using the Eclipse update repository feature. Go to Help>Install New Software and 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
    Screenshot of the Graph plugin Dependencies screen with a search window.
  2. Go to Window>Preferences>Plug-in Development>Target Platform and 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.)
    Figure 2.
    Screenshot shows the target platform screen with the AUT_dropins_plugins option checked.
  3. Right click and select Focus On. Select the plugin under dropins for which you want to see the dependency graph. Here org.eclipse.emf.core

    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
    Screenshot shows a series of colored boxes with labels for different dependencies. Red arrows originate at the highlited element and branch out to all dependencies and subdependencies.
  4. 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
    Screenshot shows an error example with a pop-up box advising 'Unresolved Bundle: B' and 'Unresolved Bundle: D' The boxes in the visual view also have red X error boxes.
  5. 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
    Screenshot shows a complex project with many dependencies. In the search bar at the top is typed 'org.eclipse.mylyn' and a number of boxes in the visual layout are highlighted in yellow to show matches.
  6. 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
    Screenshot shows a preview of a dependency graph snapshot
  7. Several zoom levels have been predefined and are available through the view's context menu. (See Figure 7.)
    Figure 7. Setting zoom levels
    Screenshot shows the dependency graph with the zoom selector open. Zoom levels range from page to 400% in varying increments
  8. 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
    Screenshot shows a dependency graph. Each element has a version number displayed with the name.
  9. The option to see the callers and callee of the selected plugin is available as in Figure 9.
    Figure 9. Showing callers and callees
    Screenshot shows the buttons which activate callees and callers for elements

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 in the 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

  • Copy the org.eclipse.pde.visualization.dependency_1.0.0.jar provided with this article to your Eclipse/plugins directory and restart Eclipse. (See Download.)
  • Go to Window>Show View>;Other>Graph Plug-in Dependencies view or 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
Screenshot shows setting the plugins location to 'c:\Program Files\IBM\AUT\dropins'

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
Screenshot shows a dependency graph. Next to the name, org.hamcrest, is a red link reading '32 errors detected'

Basically, our code:

  1. Goes through all the plugins in the specified folder,
  2. Checks through the dependencies for each plugin, and
  3. 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
Screenshot shows a dependency tree with the context menu opened. There are choices for Back and Forward to move through the 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 Required Plug-ins or 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
Screenshot shows a dependency graph with the errors list expanded, showing a list of individual 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.

Conclusion

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.


Download

DescriptionNameSize
org.eclipse.pde.visualization.dependency_1.0.0.jarorg.eclipse.pde.visualization.dependency_1.0.0.jar741KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=764281
ArticleTitle=Dependency Visualization
publish-date=10112011