7.4. Troubleshooting Dependencies

Missing dependencies

The most common issue that can arise when you deploy an OSGi bundle into the Red Hat JBoss Fuse container is that one or more dependencies are missing. This problem shows itself when you try to resolve the bundle in the OSGi container, usually as a side effect of starting the bundle. The bundle fails to resolve (or start) and a ClassNotFound error is logged (to view the log, use the log:display console command or look at the log file in the InstallDir/data/log directory).
There are two basic causes of a missing dependency: either a required feature or bundle is not installed in the container; or your bundle's Import-Package header is incomplete.

Required features or bundles are not installed

Evidently, all features and bundles required by your bundle must already be installed in the OSGi container, before you attempt to resolve your bundle. In particular, because Apache Camel has a modular architecture, where each component is installed as a separate feature, it is easy to forget to install one of the required components.
Note
Consider packaging your bundle as a feature. Using a feature, you can package your bundle together with all of its dependencies and thus ensure that they are all installed simultaneously. For details, see Chapter 8, Deploying Features.

Import-Package header is incomplete

If all of the required features and bundles are already installed and you are still getting a ClassNotFound error, this means that the Import-Package header in your bundle's MANIFEST.MF file is incomplete. The maven-bundle-plugin (see Section 6.2, “Modifying an Existing Maven Project”) is a great help when it comes to generating your bundle's Import-Package header, but you should note the following points:
  • Make sure that you include the wildcard, *, in the Import-Package element of the Maven bundle plug-in configuration. The wildcard directs the plug-in to scan your Java source code and automatically generates a list of package dependencies.
  • The Maven bundle plug-in is not able to figure out dynamic dependencies. For example, if your Java code explicitly calls a class loader to load a class dynamically, the bundle plug-in does not take this into account and the required Java package will not be listed in the generated Import-Package header.
  • If you define a Spring XML file (for example, in the META-INF/spring directory), the Maven bundle plug-in is not able to figure out dependencies arising from the Spring XML configuration. Any dependencies arising from Spring XML must be added manually to the bundle plug-in's Import-Package element.
  • If you define a blueprint XML file (for example, in the OSGI-INF/blueprint directory), any dependencies arising from the blueprint XML file are automatically resolved at run time. This is an important advantage of blueprint over Spring.

How to track down missing dependencies

To track down missing dependencies, perform the following steps:
  1. Perform a quick check to ensure that all of the required bundles and features are actually installed in the OSGi container. You can use osgi:list to check which bundles are installed and features:list to check which features are installed.
  2. Install (but do not start) your bundle, using the osgi:install console command. For example:
    JBossFuse:karaf@root> osgi:install MyBundleURL
  3. Use the dev:dynamic-import console command to enable dynamic imports on the bundle you just installed. For example, if the bundle ID of your bundle is 218, you would enable dynamic imports on this bundle by entering the following command:
    JBossFuse:karaf@root> dev:dynamic-import 218
    This setting allows OSGi to resolve dependencies using any of the bundles already installed in the container, effectively bypassing the usual dependency resolution mechanism (based on the Import-Package header). This is not recommemded for normal deployment, because it bypasses version checks: you could easily pick up the wrong version of a package, causing your application to malfunction.
  4. You should now be able to resolve your bundle. For example, if your bundle ID is 218, enter the followng console command:
    JBossFuse:karaf@root> osgi:resolve 218
  5. Assuming your bundle is now resolved (check the bundle status using osgi:list), you can get a complete list of all the packages wired to your bundle using the package:imports command. For example, if your bundle ID is 218, enter the following console command:
    JBossFuse:karaf@root> package:imports 218
    You should see a list of dependent packages in the console window (where the package names are highlighted in this example):
    Spring Beans (67): org.springframework.beans.factory.xml; version=3.0.5.RELEASE
    Web Services Metadata 2.0 (104): javax.jws; version=2.0.0
    Apache CXF Bundle Jar (125): org.apache.cxf.helpers; version=2.4.2.fuse-00-08
    Apache CXF Bundle Jar (125): org.apache.cxf.transport.jms.wsdl11; version=2.4.2.fuse-00-08
    ...
  6. Unpack your bundle JAR file and look at the packages listed under the Import-Package header in the META-INF/MANIFEST.MF file. Compare this list with the list of packages found in the previous step. Now, compile a list of the packages that are missing from the manifest's Import-Package header and add these package names to the Import-Package element of the Maven bundle plug-in configuration in your project's POM file.
  7. To cancel the dynamic import option, you must uninstall the old bundle from the OSGi container. For example, if your bundle ID is 218, enter the following command:
    JBossFuse:karaf@root> osgi:uninstall 218
  8. You can now rebuild your bundle with the updated list of imported packages and test it in the OSGi container.