OSGi-Specific Recommendations
Last 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 the
    Bundle-Classpath
    manifest 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 the
    thirdPartyLibrary.jar
    , add the JAR to the root of the bundle and add the following line to the bundle manifest file:
    Bundle-Classpath: .,thirdPartyLibrary.jar
    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 the
    Import-Package
    manifest header to declare your package dependencies and not the
    Require-Bundle
    header.
  • To avoid deployment failures in case your bundle imports packages that are exported from
    vim25.jar
    , remove any packages exported by the
    vim25.jar
    bundle from the package imports of your
    MANIFEST.MF
    file. You must add the following line to your
    MANIFEST.MF
    file:
    Require-Bundle: com.vmware.vim25;bundle-version=1.0.0
    You might have deployment issues, if your environment has a plug-in package that contains the
    vijava-osgi.jar
    bundle.
  • 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 the
    vSphere Client
    bundles, set the package version to
    0
    in the
    MANIFEST.MF
    file. When you update the
    vSphere Client
    platform, 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 the
    plugin-medic.log
    file.
    For example, if you import the
    com.vmware.vise.data
    and
    com.vmware.vise.data.query
    packages, you must add the following line to your
    MANIFEST.MF
    file:
    Import-Package: com.vmware.vise.data;version="0", com.vmware.vise.data.query;version="0"
  • To improve the performance of your plug-in package, avoid using the
    DynamicImport-Package
    manifest header unless necessary. If you use the
    DynamicImport-Package
    header 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 your
    plugin-package.xml
    manifest 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 separate
    my_api.jar
    bundle. Include the
    my_api.jar
    bundle 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 to
    equinox.log
    . The
    equinox.log
    file is a recommended starting point for troubleshooting deployment failures.
  • Starting with vSphere 6.5, an OSGi validation utility is added to the
    vSphere Client
    which ensures that the deployed plug-ins follow the OSGi-specific best practices. The results from the validation checks are logged to the
    plugin-medic.log
    file 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 as
    INFO
    and
    WARN
    messages to the
    plugin-medic.log
    file. 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 the
      DynamicImport-Package
      manifest header to declare packages that must be looked up at runtime. Using dynamic imports might cause instability issues with the
      vSphere 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 the
      com.vmware
      prefix 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 to
      ClassNotFoundException
      s 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.