VMware vSphere Automation SDK for Java 6.5 Release Notes

This document contains the following sections:

• Overview
• Distribution Kit
• Supported Java Versions
• What's New
• Known Issues

Overview

The VMware vSphere Automation SDKs provide support for your client application infrastructure with services to perform management operations in your vSphere environment. This SDK also contains samples that demonstrate API extensibility and how the libraries work with other vSphere APIs.

The version 6.5 SDK enables programmatic access to the following services:

• Service discovery using Lookup Service
• Authentication (Single Sign-On)
• Session management
• Tagging
• Content Library
• Virtual Machines
• vCenter Server Appliance management

Note:  Single Sign-On authentication is available through the VMware vCenter Single Sign-On API. Service discovery is available through the Lookup Service API.

Distribution Kit

When you extract the contents of the vSphere Automation SDK for Java distribution kit, the files are placed in the VMware-vSphere-Automation-SDK-Java directory. That directory also contains the provider development kit which supports the development of a service to be integrated into the vSphere Automation environment.

    VMware-vSphere-Automation-SDK-Java/
        client/
        docs/
        SDK-EULA.txt
        open_source_license.txt
        vSphere-Automation-SDK-Java-README.html

You can download the vSphere Automation SDK for Java distribution kit from the VMware Developer Center.

Supported Java Versions

The vSphere Automation SDK for Java 6.5 runs with JDK 1.8 or later.

What's New

This release of the vSphere Automation SDK for Java includes the following new features:

• SDK rename.

  vCloud Suite SDK for Java is now renamed to vSphere Automation SDK for Java.

• Updated samples.

  The samples provided in the vSphere Automation SDK for Java are updated and expanded.

• URI scheme changes.

  Creating a content library backed by a file storage URI is not supported. When you create a content library and specify a Windows Shared Folder as a storage backing, note that the file URI format is not supported and you should use smb://unc-server/path instead of file://unc-server/path.

  Creating a subscribed content library with a file subscription URL is not supported. When you create a subscribed library you can use an HTTP or HTTPS subscription URL. The new URI schemes supported for this release are NFS, SMB, and DS. For more information about the supported URI formats, see the API Reference documentation.

• Virtual Machine Management APIs.

  This release includes Virtual Machine Management APIs that enable developers to manage the lifecycle and configure the hardware of a virtual machine.

• The Tagging API is more powerful, including improved search methods and bulk tagging capability.
• Appliance Management API.

  This release of the SDK includes bindings for vCenter Server Appliance Management interfaces that enable developers to create client applications to configure, monitor, and manage the vCenter Server Appliance.

• Java 8 required for samples.

  The samples provided in the vSphere Automation SDK for Java require Java 8.

• Certificate support.

  In this release of the SDK, the samples support certificate validation on the command line. See the README files in the SDK.

Known Issues

The following issues were discovered during testing.

• Samples unable to connect to server.

  If you run the samples in a JDK 1.7 environment, the samples will be unable to connect to vSphere services. The error message is:

              Exception in thread "main" java.lang.RuntimeException: 
              javax.net.ssl.SSLPeerUnverifiedException: peer not authenticated
              

  The error results from a transport encryption mismatch. In the vSphere 6.5 release, vSphere services run with enhanced security, using TLS 1.2. JDK 1.7 does not support the stronger version of TLS.

  To run the samples, you must install JDK 1.8, which supports TLS 1.2. After you install JDK 1.8, set the JAVA_HOME variable to the location of JDK 1.8 on your system.

  If you are unable to install JDK 1.8, download and install build 4240471 of ESXi and build 4240472 of vCenter Server, which use the older TLS protocols.

• Internal Server Error if Tagging Description Field is Empty

  The Tag Category Description field is optional in the vSphere Web Services API, but it is mandatory in the vSphere Automation SDK for Java. Therefore, if the description field is empty, the vSphere Automation SDK for Java can return an internal server error that states, "the ‘description’ field of the Category model is empty".

  Workaround:

  When creating tags, do not leave the description field empty. If you do not have any description, you may add a whitespace character (i.e. space).

• Unauthenticated exception following long-running operation

  After an API client completes a long-running operation, such as an upload to the content library, the next operation might fail with an "Unauthenticated exception" message. This happens if the long running operation did not complete within the lifetime of the authentication session.

  Workarounds:

  • Keep the session alive by issuing short operations on another thread until the long running operation completes.
  • Increase the session length using the VMware vSphere Web Client. Select Administration > System Configuration > Services > vAPI Endpoint > Manage > General, and increase the value for the Maximum session idle time.

• Tomcat vulnerability to CVE-2014-0227 (request smuggling exploit). The vSphere Automation SDK for Java ships with Tomcat version 7.0.35, which contains a vulnerability to request smuggling. In the case of a chunked request, a malformed continuation chunk could be interpreted by Tomcat as a new request.

  Workaround:

  Upgrade the Tomcat server to version 7.0.55 or later.

• Sample names in Programming Guide.

  The samples provided in the vSphere Automation SDK for Java are updated but the changes are not reflected in the programming guide.