Release Notes for vSphere Web Client SDK 5.5

Please read the full release notes because of important changes that will guarantee your plugin compatibility with 5.5 and future releases.

  1. Upgrading from version 5.1
  2. New Features
  3. Other Changes
  4. Deprecated Features
  5. Breaking Changes
  6. Changes since 5.5 beta 2

Upgrading from version 5.1 or 5.1 U1

Setup

The overall setup is the same as in 5.1 but since vCenter 5.0 is not supported by VWC 5.5 you will need to upgrade your vSphere vCenter to version 5.1 or 5.5. vCenter 5.1 will work fine if you are not willing to install 5.5 yet.

The main changes in the SDK setup are the following:

  1. Virgo was upgraded to version 3.6. This should not affect your own setup, see section Other Changes below for more information.
  2. The minimum Flash Player version is now 11.5. This allows to display the stack trace of errors when using the release version.
  3. You must upgrade to Java 1.7 but compile with option -target 1.6. See the Java JDK setup.
  4. See the new sections Software Requirements Summary and Mac OS Setup notes and tips.

You can keep your current Eclipse/STS environment if you follow these steps:

Plugin Packaging

Once you start using 5.5 APIs your plugin will no longer work correctly with VWC 5.1. You must update the pluginPackage dependency on VWC version 5.1.0 to 5.5.0 so that your plugin cannot be loaded when VWC 5.1.0 is running:

  <dependencies>
      <!-- dependency on the current vSphere Client version is required -->
      <pluginPackage id="com.vmware.vsphere.client" version="5.5.0" />
   </dependencies>
If you don't update that dependency and a user connects to a vCenter where your plugin is registered using VWC 5.1 one of three things can happen:
  1. The plugin still works correctly because it is not using any API incompatible with 5.1.
  2. The plugin fails to deploy and the UI is not visible to users. The server log will show the reason for the deployment error.
  3. The plugin UI is visible but a Flex error or Java error occurs at runtime (worst case for the user's experience).

The registration process as a vCenter extension is still the same as with version 5.1.

Flex and Java development cycles

Not much has changed in this area, you can use the same Eclipse plugin to create a Flex UI or Java Service project, and follow the various tips provided in the SDK Tutorial and FAQs. The FAQs did get significant additions since 5.1.

Testing your current plugin

After upgrading to SDK 5.5 rebuild your plugin and test it with VWC 5.5, it should work exactly the same as before. Please report any problem you encounter!

Likewise a plugin built with SDK 5.1 should work as-is in Web Client 5.5. However a 5.1 plugin is not guaranteed to be binary compatible with the next major release coming after 5.5 (see for instance how the Web-ContextPath must be formatted from now on in "Other changes" below).

New Features

This section gives only an overview of what was added. See also the vSphere 5.5 Web Client SDK Programming Guide.
For a list of new extension points see the ones labeled 5.5 in this updated list.
See the Flex API docs and Java API docs for Flex and Java APIs.

Solution menus

The recommended way to extend vSphere objects' menu is to use the new extension point vsphere.core.menus.solutionMenus. It lets you define your solution-specific menu more precisely with a list of actions and with sub-menus and separators if necessary. See the updated vmaction-ui sample.

Actions Prioritization

Two new extension points allow to assign priorities on actions, i.e. to order them or promote them specifically:

See how these extension points are used in the chassis-app samples.

AdvancedMouseEvent

New API which allows you to listen to right-click events inside your own widgets. The native Flash MouseEvents are suppressed on purpose to avoid the Flash context menu, so instead you can add a listener for AdvancedMouseEvent.RIGHT_CLICK. See AdvancedMouseEvent.

UI Dispose Manager

The internal Dispose Manager (i.e. garbage collector for Flex objects) has been improved in the way it detects objects that are no longer in use and can be disposed of to avoid memory leaks. But since it is impossible to know which 3rd party objects are cached the Dispose Manager will no longer attempt to release objects unless their namespace is explicitly declared with the new extension point vise.dispose.namespace.inclusions. For instance, if you'd like to turn on the Dispose Manager on all types starting with namespace com.example.myplugin add the following extension in plugin.xml:

   <extension id="com.example.myplugin.disposemanager">
     <extendedPoint>vise.dispose.namespace.inclusions</extendedPoint>
        <object>
         <namespaces>
           <String>com.example.myplugin</String>
         </namespaces>
      </object>
   </extension>

We recommend that you use a top level namespace to minimize memory leaks in your plugin (it is used by default by all VMware plugins). The only case where you may want to exclude a particular namespace is when your code involves some advanced caching or your tests detect problems with objects being disposed too early.

DataException

The DataException API was added to the Flex library (it was only in Java before) so that you can cast a return error to DataException and use its objects and properties fields. DataException can also be used now by DataProviderAdapters to signal errors when discovering new objects (by opposition to fetching data on existing objects). The error message will be displayed briefly in your objects list view, showing that the empty list is not a normal state. See the API doc for specific examples.

UserSession samlTokenXml

The UserSession class has a new field samlTokenXml that contains the XML value of the SAML Token for the current user. A plug-in can use that information to check the user's authentication if necessary. See the vSphere Single Sign-On documentation.

Dialogs and Wizards

New Dialogs and Wizard APIs are provided to help your 5.5 development, but we have to mark them as deprecated right away because they are not guaranteed to be compatible with the next major SDK release. If you can use these APIs in 5.5 you may need to update your plugin when the next version comes out.

See how the APIs are used in the chassis-ui sample.

Other Changes

Virgo was upgraded to the recent version 3.6, see these release notes for details. This should not affect your existing plugins. One visible change is the renaming of the server subdirectory config to configuration.

All UI plugins Web-ContextPath must use the format vsphere-client/plugin-name, i.e. be prefixed with vsphere-client, in anticipation of the next major release where this will be required. Samples have been updated to that effect, as well as the Eclipse wizard generating new plugin projects. Existing plugins will work as-is, but new plugins should follow that rule.

UI plugins using proxies must have two default channels in war/src/main/webapp/WEB-INF/flex/remote-config.xml and war/src/main/webapp/WEB-INF/flex/services-config.xml, "amf" and "secure-amf" as shown below:

<service id="remoting-service"
    class="flex.messaging.services.RemotingService">
    <adapters>
        <adapter-definition id="java-object"
            class="com.vmware.vise.messaging.remoting.JavaAdapterEx"
            default="true"/>
    </adapters>
    <default-channels>
        <channel ref="secure-amf"/>
        <channel ref="amf"/>
    </default-channels>
</service>
<services-config>
   <services>
      <service-include file-path="remoting-config.xml" />
      <default-channels>
         <channel ref="secure-amf"/>
         <channel ref="amf"/>
      </default-channels>
   </services>

   <channels>
      <channel-definition id="secure-amf" class="mx.messaging.channels.SecureAMFChannel">
         <endpoint
            url="https://{server.name}:{server.port}/{context.root}/messagebroker/amfsecure"
            class="com.vmware.vise.messaging.endpoints.SecureAMFEndpoint" />
      </channel-definition>

      <channel-definition id="amf" class="mx.messaging.channels.AMFChannel">
         <endpoint
            url="http://{server.name}:{server.port}/{context.root}/messagebroker/amf"
            class="com.vmware.vise.messaging.endpoints.AMFEndpoint" />
      </channel-definition>
   </channels>
   ...

Note also that the AMF channel endpoints have been changed to use internal classes from packagecom.vmware.vise.messaging.endpoints instead of the default flex.messaging.endpoints. Samples and project wizard were updated. However you don't need to change your existing plugin unless you plan on using Java enums. The VMware endpoint classes include an internal EnumWrapper to convert Java enums to Flex because BlazeDS doesn't support this by default. A separate doc will be available with more details.

Tools

The SDK Tools Eclipse plugin was updated with small changes in the source that gets generated when creating a new Flex or Java project.

Shell scripts are provided for building Flex and Java projects on Mac OS: build-flex.sh and build-java.sh.

SDK samples improvements

Be sure to load the newest samples as they take advantage of new features and better implementation.

actions: vmaction-ui was updated to use the new extension point vsphere.core.menus.solutionMenus. One added benefit is that the menu doesn't show anymore All NoGroup Actions when running the plugin from Eclipse.

custom-property-provider: the custom-property-provider sample now returns a DataException in case an error occurred during the web service call. This is the recommended way to propagate exception back to the UI during a data query.

globalview:

chassis-app:

Deprecated Features

The following 5.1 APIs are marked deprecated in 5.5, i.e. compatibility is not guaranteed with the next major release.

The new Dialogs and Wizards APIs are deprecated because they are only guaranteed to work with 5.5.

Regarding extensions to the Object Navigator interface, the following "admin" "categories that were documented in 5.1 have been deprecated and should not be used by plugins going forward:

You can still add your own category extension beneath the "Administration" section as shown in the globalview sample.

Breaking Changes

No breaking change known at the time of this release. Plugins built with 5.1 should work with VWC 5.5.

Changes since 5.5 beta 2

If you are upgrading from beta 2, here is a summary of changes.