Feature pages are design documents that developers have created while collaborating on oVirt.

Most of them are outdated , but provide historical design context.

They are not user documentation and should not be treated as such.

Documentation is available here.

Java-sdk

The oVirt Java-SDK is an automatically generated software development kit for the oVirt engine API. This software development kit allows you to develop Java-based applications for automating a variety of complex administrative tasks in oVirt.

TOC

Concepts

  • Auto-Generated
  • Complete protocol abstraction.
  • Full compliance with the oVirt api architecture.
  • Self descriptive.
  • Intuitive and easy to use.

IDE Examples

Creating the proxy:


Authenticating using user name and password:

Authenticating using sessionid:

Listing all collections:


Listing the methods of a collection:


Querying a collection using a oVirt search engine query and custom constraints:


Accessing resource methods and properties:


Creating a resource:


Accessing resource properties and sub-collections:


Accessing sub-collection methods:


Querying a sub-collection using custom constraints:


TBD

Retrieving a sub-collection resource:


Accessing sub-collection resource properties and methods:


Examples

create proxy

     // #1 - import
     import org.ovirt.engine.sdk.Api;

     // #2 - create proxy
     Api api = new Api("`[`http://localhost:8080/api`](http://localhost:8080/api)`", "user@domain", "password");

list entities

     // #1 - list resources
     List`<VM>` vms = api.getVMs().list();

update resource

     // #1 - fetch resource
     VM vm = api.getVMs().get("test");

     // #2 - modify it
     vm.setDescription("java_sdk");

     // #3 - update it
     VM newVM = vm.update();

get resource by name

     // #1 - fetch resource using name
     VM vm = api.getVMs().get("test");

get resource by id

     // #1 - fetch resource using id
     VM vm = api.getVMs().get(UUID.fromString("5a89a1d2-32be-33f7-a0d1-f8b5bc974ff6"));

add resource

     // #1 - create parameters
     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"));

     // #2 - add resource
     VM vm = api.getVMs().add(vmParams);

     or

     // #1 - create parameters
     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);

     // #2 - add resource
     VM vm = api.getVMs().add(vmParams);

perform an action on resource

     // #1 - fetch resource
     VM vm = api.getVMs().get("test");

     // #2 - create params
     Action actionParam = new Action();
     org.ovirt.engine.sdk.entities.VM vmParam = new org.ovirt.engine.sdk.entities.VM();
     actionParam.setVm(vmParam);

     // #3 - perform an action
     Action res = vm.start(actionParam);

     or

     // #1 - fetch resource
     VM vm = api.getVMs().get("test");

     // #2 - create params + perform an action
     Action res = vm.start(new Action() {
         {
             setVm(new org.ovirt.engine.sdk.entities.VM());
         }
     });

list sub-resources

     // #1 - fetch resource
     VM vm = api.getVMs().get("test");

     // #2 - list sub-resources
     List`<VMDisk>` disks = vm.getDisks().list();  

get sub-resource

     // #1 - fetch resource
     VM vm = api.getVMs().get("test");

     // #2 - fetch sub-resource
     VMDisk disk = vm.getDisks().get("my disk");

add sub-resource to resource

     // #1 - fetch resource
     VM vm = api.getVMs().get("test");

     // #2 - create parameters
     Disk diskParam = new Disk();
     diskParam.setProvisionedSize(1073741824L);
     diskParam.setInterface("virtio");
     diskParam.setFormat("cow");

     // #3 - add sub-resource
     Disk disk = vm.getDisks().add(diskParam);

update sub-resource

     // #1 - fetch resource
     VM vm = api.getVMs().get("test");

     // #2 - fetch sub-resource
     VMDisk disk = vm.getDisks().get("test_Disk1");

     // #3 - modify sub-resource
     disk.setAlias("test_Disk1_updated");

     // #4 - update it
     VMDisk updateDisk = disk.update();

run action on sub-resource

     // #1 - fetch resource
     VM vm = api.getVMs().get("test");

     // #2 - fetch sub-resource
     VMDisk disk = vm.getDisks().get("test_Disk1");

     // #3 - create parameters
     Action actionParam = new Action();

     // #4 - run an action on sub-resource
     Action result = disk.activate(actionParam);

Best Practices

The api should be shutdown in a finally block so daemon resources are freed:

   Api api = new Api(URL, USER, PASSWORD);
   try {
       api.api.getDataCenters().add(new DataCenter());
       ...
   } finally {
       api.shutdown();
   }

Working with SSL (Secure Socket Layer)

The oVirt Java software development kit provides full support for HTTP over Secure Sockets Layer (SSL) or IETF Transport Layer Security (TLS) protocols by leveraging the Java Secure Socket Extension (JSSE). JSSE has been integrated into the Java 2 platform as of version 1.4 and works with Java-SDK out of the box. On older Java 2 versions, JSSE must be manually installed and configured. Installation instructions can be found at here.

Once you have correctly installed JSSE, secure HTTP communication over SSL should be as simple as plain HTTP communication. However, you must supply the Java software development kit with a KeyStore containing the host CA certificate to validate the destination host identity:

Generating the truststore

1 Download oVirt host CA certificate from

   https://host:port/ca.crt

  1. Generate keystore

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

Make Java-SDK aware of the keystore

this can be achieved in one of two ways:

  1. Via default keystore lookup path

       mkdir ~/.ovirtsdk/    cp server.truststore ~/.ovirtsdk/ovirtsdk-keystore.truststore

Once the ovirtsdk-keystore.truststore installed in the ~/.ovirtsdk, it will be used for host identity validation upon handshake with the destination host.

  1. Via a custom truststore

Use this signature: Api(String url, String username, String password, String keyStorePath)

     Api api = new Api(url, user, password, "/path/server.truststore");

Disable host identity validation

This method SHOULD NOT be used for productive systems due to security reasons, unless it is a conscious decision and you are perfectly aware of security implications of not validating host identity.

use this signature: Api(String url, String username, String password, boolean noHostVerification)

     Api api = new Api(url, user, password, true);

Deployment

Maven deployment

  1. add mvn-releases repository to your ~/.m2/settings.xml under

    `       ``mvn-releases` `       `[`https://oss.sonatype.org/content/repositories/releases`](https://oss.sonatype.org/content/repositories/releases) `       ` `       ` `       ` `           ``false` `       ` `   `

  1. add sdk dependency to your project pom.xml

    `       ``org.ovirt.engine.sdk` `       ``ovirt-engine-sdk-java` `       ``x.y.z.q-v` `       ``jar` `       ``compile` `   `

         "x.y.z.q-v" is a latest sdk release (list of available releases can be found at `[`java-sdk-changelog`](java-sdk-changelog)`)
  1. deploy sdk dependencies and javadoc

         mvn dependency:resolve -Dclassifier=javadoc

  2. compile

          mvn clean install

Development deployment

Code generation

       1. pull + compile + deploy latest ovirt-engine sources
       2. cd ovirt-engine-sdk-java-codegen
       3. compile
       4. run (this will generate sdk from the ovirt-engine)

Development

       all SDK development is done on the ovirt-engine-sdk-java-codegen project,
       i.e if you have yet not supported funcionality in SDK, this is a place to add
       support for it.

TODO list

  1. generate entry-point (/api) methods (done)

  2. generate searchable list() methods (done)

  3. generate method/s overloads using header/url params (done)

  4. generate delete method/s overloads with body (done)

  5. support persistent authentication (done)

  6. implement SSL support (done)

  7. implement SSL CA certificate validation (done)

  8. implement client validation

  9. allow setters generation for collection based fields in org.ovirt.engine.sdk.entities

  10. implement in collection.get(name) search using engine.search

  11. implement timeout in SDK constructor

  12. implement sdk debug mode (done)

  13. remove @SuppressWarnings("unused") from decorators

  14. move get/list methods from the decorators to the parent classes

  15. implement unique treatment for COLLECTION2ENTITY pattern exceptions (in-progress)

  16. implement logger in codegen

  17. add deployment capabilities (done)

  18. upload artifacts to mvn repo (done)

  19. Implement querying collections using custom constraint.

  20. in doc change parameters format to javaDoc style (done)

  21. make API.java thread safe (done)

Change Log

java-sdk-changelog

Maintainers

Michael Pasternak: mishka8520@yahoo.com, Juan Hernandez: juan.hernandez@redhat.com