OSGi-Specific
RecommendationsLast Updated December 16, 2024
Following these
OSGi-specific recommendations, helps you improve the performance and
scalability of your Java service layer extensions.
- To avoid deployment errors in case your plug-in depends on a third-party library with a different version than the ones available on the application server, you can embed the library inside your bundle. You must also specify the library in your bundle manifest file by using theBundle-Classpathmanifest header. In this way, the bundle class loader looks for required classes among the classes from your plug-in and also from the embedded third-party library.For example, if your bundle uses classes from thethirdPartyLibrary.jar, add the JAR to the root of the bundle and add the following line to the bundle manifest file: As a result, when you deploy your plug-in on the application server, your bundle dependencies are resolved using the embedded third-party library and not the one that is already on the server.
- To avoid future compatibility issues, make sure that you follow the recommendations of the OSGi Alliance for wiring bundles. Use theImport-Packagemanifest header to declare your package dependencies and not theRequire-Bundleheader.
- To avoid deployment failures in case your bundle imports packages that are exported fromvim25.jar, remove any packages exported by thevim25.jarbundle from the package imports of yourMANIFEST.MFfile. You must add the following line to yourMANIFEST.MFfile:You might have deployment issues, if your environment has a plug-in package that contains thevijava-osgi.jarbundle.
- To improve the future maintenance of your bundles, you must export as few packages as possible. Remember that every exported package is considered a public API that must be versioned and maintained. If you export packages that contain implementation classes, your specific implementation becomes harder to evolve and to be maintained in the future. Ideally, you must export APIs by using a dedicated API bundles. Other bundles must import the APIs and provide implementation classes that use and publish services. The implementation classes must not export packages.
- To avoid deployment errors, you must not export packages that do not belong to your own code. If you include a third-party bundle in your bundle, do not export any classes from the third-party bundle.
- To avoid future compatibility issues in case you import a package from thevSphere Clientbundles, set the package version to0in theMANIFEST.MFfile. When you update thevSphere Clientplatform, your bundle might stop working if you specified a concrete package version that is not available after the update. If you do not specify a version, the OSGi validation utility logs a warning message in theplugin-medic.logfile.For example, if you import thecom.vmware.vise.dataandcom.vmware.vise.data.querypackages, you must add the following line to yourMANIFEST.MFfile:
- To improve the performance of your plug-in package, avoid using theDynamicImport-Packagemanifest header unless necessary. If you use theDynamicImport-Packageheader in your bundle and the packages you want to import are not known in advance, the application framework switches to searching mode for a publicly available package that satisfies the requirement. The use of wildcards is discouraged.
- To improve the deployment time of your plug-in packages, you must add as few bundles as possible to the<bundlesOrder>element of yourplugin-package.xmlmanifest file. All bundles that are not included in the ordered bundles list are deployed in parallel.For example, you can deploy the OSGi bundles from your plug-in package in a parallel manner. This deployment is achieved, if you move all APIs exported by bundle A and imported by bundle B to a separatemy_api.jarbundle. Include themy_api.jarbundle to the ordered bundles list of your plug-in package. In this way, the dependencies of bundle A and B are satisfied in advance and these bundles can start in parallel.
- To improve the deployment time of your plug-in package, do not perform Spring bean initialization in the bundles from the ordered bundles list. The deployment of bundles is blocked until the Spring bean initialization is completed for each bundle that is part of the ordered bundles list. This behavior slows down the startup of the application server. You must use the bundles from the ordered bundles list only to export APIs and data transfer objects, if possible. For more information, see the previous recommendation.
- To speed up the deployment of your plug-in package, you must use as few Web application ARchive (WAR) files as possible, ideally only one WAR file per plug-in package. WAR files are deployed slower that the other bundles, especially when the Web application has OSGi dependencies. For example, the deployment process can be slowed down when the Web application registers a message broker.
- To avoid runtime errors, you can specify the versions of the packages that you import and export for your OSGi bundle.
- Starting with vSphere 6.7U2, the Tomcat application server logs OSGi, dependency, and deployment errors toequinox.log. Theequinox.logfile is a recommended starting point for troubleshooting deployment failures.
- Starting with vSphere 6.5, an OSGi validation utility is added to thevSphere Clientwhich ensures that the deployed plug-ins follow the OSGi-specific best practices. The results from the validation checks are logged to theplugin-medic.logfile which is located in the same folder as the Tomcat server log file,vsphere_client_virgo.log. For more information about the location of the Tomcat server log files, see the Log Files Location table.Once the deployment of all plug-ins completes, the validation for the whole set of OSGi bad practices begins. Any issues detected are logged asINFOandWARNmessages to theplugin-medic.logfile. For example, following are some of the warning messages that can be seen in the log file after you deploy your plug-ins:
- DynamicImport-Package should be avoided- To prevent performance issues during plug-in deployment, you must avoid using theDynamicImport-Packagemanifest header to declare packages that must be looked up at runtime. Using dynamic imports might cause instability issues with thevSphere Client. To complete successfully the certification of your plug-in, use wildcards with caution and avoid using declarations such as the following:DynamicImport-Package: com.vmware.*.
- Don't use 'com.vmware' prefix for bundle symbolic names and packages- The warning message is logged when a third-party bundle exports packages with thecom.vmwareprefix and the bundle's symbolic name starts with a different prefix.
- Conflicting package exports- The warning message is logged when two or more plug-ins contain bundles that export the same package. This violation of the recommendations of the OSGi Alliance leads toClassNotFoundExceptions at runtime that are difficult to troubleshoot. For example, in production environments, this warning message is logged in case two plug-ins contain bundles that export Hibernate or another third-party library with the same version number.