org.virtualbox_6_0
Class IAppliance

java.lang.Object
  extended by org.virtualbox_6_0.IUnknown
      extended by org.virtualbox_6_0.IAppliance

public class IAppliance
extends IUnknown

Represents a platform-independent appliance in OVF format. An instance of this is returned byIVirtualBox.createAppliance(), which can then be used to import and export virtual machines within an appliance with VirtualBox. The OVF standard suggests two different physical file formats:

  1. If the appliance is distributed as a set of files, there must be at least one XML descriptor file that conforms to the OVF standard and carries an.ovffile extension. If this descriptor file references other files such as disk images, as OVF appliances typically do, those additional files must be in the same directory as the descriptor file.
  2. If the appliance is distributed as a single file, it must be in TAR format and have the.ovafile extension. This TAR file must then contain at least the OVF descriptor files and optionally other files. At this time, VirtualBox does not not yet support the packed (TAR) variant; support will be added with a later version.
Importingan OVF appliance into VirtualBox as instances ofIMachineinvolves the following sequence of API calls:
  1. CallIVirtualBox.createAppliance(). This will create an empty IAppliance object.
  2. On the new object, callread(String)with the full path of the OVF file you would like to import. So long as this file is syntactically valid, this will succeed and fill the appliance object with the parsed data from the OVF file.
  3. Next, callinterpret(), which analyzes the OVF data and sets up the contents of the IAppliance attributes accordingly. These can be inspected by a VirtualBox front-end such as the GUI, and the suggestions can be displayed to the user. In particular, thegetVirtualSystemDescriptions()array contains instances ofIVirtualSystemDescriptionwhich represent the virtual systems (machines) in the OVF, which in turn describe the virtual hardware prescribed by the OVF (network and hardware adapters, virtual disk images, memory size and so on). The GUI can then give the user the option to confirm and/or change these suggestions.
  4. If desired, callIVirtualSystemDescription.setFinalValues(List,List,List)for each virtual system (machine) to override the suggestions made by theinterpret()routine.
  5. Finally, callimportMachines(List)to create virtual machines in VirtualBox as instances ofIMachinethat match the information in the virtual system descriptions. After this call succeeded, the UUIDs of the machines created can be found in thegetMachines()array attribute.
ExportingVirtualBox machines into an OVF appliance involves the following steps:
  1. As with importing, first callIVirtualBox.createAppliance()to create an empty IAppliance object.
  2. For each machine you would like to export, callIMachine.exportTo(org.virtualbox_6_0.IAppliance,String)with the IAppliance object you just created. Each such call creates one instance ofIVirtualSystemDescriptioninside the appliance.
  3. If desired, callIVirtualSystemDescription.setFinalValues(List,List,List)for each virtual system (machine) to override the suggestions made by theIMachine.exportTo(org.virtualbox_6_0.IAppliance,String)routine.
  4. Finally, callwrite(String,List,String)with a path specification to have the OVF file written.
Interface ID: {86A98347-7619-41AA-AECE-B21AC5C1A7E6}


Field Summary
 
Fields inherited from class org.virtualbox_6_0.IUnknown
obj, objMgr, port
 
Constructor Summary
IAppliance(java.lang.String wrapped, org.virtualbox_6_0.ObjectRefManager objMgr, org.virtualbox_6_0.jaxws.VboxPortType port)
           
 
Method Summary
 void addPasswords(java.util.List<java.lang.String> identifiers, java.util.List<java.lang.String> passwords)
          Adds a list of passwords required to import or export encrypted virtual machines.
 IVFSExplorer createVFSExplorer(java.lang.String URI)
          Returns aIVFSExplorerobject for the given URI.
 ICertificate getCertificate()
          The X.509 signing certificate, if the imported OVF was signed, null if not signed.
 java.util.List<java.lang.String> getDisks()
          Array of virtual disk definitions.
 java.util.List<java.lang.String> getMachines()
          Contains the UUIDs of the machines created from the information in this appliances.
 java.util.List<java.lang.String> getMediumIdsForPasswordId(java.lang.String passwordId)
          Returns a list of medium identifiers which use the given password identifier.
 java.util.List<java.lang.String> getPasswordIds()
          Returns a list of password identifiers which must be supplied to import or export encrypted virtual machines.
 java.lang.String getPath()
          Path to the main file of the OVF appliance, which is either the.ovfor the.ovafile passed toread(String)(for import) orwrite(String,List,String)(for export).
 java.util.List<IVirtualSystemDescription> getVirtualSystemDescriptions()
          Array of virtual system descriptions.
 java.util.List<java.lang.String> getWarnings()
          Returns textual warnings which occurred during execution ofinterpret().
 IProgress importMachines(java.util.List<ImportOptions> options)
          Imports the appliance into VirtualBox by creating instances ofIMachineand other interfaces that match the information contained in the appliance as closely as possible, as represented by the import instructions in thegetVirtualSystemDescriptions()array.
 void interpret()
          Interprets the OVF data that was read when the appliance was constructed.
static IAppliance queryInterface(IUnknown obj)
           
 IProgress read(java.lang.String file)
          Reads an OVF file into the appliance object.
 IProgress write(java.lang.String format, java.util.List<ExportOptions> options, java.lang.String path)
          Writes the contents of the appliance exports into a new OVF file.
 
Methods inherited from class org.virtualbox_6_0.IUnknown
getObjMgr, getRemoteWSPort, getWrapped, releaseRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IAppliance

public IAppliance(java.lang.String wrapped,
                  org.virtualbox_6_0.ObjectRefManager objMgr,
                  org.virtualbox_6_0.jaxws.VboxPortType port)
Method Detail

getPath

public java.lang.String getPath()
Path to the main file of the OVF appliance, which is either the.ovfor the.ovafile passed toread(String)(for import) orwrite(String,List,String)(for export). This attribute is empty until one of these methods has been called.

Returns:
String

getDisks

public java.util.List<java.lang.String> getDisks()
Array of virtual disk definitions. One such description exists for each disk definition in the OVF; each string array item represents one such piece of disk information, with the information fields separated by tab (\\t) characters. The caller should be prepared for additional fields being appended to this string in future versions of VirtualBox and therefore check for the number of tabs in the strings returned. In the current version, the following eight fields are returned per string in the array:
  1. Disk ID (unique string identifier given to disk)
  2. Capacity (unsigned integer indicating the maximum capacity of the disk)
  3. Populated size (optional unsigned integer indicating the current size of the disk; can be approximate; -1 if unspecified)
  4. Format (string identifying the disk format, typically "http://www.vmware.com/specifications/vmdk.html#sparse")
  5. Reference (where to find the disk image, typically a file name; if empty, then the disk should be created on import)
  6. Image size (optional unsigned integer indicating the size of the image, which need not necessarily be the same as the values specified above, since the image may be compressed or sparse; -1 if not specified)
  7. Chunk size (optional unsigned integer if the image is split into chunks; presently unsupported and always -1)
  8. Compression (optional string equaling "gzip" if the image is gzip-compressed)

Returns:
List<String>

getVirtualSystemDescriptions

public java.util.List<IVirtualSystemDescription> getVirtualSystemDescriptions()
Array of virtual system descriptions. One such description is created for each virtual system (machine) found in the OVF. This array is empty until eitherinterpret()(for import) orIMachine.exportTo(org.virtualbox_6_0.IAppliance,String)(for export) has been called.

Returns:
List<org.virtualbox_6_0.IVirtualSystemDescription>

getMachines

public java.util.List<java.lang.String> getMachines()
Contains the UUIDs of the machines created from the information in this appliances. This is only relevant for the import case, and will only contain data after a call toimportMachines(List)succeeded.

Returns:
List<String>

getCertificate

public ICertificate getCertificate()
The X.509 signing certificate, if the imported OVF was signed, null if not signed. This is available after callingread(String).

Returns:
org.virtualbox_6_0.ICertificate

queryInterface

public static IAppliance queryInterface(IUnknown obj)

read

public IProgress read(java.lang.String file)
Reads an OVF file into the appliance object. This method succeeds if the OVF is syntactically valid and, by itself, without errors. The mere fact that this method returns successfully does not mean that VirtualBox supports all features requested by the appliance; this can only be examined after a call tointerpret().

Parameters:
file - Name of appliance file to open (either with an.ovfor.ovaextension, depending on whether the appliance is distributed as a set of files or as a single file, respectively).
Returns:
Progress object to track the operation completion.

interpret

public void interpret()
Interprets the OVF data that was read when the appliance was constructed. After calling this method, one can inspect thegetVirtualSystemDescriptions()array attribute, which will then contain oneIVirtualSystemDescriptionfor each virtual machine found in the appliance. Calling this method is the second step of importing an appliance into VirtualBox; seeIAppliancefor an overview. After calling this method, one should callgetWarnings()to find out if problems were encountered during the processing which might later lead to errors.


importMachines

public IProgress importMachines(java.util.List<ImportOptions> options)
Imports the appliance into VirtualBox by creating instances ofIMachineand other interfaces that match the information contained in the appliance as closely as possible, as represented by the import instructions in thegetVirtualSystemDescriptions()array. Calling this method is the final step of importing an appliance into VirtualBox; seeIAppliancefor an overview. Since importing the appliance will most probably involve copying and converting disk images, which can take a long time, this method operates asynchronously and returns an IProgress object to allow the caller to monitor the progress. After the import succeeded, the UUIDs of the IMachine instances created can be retrieved from thegetMachines()array attribute.

Parameters:
options - Options for the importing operation.
Returns:
Progress object to track the operation completion.

createVFSExplorer

public IVFSExplorer createVFSExplorer(java.lang.String URI)
Returns aIVFSExplorerobject for the given URI.

Parameters:
URI - The URI describing the file system to use.

write

public IProgress write(java.lang.String format,
                       java.util.List<ExportOptions> options,
                       java.lang.String path)
Writes the contents of the appliance exports into a new OVF file. Calling this method is the final step of exporting an appliance from VirtualBox; seeIAppliancefor an overview. Since exporting the appliance will most probably involve copying and converting disk images, which can take a long time, this method operates asynchronously and returns an IProgress object to allow the caller to monitor the progress.

Parameters:
format - Output format, as a string. Currently supported formats are "ovf-0.9", "ovf-1.0", "ovf-2.0" and "opc-1.0"; future versions of VirtualBox may support additional formats. The "opc-1.0" format is for creating tarballs for the Oracle Public Cloud.
options - Options for the exporting operation.
path - Name of appliance file to create. There are certain restrictions with regard to the file name suffix. If the format parameter is "opc-1.0" a.tar.gzsuffix is required. Otherwise the suffix must either be.ovfor.ova, depending on whether the appliance is distributed as a set of files or as a single file, respectively.
Returns:
Progress object to track the operation completion.

getWarnings

public java.util.List<java.lang.String> getWarnings()
Returns textual warnings which occurred during execution ofinterpret().


getPasswordIds

public java.util.List<java.lang.String> getPasswordIds()
Returns a list of password identifiers which must be supplied to import or export encrypted virtual machines.

Returns:
The list of password identifiers required for export on success.

getMediumIdsForPasswordId

public java.util.List<java.lang.String> getMediumIdsForPasswordId(java.lang.String passwordId)
Returns a list of medium identifiers which use the given password identifier.

Parameters:
passwordId - The password identifier to get the medium identifiers for.
Returns:
The list of medium identifiers returned on success.

addPasswords

public void addPasswords(java.util.List<java.lang.String> identifiers,
                         java.util.List<java.lang.String> passwords)
Adds a list of passwords required to import or export encrypted virtual machines.

Parameters:
identifiers - List of identifiers.
passwords - List of matching passwords.