Red Hat Enterprise Virtualization 3.

Java SDK Guide

Using the Red Hat Enterprise Virtualization Java SDK

Last Updated: 2017-09-27

Red Hat Enterprise Virtualization 3.6 Java SDK Guide

Using the Red Hat Enterprise Virtualization Java SDK

Red Hat Enterprise Virtualization Documentation Team

Red Hat Customer Content Services
[email protected]
Legal Notice

Copyright © 2016 Red Hat.

This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0
Unported License. If you distribute this document, or a modified version of it, you must provide
attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red
Hat trademarks must be removed.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity
logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other
countries.

Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.

Java ® is a registered trademark of Oracle and/or its affiliates.

XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United
States and/or other countries.

MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and
other countries.

Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related
to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other
countries and are used with the OpenStack Foundation's permission. We are not affiliated with,
endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract

This guide describes Red Hat Enterprise Virtualization's Java Software Development Kit.
 Table of Contents

Table of Contents
.CHAPTER
. . . . . . . . . . 1.
. .OVERVIEW
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . . . .
1.1. PREREQUISITES 3

.CHAPTER
. . . . . . . . . . 2.
. . CREATING
. . . . . . . . . . . .A. .BUILD
. . . . . . .ENVIRONMENT
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . .
2.1. INSTALLING THE JAVA SOFTWARE DEVELOPMENT KIT 4
2.2. DEPENDENCIES 4
2.3. CONFIGURING SSL 4

.CHAPTER
. . . . . . . . . . 3.
. . USING
. . . . . . . .THE
. . . . SOFTWARE
. . . . . . . . . . . . .DEVELOPMENT
. . . . . . . . . . . . . . . . KIT
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6. . . . . . . . . . . .
3.1. CONNECTING TO THE RED HAT ENTERPRISE VIRTUALIZATION MANAGER 6
3.2. LISTING ENTITIES 7
3.3. MODIFYING THE ATTRIBUTES OF RESOURCES 7
3.4. GETTING A RESOURCE 8
3.5. ADDING RESOURCES 8
3.6. PERFORMING ACTIONS ON RESOURCES 9
3.7. LISTING SUB-RESOURCES 9
3.8. GETTING SUB-RESOURCES 10
3.9. ADDING SUB-RESOURCES TO A RESOURCE 10
3.10. MODIFYING SUB-RESOURCES 10
3.11. PERFORMING ACTIONS ON SUB-RESOURCES 11

. . . . . . . . . . . . A.
APPENDIX . . .APIBUILDER
. . . . . . . . . . . . . METHODS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
.............

. . . . . . . . . . . . B.
APPENDIX . . .REVISION
. . . . . . . . . . HISTORY
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
.............

1
Java SDK Guide

2
 CHAPTER 1. OVERVIEW

CHAPTER 1. OVERVIEW
The Java software development kit is a collection of classes that allows you to interact with the Red
Hat Enterprise Virtualization Manager in Java-based projects. By downloading these classes and
adding them to your project, you can access a range of functionality for high-level automation of
administrative tasks.

The Java software development kit uses the rhevm-sdk-java package, which is available to systems
subscribed to a Red Hat Enterprise Virtualization entitlement pool in Red Hat Subscription
Manager.

1.1. PREREQUISITES
To install the Java software development kit, you must have:

A system where Red Hat Enterprise Linux 6.6 or 7 is installed. Both the Server and Workstation
variants are supported.

A subscription to Red Hat Enterprise Virtualization entitlements.

IMPORTANT

The rhevm-sdk-java package must be installed on each system where scripts that use
the software development kit will be run.

IMPORTANT

The software development kit is an interface for the Red Hat Enterprise Virtualization
REST API. As such, you must use the version of the software development kit that
corresponds to the version of your Red Hat Enterprise Virtualization environment. For
example, if you are using Red Hat Enterprise Virtualization 3.5, you must use the version
of the software development kit designed for 3.5.

3
Java SDK Guide

CHAPTER 2. CREATING A BUILD ENVIRONMENT

This chapter describes how to create a build environment to develop applications using the Java
software development kit.

2.1. INSTALLING THE JAVA SOFTWARE DEVELOPMENT KIT

Install the Java software development kit and accompanying documentation.

Procedure 2.1. Installing the Java Software Development Kit

1. Ensure your system is subscribed to the Red Hat Enterprise Virtualization

entitlement in Red Hat Subscription Manager:

# subscription-manager list --available | grep -A8 "Red Hat

Enterprise Virtualization"
# subscription-manager attach --pool=pool_id
# subscription-manager repos --enable=rhel-6-server-rpms
# subscription-manager repos --enable=rhel-6-server-rhevm-3.6-rpms
# subscription-manager repos --enable=jb-eap-6-for-rhel-6-server-
rpms

2. Install the required packages:

# yum install rhevm-sdk-java

# yum install rhevm-sdk-java-javadoc

The Java software development kit and accompanying documentation are downloaded to the
/usr/share/java/rhevm-sdk-java directory, and can now be added to Java projects.

2.2. DEPENDENCIES
To use the Java software development kit in Java applications, you must add the following JAR files to
the class path of those applications:

commons-beanutils.jar

commons-codec.jar

httpclient.jar

httpcore.jar

jakarta-commons-logging.jar

log4j.jar

The packages that provide these JAR files are installed as dependencies to the rhevm-sdk-java
package. By default, they are available in the /usr/share/java directory on Red Hat Enterprise
Linux 6 and Red Hat Enterprise Linux 7 systems.

2.3. CONFIGURING SSL

4
 CHAPTER 2. CREATING A BUILD ENVIRONMENT

The Red Hat Enterprise Virtualization Manager Java SDK provides full support for HTTP over Secure
Socket Layer (SSL) and the IETF Transport Layer Security (TLS) protocol using the Java Secure
Socket Extension (JSSE). JSSE has been integrated into the Java 2 platform as of version 1.4 and
works with the Java SDK out of the box. On older Java 2 versions, JSSE must be manually installed and
configured.

2.3.1. Configuring SSL

The following procedure outlines how to configure SSL using the Java SDK.

Procedure 2.2. Configuring SSL

1. Download the certificate for the Red Hat Enterprise Virtualization Manager:

https://[your manager's address]:[port]/ca.crt

2. Generate a keystore:

keytool -import -alias "server.crt truststore" -file ca.crt -

keystore server.truststore

3. Specify the keyStorePath and keyStorePassword arguments when constructing an

instance of the Api object as described in Section 3.1, “Connecting to the Red Hat Enterprise
Virtualization Manager”:

myBuilder.keyStorePath("/home/username/server.truststore")
myBuilder.keyStorePassword("p@ssw0rd")

2.3.2. Host Verification

By default, the identity of the host name in the certificate is verified when attempting to open a
connection to the Red Hat Enterprise Virtualization Manager. You can disable verification by passing
the following argument when constructing an instance of the Api class:

myBuilder.noHostVerification(true)

IMPORTANT

This method should not be used for production systems due to security reasons, unless
it is a conscious decision and you are aware of the security implications of not verifying
host identity.

5
Java SDK Guide

CHAPTER 3. USING THE SOFTWARE DEVELOPMENT KIT

This chapter outlines several examples of how to use the Java Software Development Kit.

3.1. CONNECTING TO THE RED HAT ENTERPRISE VIRTUALIZATION

MANAGER
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 3.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();

myBuilder.url("https://rhevm.example.com/api")
myBuilder.user("admin@internal")
myBuilder.password("p@ssw0rd")
myBuilder.keyStorePath("/home/username/server.truststore")
myBuilder.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) {

6
 CHAPTER 3. USING THE SOFTWARE DEVELOPMENT KIT

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.

3.2. LISTING ENTITIES

The following example outlines how to list entities in the Red Hat Enterprise Virtualization Manager. In
this example, the entities to be listed are virtual machines, which are listed using the getVMs()
method of the Api class.

Procedure 3.1. 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();

3.3. 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 3.2. Modifying the Attributes of a Resource

1. Declare an instance of the resource whose attributes are to be modified:

VM vm = api.getVMs().get("test");

2. Set the new value of the attribute:

vm.setDescription("java_sdk");

7
Java SDK Guide

3. Update the virtual machine to apply the change:

VM newVM = vm.update();

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

3.5. ADDING RESOURCES

The following examples outline two ways to add resources to the Red Hat Enterprise 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();

8
 CHAPTER 3. USING THE SOFTWARE DEVELOPMENT KIT

templateParam.setName("myTemplate");
vmParams.setTemplate(templateParam);
...

VM vm = api.getVMs().add(vmParams);

3.6. 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 3.3. Performing an Action on a Resource

1. Declare an instance of the resource:

VM vm = api.getVMs().get("test");

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

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

3.7. 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 3.4. Listing Sub-Resources

1. Declare an instance of the resource whose sub-resources are to be listed:

VM vm = api.getVMs().get("test");

2. List the sub-resources:

List<VMDisk> disks = vm.getDisks().list();

9
Java SDK Guide

3.8. 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 3.5. Getting the Sub-Resources of a Resource

1. Declare an instance of the resource whose sub-resources are to be referenced:

VM vm = api.getVMs().get("test");

2. Declare an instance of the sub-resource to be referenced:

VMDisk disk = vm.getDisks().get("my disk");

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

Procedure 3.6. Adding a Sub-Resource to a Resource

1. Declare an instance of the resource to which sub-resources are to be added:

VM vm = api.getVMs().get("test");

2. Create parameters to define the attributes of the resource:

Disk diskParam = new Disk();

diskParam.setProvisionedSize(1073741824L);
diskParam.setInterface("virtio");
diskParam.setFormat("cow");

3. Add the sub-resource:

Disk disk = vm.getDisks().add(diskParam);

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

Procedure 3.7. Updating a Sub-Resource

1. Declare an instance of the resource whose sub-resource is to be modified:

VM vm = api.getVMs().get("test");

2. Declare an instance of the sub-resource to be modified:

10
 CHAPTER 3. USING THE SOFTWARE DEVELOPMENT KIT

VMDisk disk = vm.getDisks().get("test_Disk1");

3. Set the new value of the attribute:

disk.setAlias("test_Disk1_updated");

4. Update the sub-resource:

VMDisk updateDisk = disk.update();

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

Procedure 3.8. Performing an Action on a Sub-Resource

1. Declare an instance of the resource containing the sub-resource on which the action is to be
performed:

VM vm = api.getVMs().get("test");

2. Declare an instance of the sub-resource:

VMDisk disk = vm.getDisks().get("test_Disk1");

3. Declare action parameters to send to the sub-resource:

Action actionParam = new Action();

4. Perform the action:

Action result = disk.activate(actionParam);

11
Java SDK Guide

APPENDIX A. APIBUILDER METHODS

The following table outlines the key methods available to the ApiBuilder class.

Table A.1. ApiBuilder Methods

Method Argument Type Description

user String The name of the user with which to connect to the
Manager. You must specify both the user name and
domain, such as admin@internal. This method
must be used together with the password method.

password String The password of the user with which to connect to

the Manager.

sessionID String The identifier of a session with which to connect to

the Manager. If you have already authenticated with
the Manager and a session is available, you can
specify this argument instead of specifying a user
name and password.

requestTimeout Integer The timeout, in seconds, to wait for responses to

requests. If a request takes longer than this value to
respond, the request is cancelled, and an exception
is thrown. This argument is optional.

sessionTimeout Integer The timeout, in minutes, after which an active

session is destroyed if no requests are made to the
Manager. This argument is optional.

persistentAuth Boolean Enables or disables persistent authentication using

cookies. This option is enabled by default, so this
method is only required to disable this option.

noHostVerificati Boolean Enables or disables verification of the host name in

on the SSL certificate presented by the server where
the Manager is hosted. By default, the identity of
host names is verified, and the connection is
rejected if the host name is not correct, so this
method is only required to disable this option.

keyStorePath String Specifies the location of a file containing the CA

certificate used to verify the certificate presented
by the server where the Manager is hosted. This
method must be used together with the
keyStorePassword method.

keyStorePassword String The password used to access the keystore file

specified in the keyStorePath method.

12
 APPENDIX A. APIBUILDER METHODS

Method Argument Type Description

filter Boolean Enables or disables filtering of objects based on the

permissions of the user making the request. By
default, this option is disabled, which allows any user
to see all objects in the environment. This method is
only required to restrict the objects in the
environment to those visible to the user making the
request.

debug Boolean Enables or disables debug output. By default, this

option is disabled.

13
Java SDK Guide

APPENDIX B. REVISION HISTORY

Revision 3.6-4 Wed 25 May 2016 Red Hat Enterprise Virtualization
Documentation Team
BZ#1325323 - Updated instructions for configuring SSL and connecting to the Manager.
BZ#1317129 - Updated instructions for authenticating via a session identifier.

Revision 3.6-3 Mon 22 Feb 2016 Red Hat Enterprise Virtualization

Documentation Team
Initial revision for Red Hat Enterprise Virtualization 3.6 general availability.

Revision 3.6-2 Wed 18 Nov 2015 Red Hat Enterprise Virtualization

Documentation Team
Final revision for Red Hat Enterprise Virtualization 3.6 beta.

Revision 3.6-1 Mon 10 Aug 2015 Red Hat Enterprise Virtualization

Documentation Team
Initial creation for the Red Hat Enterprise Virtualization 3.6 release.

14