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 theImport-Packageelement 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-Packageheader. - If you define a Spring XML file (for example, in the
META-INF/springdirectory), 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'sImport-Packageelement. - If you define a blueprint XML file (for example, in the
OSGI-INF/blueprintdirectory), 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:
- 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:listto check which bundles are installed andfeatures:listto check which features are installed. - Install (but do not start) your bundle, using the
osgi:installconsole command. For example:JBossFuse:karaf@root> osgi:install MyBundleURL
- Use the
dev:dynamic-importconsole 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 theImport-Packageheader). 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. - 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
- 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 thepackage:importscommand. 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 Apache ServiceMix :: Specs :: JAXB API 2.2 (87): javax.xml.bind.annotation; version=2.2.1 Apache ServiceMix :: Specs :: JAXB API 2.2 (87): javax.xml.bind; version=2.2.1 Web Services Metadata 2.0 (104): javax.jws; version=2.0.0 Apache ServiceMix :: Specs :: JAXWS API 2.2 (105): javax.xml.ws.handler; version=2.2.0 Apache ServiceMix :: Specs :: JAXWS API 2.2 (105): javax.xml.ws; version=2.2.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 ...
- Unpack your bundle JAR file and look at the packages listed under the
Import-Packageheader in theMETA-INF/MANIFEST.MFfile. 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'sImport-Packageheader and add these package names to theImport-Packageelement of the Maven bundle plug-in configuration in your project's POM file. - 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
- You can now rebuild your bundle with the updated list of imported packages and test it in the OSGi container.
