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.

Connecting to the {virt-product-fullname} {engine-name} 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 {virt-product-fullname} 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 {virt-product-fullname} environment using version 4 of the software development kit:

Example 1. Connecting to the {virt-product-fullname} {engine-name}

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 ConnectionBuilder Methods.

Listing Entities

The following example outlines how to list entities in the {virt-product-fullname} {engine-name}. In this example, the entities to be listed are virtual machines, which are listed using the getVMs() method of the Api class.

Procedure

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();
```

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'.

Procedure

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();
```

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"));

Adding Resources

The following examples outline two ways to add resources to the {virt-product-fullname} {engine-name}. 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. Next, the attributes of that virtual machine set to the preferred values. Finally, the new virtual machine is added to the {engine-name}.

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 {engine-name}, each attribute is referenced by declaring an instance of that attribute. Finally, the new virtual machine is added to the {engine-name}.

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);

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.

Procedure

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());
    }
});

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.

Procedure

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.

Procedure

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");
```

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'.

Procedure

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);

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'.

Procedure

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();
```

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.

Procedure

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);