OSGi-Specific Best Practices for Developing your HTML Based vSphere Client Plug-in

This post was authored by Ina Uzunova, Product Owner of HTML Client SDK, and Vladimir Velikov, HTML Client SDK Engineer.

In vSphere 6.5 we have summarized and documented several key OSGi-specific best practices for developing your HTML based vSphere Client Plug-in. These best practices are available from chapter “Best Practices for Developing Extensions” in the official vSphere Web Client SDK Documentation.

Why is that useful?

Following the OSGi-specific recommendations helps you improve the performance and scalability of your Java service layer extensions. It is the foundation for preventing deployment, runtime and future compatibility errors for your plug-in.

The presence of clear instructions what to do and what to avoid at any cost will speed your development and prevent unintentional mistakes. Following the best practices will give your plug-in competitive advantages including smoother certification process.

Both the vSphere Web Client and the HTML-based vSphere Client released as part of vSphere 6.5 contain a new OSGi validation utility. The utility checks automatically if a deployed plug-in follows the OSGi-specific best practices.

How does this work?

Once the deployment of all plug-ins completes, the validation for a whole set of OSGi bad practices begins. Any issues detected are logged to the plugin-medic.log file. This file is located in the same folder as the Virgo server log file, vsphere_client_virgo.log.

OSGi validation tool covers the following categories of common OSGi issues:

• Clashing plugins: when two or more plug-ins contain bundles that export the same package with different versions or with no version. This could lead to race conditions causing NoClassDefFoundError during deployment or at runtime. The OSGi usage validation may report the following warnings.
  • Deployed clashing plug-ins found in the currently running HTML Client
    Conflicting package exports [Package: <package-id>;version=”<version>”; Clashing
    bundles: <bundle-id>:<version>(<plugin-id>:<version>),
    <bundle-id>:<version>(<plugin-id>:<version>)]
  • Exported packages with no version
    Export of packages with no version specified [Bundle: <bundle-id>; Unversioned
    packages: <package-id>, <package-id>]
  • Imported packages with no version
    Import of packages with no version specified [Bundle: <bundle-id>; Unversioned
    packages: <package-id>, <package-id>]

Here is an example of correct import and export of packages with versions.

• Unsafe dependency handling: when using OSGi features not recommended for HTML Client plug-ins. This could result in unexpected runtime behavior. The OSGi usage validation may report the following warnings:
  • Unnecessary usage of DynamicImport-Package in your bundle manifest
    DynamicImport-Package should be avoided [Bundle: <bundle-id>; Dynamic imports
    <package-id>]
  • Unnecessary usage of Require-Bundle in your bundle manifest
    Require-Bundle usage in place of Import-Package is discouraged [Bundle: <bundle-id>;
    Required bundles: <bundle-id>,<bundle-id>]
  • Exporting a missing package or package that belongs to another library your bundle uses
    Exporting nonexistent packages or packages from nested or imported JARs [Bundle:<bundle-id>; Exported foreign packages: <package-id>]
  • Nesting the same library within multiple bundles (instead of reusing it as a separate bundle)
    JARs with one and the same name are found in multiple bundles [JAR: <library-name>.jar; Nested in bundles: <bundle-id>, <bundle-id>]
• Naming inconsistencies: when there is a mismatch between Bundle-SymbolicName , Bundle-Vendor and/or the reverse company name of the bundle’s exported packages. This could interfere with the namespace of other plug-ins and cause unexpected runtime behavior. The OSGi usage validation may report the following warnings:
  • Non matching usages of your company name
    Packages exported with reverse company name other than the one specified in the bundle symbolic name [Bundle: <bundle-id>; Packages: <package-id>]
  • Misuse of VMware’s namespace for bundles and packages (com.vmware)
    Don’t use ‘com.vmware’ prefix for bundle symbolic names and packages [Bundle:<bundle-id>; Bundle vendor: <your-company-name>] or Don’t use ‘com.vmware’ prefix for bundle symbolic names and packages [Bundle:<bundle-id>; Misnamed exported packages: <package-id>].

As of vSphere 6.5 OSGi validation utility does not block plug-ins which violate the OSGi-specific recommendations. Nevertheless, the plugin-medic.log is essential part of the vSphere 6.5 troubleshooting process and any warnings reported for a plug-in have direct end user visibility. In an effort to increase the stability of vSphere environments and improve the end user experience, these recommendations will likely be enforced in future releases starting with vSphere 6.5 U1.

Here are more details where you can find the plugin-medic.log file based on your environment:

Plug-in writers should make sure their HTML plug-in for vSphere Client meets all Best Practices listed in the official vSphere Web Client SDK Documentation giving a high priority to the OSGi-Specific recommendations.