Chapter 2. Using the Software Development Kit This chapter outlines several examples of how to use the Java Software Development Kit. All examples in this chapter use version 3 of the software development kit unless otherwise noted. 2.1. Connecting to the Red Hat Enterprise Virtualization Manager in Version 3 In V3 of the Java software development kit, the Api class is the main class you use to connect to and manipulate objects in a Red Hat Enterprise Virtualization environment. To declare an instance of this class, you must declare an instance of the ApiBuilder class, pass the required arguments to this instance using builder methods, then call the build method on the instance. The build method returns an instance of the Api class that you can then assign to a variable and use to perform subsequent actions. The following is an example of a simple Java SE program that creates a connection with a Red Hat Enterprise Virtualization environment, then gracefully shuts down and closes the connection: Example 2.1. Connecting to the Red Hat Enterprise Virtualization Manager package rhevm; import org.ovirt.engine.sdk.Api; import java.io.IOException; import java.util.logging.Level; import java.util.logging.Logger; import org.ovirt.engine.sdk.ApiBuilder; import org.ovirt.engine.sdk.exceptions.ServerException; import org.ovirt.engine.sdk.exceptions.UnsecuredConnectionAttemptError; public class rhevm { public static void main(String[] args) { Api api = null; try { ApiBuilder myBuilder = new ApiBuilder() .url("https://rhevm.example.com/api") .user("admin@internal") .password("p@ssw0rd") .keyStorePath("/home/username/server.truststore") .keyStorePassword("p@ssw0rd"); api = myBuilder.build(); api.shutdown(); } catch (ServerException | UnsecuredConnectionAttemptError | IOException ex) { Logger.getLogger(Ovirt.class.getName()).log(Level.SEVERE, null, ex); } finally { if (api != null) { try { api.close(); } catch (Exception ex) { Logger.getLogger(Ovirt.class.getName()).log(Level.SEVERE, null, ex); } } } } } This example creates a connection using basic authentication, but other methods are also available. For a list of the key arguments that can be passed to instances of the ApiBuilder class, see Appendix A, ApiBuilder Methods . Note Note that the Api class does not implement the Autocloseable interface. As such, it is recommended that you shut down instances of the Api class in a finally block as per the above example to ensure the connection with the Red Hat Enterprise Virtualization Manager is closed gracefully. 2.2. Connecting to the Red Hat Virtualization Manager in Version 4 In V4 of the Java software development kit, the Connection class is the main class you use to connect to and manipulate objects in a Red Hat Virtualization environment. To declare an instance of this class, you must declare an instance of the ConnectionBuilder class, pass the required arguments to this instance using builder methods, then call the build method on the instance. The build method returns an instance of the Connection class that you can then assign to a variable and use to perform subsequent actions. The following is an example of a simple Java SE program that creates a connection with a Red Hat Virtualization environment using version 4 of the software development kit: Example 2.2. Connecting to the Red Hat Virtualization Manager package rhevm; import org.ovirt.engine.sdk4.Connection; import org.ovirt.engine.sdk4.ConnectionBuilder; public class rhevm { public static void main(String[] args) { ConnectionBuilder myBuilder = ConnectionBuilder.connection() .url("https://rhevm.example.com/ovirt-engine/api") .user("admin@internal") .password("p@ssw0rd") .trustStoreFile("/home/username/server.truststore") .trustStorePassword("p@ssw0rd"); try (Connection conn = myBuilder.build()) { // Requests } catch (Exception e) { // Error handling } } } This example creates a connection using basic authentication, but other methods are also available. For a list of the key arguments that can be passed to instances of the ConnectionBuilder class, see Appendix B, ConnectionBuilder Methods . 2.3. Listing Entities The following example outlines how to list entities in the Red Hat Virtualization Manager. In this example, the entities to be listed are virtual machines, which are listed using the getVMs() method of the Api class. Listing Entities Declare a List of the type of entity to be listed and use the corresponding method to get the list of entities: List<VM> vms = api.getVMs().list(); 2.4. Modifying the Attributes of Resources The following example outlines how to modify the attributes of a resource. In this example, the attribute to be modified is the description of the virtual machine with the name 'test', which is changed to 'java_sdk'. Modifying the Attributes of a Resource Declare an instance of the resource whose attributes are to be modified: VM vm = api.getVMs().get("test"); Set the new value of the attribute: vm.setDescription("java_sdk"); Update the virtual machine to apply the change: VM newVM = vm.update(); 2.5. Getting a Resource In the Java Software Development Kit, resources can be referred to via two attributes: name , and UUID . Both return an object with the specified attribute if that object exists. To get a resource using the value of the name attribute: VM vm = api.getVMs().get("test"); To get a resource using the value of the UUID attribute: VM vm = api.getVMs().get(UUID.fromString("5a89a1d2-32be-33f7-a0d1-f8b5bc974ff6")); 2.6. Adding Resources The following examples outline two ways to add resources to the Red Hat Virtualization Manager. In these examples, the resource to be added is a virtual machine. Example 1 In this example, an instance of the VM class is declared to represent the new virtual machine to be added. , the attributes of that virtual machine set to the preferred values. Finally, the new virtual machine is added to the Manager. org.ovirt.engine.sdk.entities.VM vmParams = new org.ovirt.engine.sdk.entities.VM(); vmParams.setName("myVm"); vmParams.setCluster(api.getClusters().get("myCluster")); vmParams.setTemplate(api.getTemplates().get("myTemplate")); ... VM vm = api.getVMs().add(vmParams); Example 2 In this example, an instance of the VM class is declared in the same way as Example 1. However, rather than using the get method to reference existing objects in the Manager, each attribute is referenced by declaring an instance of that attribute. Finally, the new virtual machine is added to the Manager. org.ovirt.engine.sdk.entities.VM vmParams = new org.ovirt.engine.sdk.entities.VM(); vmParams.setName("myVm"); org.ovirt.engine.sdk.entities.Cluster clusterParam = new Cluster(); clusterParam.setName("myCluster"); vmParams.setCluster(clusterParam); org.ovirt.engine.sdk.entities.Template templateParam = new Template(); templateParam.setName("myTemplate"); vmParams.setTemplate(templateParam); ... VM vm = api.getVMs().add(vmParams); 2.7. Performing Actions on Resources The following example outlines how to perform actions on a resource. In this example, a virtual machine with the name 'test' is started. Performing an Action on a Resource Declare an instance of the resource: VM vm = api.getVMs().get("test"); Declare action parameters to send to the resource: Action actionParam = new Action(); org.ovirt.engine.sdk.entities.VM vmParam = new org.ovirt.engine.sdk.entities.VM(); actionParam.setVm(vmParam); Perform the action: Action res = vm.start(actionParam); Alternatively, you can perform the action as an inner method: Action res = vm.start(new Action() { { setVm(new org.ovirt.engine.sdk.entities.VM()); } }); 2.8. Listing Sub-Resources The following example outlines how to list the sub-resources of a resource. In this example, the sub-resources of a virtual machine with the name 'test' are listed. Listing Sub-Resources Declare an instance of the resource whose sub-resources are to be listed: VM vm = api.getVMs().get("test"); List the sub-resources: List<VMDisk>; disks = vm.getDisks().list(); === Getting Sub-Resources The following example outlines how to reference the sub-resources of a resource. In this example, a disk with the name 'my disk' that belongs to a virtual machine with the name 'test' is referenced. Getting the Sub-Resources of a Resource Declare an instance of the resource whose sub-resources are to be referenced: VM vm = api.getVMs().get("test"); Declare an instance of the sub-resource to be referenced: VMDisk disk = vm.getDisks().get("my disk"); 2.9. Adding Sub-Resources to a Resource The following example outlines how to add sub-resources to a resource. In this example, a new disk with a size of '1073741824L', interface 'virtio' and format 'cow' are added to a virtual machine with the name 'test'. Adding a Sub-Resource to a Resource Declare an instance of the resource to which sub-resources are to be added: VM vm = api.getVMs().get("test"); Create parameters to define the attributes of the resource: Disk diskParam = new Disk(); diskParam.setProvisionedSize(1073741824L); diskParam.setInterface("virtio"); diskParam.setFormat("cow"); Add the sub-resource: Disk disk = vm.getDisks().add(diskParam); 2.10. Modifying Sub-Resources The following example outlines how to modify sub-resources. In this example, the name of a disk with the name 'test_Disk1' belonging to a virtual machine with the name 'test' is changed to 'test_Disk1_updated'. Updating a Sub-Resource Declare an instance of the resource whose sub-resource is to be modified: VM vm = api.getVMs().get("test"); Declare an instance of the sub-resource to be modified: VMDisk disk = vm.getDisks().get("test_Disk1"); Set the new value of the attribute: disk.setAlias("test_Disk1_updated"); Update the sub-resource: VMDisk updateDisk = disk.update(); 2.11. Performing Actions on Sub-Resources The following example outlines how to perform actions on sub-resources. In this example, a disk with the name 'test_Disk1' belonging to a virtual machine with the name 'test' is activated. Performing an Action on a Sub-Resource Declare an instance of the resource containing the sub-resource on which the action is to be performed: VM vm = api.getVMs().get("test"); Declare an instance of the sub-resource: VMDisk disk = vm.getDisks().get("test_Disk1"); Declare action parameters to send to the sub-resource: Action actionParam = new Action(); Perform the action: Action result = disk.activate(actionParam);

Commands:
package rhevm; import org.ovirt.engine.sdk.Api; import java.io.IOException; import java.util.logging.Level; import java.util.logging.Logger; import org.ovirt.engine.sdk.ApiBuilder; import org.ovirt.engine.sdk.exceptions.ServerException; import org.ovirt.engine.sdk.exceptions.UnsecuredConnectionAttemptError; public class rhevm { public static void main(String[] args) { Api api = null; try { ApiBuilder myBuilder = new ApiBuilder() .url("https://rhevm.example.com/api") .user("admin@internal") .password("p@ssw0rd") .keyStorePath("/home/username/server.truststore") .keyStorePassword("p@ssw0rd"); api = myBuilder.build(); api.shutdown(); } catch (ServerException | UnsecuredConnectionAttemptError | IOException ex) { Logger.getLogger(Ovirt.class.getName()).log(Level.SEVERE, null, ex); } finally { if (api != null) { try { api.close(); } catch (Exception ex) { Logger.getLogger(Ovirt.class.getName()).log(Level.SEVERE, null, ex); } } } } }
package rhevm; import org.ovirt.engine.sdk4.Connection; import org.ovirt.engine.sdk4.ConnectionBuilder; public class rhevm { public static void main(String[] args) { ConnectionBuilder myBuilder = ConnectionBuilder.connection() .url("https://rhevm.example.com/ovirt-engine/api") .user("admin@internal") .password("p@ssw0rd") .trustStoreFile("/home/username/server.truststore") .trustStorePassword("p@ssw0rd"); try (Connection conn = myBuilder.build()) { // Requests } catch (Exception e) { // Error handling } } }
List<VM> vms = api.getVMs().list();
VM vm = api.getVMs().get("test");
vm.setDescription("java_sdk");
VM newVM = vm.update();
VM vm = api.getVMs().get("test");
VM vm = api.getVMs().get(UUID.fromString("5a89a1d2-32be-33f7-a0d1-f8b5bc974ff6"));
org.ovirt.engine.sdk.entities.VM vmParams = new org.ovirt.engine.sdk.entities.VM(); vmParams.setName("myVm"); vmParams.setCluster(api.getClusters().get("myCluster")); vmParams.setTemplate(api.getTemplates().get("myTemplate"));
VM vm = api.getVMs().add(vmParams);
org.ovirt.engine.sdk.entities.VM vmParams = new org.ovirt.engine.sdk.entities.VM(); vmParams.setName("myVm"); org.ovirt.engine.sdk.entities.Cluster clusterParam = new Cluster(); clusterParam.setName("myCluster"); vmParams.setCluster(clusterParam); org.ovirt.engine.sdk.entities.Template templateParam = new Template(); templateParam.setName("myTemplate"); vmParams.setTemplate(templateParam);
VM vm = api.getVMs().add(vmParams);
VM vm = api.getVMs().get("test");
Action actionParam = new Action(); org.ovirt.engine.sdk.entities.VM vmParam = new org.ovirt.engine.sdk.entities.VM(); actionParam.setVm(vmParam);
Action res = vm.start(actionParam);
Action res = vm.start(new Action() { { setVm(new org.ovirt.engine.sdk.entities.VM()); } });
VM vm = api.getVMs().get("test");
List<VMDisk>; disks = vm.getDisks().list();
VM vm = api.getVMs().get("test");
VMDisk disk = vm.getDisks().get("my disk");
VM vm = api.getVMs().get("test");
Disk diskParam = new Disk(); diskParam.setProvisionedSize(1073741824L); diskParam.setInterface("virtio"); diskParam.setFormat("cow");
Disk disk = vm.getDisks().add(diskParam);
VM vm = api.getVMs().get("test");
VMDisk disk = vm.getDisks().get("test_Disk1");
disk.setAlias("test_Disk1_updated");
VMDisk updateDisk = disk.update();
VM vm = api.getVMs().get("test");
VMDisk disk = vm.getDisks().get("test_Disk1");
Action actionParam = new Action();
Action result = disk.activate(actionParam);