Red Hat Training
A Red Hat training course is available for Red Hat Virtualization
Java SDK Guide
Using the Red Hat Virtualization Java SDK
Abstract
Chapter 1. Overview
-
Version 3
- The V3 Java software development kit provides backwards compatibility with the class and method structure provided in the Java software development kit as of the latest release of Red Hat Enterprise Virtualization 3.6. Applications written using the Java software development kit from Red Hat Enterprise Virtualization 3.6 can be used with this version without modification.
-
Version 4
- The V4 Java software development kit provides an updated set of class and method names and signatures. Applications written using the Java software development kit from Red Hat Enterprise Virtualization 3.6 must be updated before they can be used with this version.
1.1. Prerequisites
- A system where Red Hat Enterprise Linux 7 is installed. Both the Server and Workstation variants are supported.
- A subscription to Red Hat Virtualization entitlements.
Important
1.2. Installing the Java Software Development Kit
Procedure 1.1. Installing the Java Software Development Kit
- Enable the required channels:
# subscription-manager repos --enable=rhel-7-server-rpms # subscription-manager repos --enable=rhel-7-server-rhv-4.0-rpms # subscription-manager repos --enable=jb-eap-7.0-for-rhel-7-server-rpms
- Install the required packages:
- For V3:
# yum install ovirt-engine-sdk-java ovirt-engine-sdk-javadoc
- For V4:
# yum install java-ovirt-engine-sdk4
/usr/share/java/rhevm-sdk-java
directory, and can now be added to Java projects.
1.3. Dependencies
commons-beanutils.jar
commons-codec.jar
httpclient.jar
httpcore.jar
jakarta-commons-logging.jar
log4j.jar
/usr/share/java
directory on Red Hat Enterprise Linux 6 and Red Hat Enterprise Linux 7 systems.
1.4. Configuring SSL
1.4.1. Configuring SSL
Procedure 1.2. Configuring SSL
- Download the certificate used by the Red Hat Virtualization Manager.
Note
By default, the location of the certificate used by the Red Hat Virtualization Manager is in/etc/pki/ovirt-engine/ca.pem
. - Create a truststore:
$ keytool -import -alias "server.crt truststore" -file ca.crt -keystore server.truststore
- Specify the
trustStoreFile
andtrustStorePassword
arguments when constructing an instance of theApi
orConnection
object:myBuilder.trustStoreFile("/home/username/server.truststore"); myBuilder.trustStorePassword("p@ssw0rd");
Note
If you do not specify thetrustStoreFile
option when creating a connection, the Java SDK attempts to use the default truststore specified by the system variablejavax.net.ssl.trustStore
. If this system variable does not specify a truststore, the Java SDK attempts to use a truststore specified in$JAVA_HOME/lib/security/jssecacerts
or$JAVA_HOME/lib/security/cacerts
.
1.4.2. Host Verification
Connection
class:
myBuilder.insecure(true);
Important
Chapter 2. Using the Software Development Kit
2.1. Connecting to the Red Hat Enterprise Virtualization Manager in Version 3
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.
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); } } } } }
ApiBuilder
class, see Appendix A, ApiBuilder Methods.
Note
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
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.
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 } } }
ConnectionBuilder
class, see Appendix B, ConnectionBuilder Methods.
2.3. Listing Entities
getVMs()
method of the Api
class.
Procedure 2.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();
2.4. Modifying the Attributes of Resources
Procedure 2.2. 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
name
, and UUID
. Both return an object with the specified attribute if that object exists.
name
attribute:
VM vm = api.getVMs().get("test");
UUID
attribute:
VM vm = api.getVMs().get(UUID.fromString("5a89a1d2-32be-33f7-a0d1-f8b5bc974ff6"));
2.6. Adding Resources
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);
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
Procedure 2.3. 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);
Action res = vm.start(new Action() { { setVm(new org.ovirt.engine.sdk.entities.VM()); } });
2.8. Listing Sub-Resources
Procedure 2.4. 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();
2.9. Getting Sub-Resources
Procedure 2.5. 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.10. Adding Sub-Resources to a Resource
Procedure 2.6. 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.11. Modifying Sub-Resources
Procedure 2.7. 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.12. Performing Actions on Sub-Resources
Procedure 2.8. 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);
Appendix A. ApiBuilder Methods
ApiBuilder
class used in V3 of the Java software development kit.
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. |
noHostVerification | Boolean | Enables or disables verification of the host name in 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. |
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. |
Appendix B. ConnectionBuilder Methods
ConnectionBuilder
class used in V4 of the Java software development kit.
Table B.1. ConnectionBuilder 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. |
compress | Boolean | Specifies whether responses from the server where the Manager is hosted should be compressed. This option is disabled by default, so this method is only required to enable this option. |
timeout | 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. |
ssoUrl | String | The base URL of the server where the Manager is hosted. For example, https://server.example.com/ovirt-engine/sso/oauth/token?\grant_type=password&scope=ovirt-app-api for password authentication. |
ssoRevokeUrl | String | The base URL of the SSO revoke service. This option only needs to be specified when you use an external authentication service. By default, this URL is automatically calculated from the value of the url option so that SSO token revoke is performed using the SSO service that is part of the engine. |
ssoTokenName | String | The token name in the JSON SSO response returned from the SSO server. By default, this value is access_token . |
insecure | Boolean | Enables or disables verification of the host name in 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. |
trustStoreFile | 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 trustStorePassword method. |
trustStorePassword | String | The password used to access the keystore file specified in the trustStorePath method. |