Exporting a Virtual Application

To export a virtual application, you must generate an OVF package. The vSphere API supports the generation of OVF packages. It does not support the generation of OVA files. An OVA file is a tar file that contains an OVF package. The OVF package consists of one of more images and an OVF file descriptor. You can create an OVA file by creating a tar file out of the OVF package for your exported virtual application.

The following steps describe how to use the vSphere VirtualApp and OvfManager API to generate an OVF package for a virtual application. The steps assume the simplest scenario: downloading one image from one device URL. You use the same steps to download many images from many device URLs. You can also export a VirtualMachine with the same steps, but use VirtualMachine.ExportVm rather than VirtualApp.ExportVApp.

1	Call the VirtualApp.ExportVApp method, which returns HttpNfcLease. The deviceURL is stored in the info property of HttpNfcLease.

2	Call the HttpNfcLeaseInfo.getDeviceUrl method to access the device URL and download the image data from the device URL.

3	Add the image to the OVF package.

4	Call the OvfManager.CreateDescriptor method, which returns OvfCreateDescriptorResult. Write the file descriptor to a file with the file extension .ovf. Add the .ovf file to the OVF package.

Generating an OVF Package shows the major steps.

Generating an OVF Package

VirtualApp and OvfManager Methods

Methods Used in Exporting a VirtualApp describes the methods used by the VirtualApp and the OvfManager API:

 

Methods Used in Exporting a VirtualApp

Method	Description
CreateDescriptor	Creates an OVF descriptor for the specified ManagedEntity, which may be a VirtualMachine or a VirtualApp. CreateDescriptor is a method in the OvfManager managed object.
ExportVApp	Obtains an export lease on the virtual application. The export lease contains a list of URLs for the disks of the virtual machines in this virtual application. ExportVApp is a method in the VirtualApp managed object.
getDeviceUrl	Retrieves the device IDs and URLs from the server. getDeviceUrl is an accessor method provided in the generated JAX-WS bindings. It does not appear in VirtualApp Class Diagram.

The next two sections deal with the VirtualApp and OvfManager data structures.

VirtualApp Data Structures

The VirtualApp managed object contains the ExportVApp method, which returns an HttpNfcLease. The HttpNfcLease contains the info and state properties, where info is of type HttpNfcLeaseInfo and state is of type HttpNfcLeaseState. The HttpNfcLeaseInfo data object has several properties, one of which is the deviceUrl of type HttpNfcLeaseDeviceUrl[]. The HttpNfcLeaseState has four different states—done, error, initializing and ready.

VirtualApp Class Diagram shows the UML representation of the data structures used in the VirtualApp API.

VirtualApp Class Diagram

The VirtualApp API data structures are the following:

■	VirtualApp—A managed object that is a collection of virtual machines (and potentially other VirtualApp containers) that are operated and monitored as a unit.

■	HttpNfcLease—A managed object returned when you call VirtualApp.ExportVApp. It represents a lease on the virtual application. While you hold the lease, you block the operations that alter the state of the virtual application.

■	HttpNfcLeaseInfo—A data object that holds information about the lease, such as the virtual application covered by the lease, and the device URLs for up/downloading images.

■	HttpNfcLeaseState—An enumeration that is a list of possible states of a lease.

HttpNfcLeaseDeviceUrl—A data object that provides a mapping from logical device IDs to upload/download URLs.

OvfManager Data Structures

The OvfManager managed object has a CreateDescriptor method that returns an OvfCreateDescriptorResult. The OvfCreateDescriptorResult has the ovfDescriptor string.

OvfManager Class Diagram shows the UML representation of the data structures used in the OvfManager API.

OvfManager Class Diagram

The OvfManager data structures are the following:

■	OvfManager—A managed object that provides a service interface to parse and generate OVF descriptors.

■	OvfCreateDescriptorResult—A data object that contains the result of creating the OVF descriptor for the virtual application.

Example of Generating an OVF Package

In summary, the steps in generating an OVF package are the following:

1	Get the managed object reference to the VirtualApp object. Call the ExportVApp method, which returns an HttpNfcLease data object. Wait for the state of the lease to turn to READY. Get the list of device URLs from the lease and store them in an array.

2	For each of the URLs in the list of device URLs, download the images from that URL to the client.

3	Save the image to the OVF package (directory/folder). Create an OvfFile object using the deviceID, absolute path of the downloaded image, and the size of the image on the local disk.

4

Call the OvfManager.CreateDescriptor method by passing the managed object reference to the VirtualApp and the OvfFile object wrapped in an OvfCreateDescriptorParams object. This method returns OvfCreateDescriptorResult, which contains the file descriptor. Write the file descriptor to a file with the file extension .ovf. Add the .ovf file to the OVF package.

The following is an example of how to generate an OVF package. The example assumes a more complex scenario: downloading more than one image from more than one device URL. The example is based on the OVFManagerExportVAAP.java sample, which is located in the SDK/vsphere-ws/java/JAXWS/samples/com/vmware/vapp/ directory.

You can use the ExportVM method instead of the ExportVapp method when exporting a VirtualMachine.

package com.vmware.vapp;

 

import java.io.*;

import java.net.URL;

import java.util.*;

 

...

  /** 1. Get the MOR of the VirtualApp.

M       ManagedObjectReference vAppMoRef = getVAPPByName(vApp);

...

  /**    Call the ExportVApp method, which returns an HttpNfcLease data object. */

        ManagedObjectReference httpNfcLease = vimPort.exportVApp(vAppMoRef);

 

...

  /**    Wait for the state of the lease to turn to READY. */

           Object[] result = waitForValues.wait(httpNfcLease, new String[]{"state"},

                           new String[]{"state"},

                                new Object[][]{new Object[]{

                                        HttpNfcLeaseState.READY,

                                        HttpNfcLeaseState.ERROR}});

                if (result[0].equals(HttpNfcLeaseState.READY)) {

 

...

  /**    Get the list of device URLs from the lease. */

                    List<HttpNfcLeaseDeviceUrl> deviceUrlArr =

                              httpNfcLeaseInfo.getDeviceUrl();

                    if (deviceUrlArr != null) {

...

  /** 2. For each of the URLs in the list of device URLs, download the images from that URL to the client. */

                        for (int i = 0; i < deviceUrlArr.size(); i++) {

 

                            String deviceId = deviceUrlArr.get(i).getKey();

String deviceUrlStr = deviceUrlArr.get(i).getUrl();

String absoluteFile =

deviceUrlStr.substring(deviceUrlStr

.lastIndexOf("/") + 1);

  /** 3. Save the image to the OVF package (directory/folder). Create an OvfFile object using

   * the deviceID, absolute path of the downloaded image, and the size of the image on the

   * local disk.

   */

                            long writtenSize =

writeVMDKFile(absoluteFile,

deviceUrlStr.replace("*", host));

OvfFile ovfFile = new OvfFile();

ovfFile.setPath(absoluteFile);

ovfFile.setDeviceId(deviceId);

ovfFile.setSize(writtenSize);

 

ovfFiles.add(ovfFile);

}

  /** 4. Call the OvfManager.CreateDescriptor method by passing the managed object reference

   * to the VirtualApp and the OvfFile object wrapped in an OvfCreateDescriptorParams object.

   * This method returns OvfCreateDescriptorResult, which contains the file descriptor.

   * Write the file descriptor to a file with the file extension .ovf. Add the .ovf file to

   * the OVF package.

   */

ovfCreateDescriptorParams.getOvfFiles().addAll(ovfFiles);

OvfCreateDescriptorResult ovfCreateDescriptorResult =

vimPort.createDescriptor(

serviceContent.getOvfManager(), vAppMoRef,

ovfCreateDescriptorParams);

 

String outOVF = localpath + "/" + vApp + ".ovf";

File outFile = new File(outOVF);

FileWriter out = new FileWriter(outFile);

 

out.write(ovfCreateDescriptorResult.getOvfDescriptor());

out.close();