Chapter 2. Using the Software Development Kit

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:

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.

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:

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.

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

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

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

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. Next, 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);

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

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

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

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

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

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