Skip to content

README.adoc

Latest commit

 

History

History
156 lines (116 loc) · 5.25 KB

README.adoc

File metadata and controls

156 lines (116 loc) · 5.25 KB
Raw

oVirt Engine API Java SDK

Introduction

This project contains the Java SDK for the oVirt Engine API.

Important

If you plan to use the SDK with Maven, then you don’t need to build it from source, as it is distributed via Maven Central in binary form, already built. All you need to do is include the correct dependency in your pom.xml file:

<dependency>
  <groupId>org.ovirt.engine.api</groupId>
  <artifactId>sdk</artifactId>
  <version>4.0.3</version>
</dependency>

If you want to build the SDK from source, you must take into account that most of the code of this SDK is automatically generated. Follow the instructions in the README.adoc file of the parent directory to generate and build it.

Note
 This example uses version 4.0.3, but there may be newer versions available. Check here to see the complete list of available versions, as well as information on how to use it with other build tools.

Usage

To use the SDK import the org.ovirt.engine.sdk4 package. That will give you Connection class. This is the entry point of the SDK, access to all the classes of th SDK, and in particular to the and gives you access to the root of the tree of services of the API:

import org.ovirt.engine.sdk4.Connection;
import static org.ovirt.engine.sdk4.ConnectionBuilder.connection;
import org.ovirt.engine.sdk4.services.SystemService;

// Create a connection to the server:
Connection connection = connection()
  .url("https://engine.example.com/ovirt-engine/api")
  .user("admin@internal")
  .password("...")
  .trustStoreFile("truststore.jks")
  .build();

// Get the reference to the system service:
SystemService systemService = connection.systemService();

// Always remember to close the connection when finished:
connection.close();

The truststore.jks file is required when connecting to a server protected with TLS. In an usual oVirt installation it will be in /etc/pki/ovirt-engine/.truststore. The default password for keystore is mypass. If you don’t specify trustStoreFile, then default Java trust store location is used, which is defined by javax.net.ssl.trustStore system property.

Once you have the reference to the system service you can use it to get references to other services, and call their methods. For example, to retrieve the list of virtual machines of the system you can use the vmsService() method, which returns a reference to the service that manages the virtual machines:

import org.ovirt.engine.sdk4.services.VmsService;

// Get the reference to the "vms" service:
VmsService vmsService = systemService.vmsService()

This service is an instance of VmsService, and it has a list method that returns an array of virtual machines, which are instances of the Vm class:

import java.util.List;
import org.ovirt.engine.sdk4.types.Vm;

// Retrieve the virtual machines:
List<Vm> vms = vmsService.list().send().vms();

// Print the names and identifiers of the virtual machines:
for (Vm vm : vms) {
    System.out.printf("%s: %s%n", vm.id(), vm.name());
}

You will find more usuage examples in the examples directory.

Releasing

The project is released to Maven Central using the Central Publishing Maven Plugin.

To perform a release you will need to do the following actions, most of them automated by the Maven release plugin:

Prepare the release

This is automated using the Maven release plugin:

$ mvn release:prepare

This will ask you the version numbers to use for the released artifacts and the version numbers to use after the release. The release version numbers will be something like 4.0.5, and the version numbers after the release will be something like 4.0.6-SNAPSHOT. You should use the defaults unless there is a very good reason to change them.

The result will be two new patches, and a tag added to the local repository. These patches and tag will not be pushed automatically to the remote repository, so you need to do it manually, first the patches:

$ git push origin HEAD:refs/for/master

This will send the patches for review to github. Go there, review and merge them. Once the patches are merged the tag can be pushed:

$ git push origin 4.0.5

This tag is important so that the release tools notice that a new version has been released.

Perform the release

This is also automated using the Maven release plugin. But in this case it is necessary to sign the artifacts, as Maven Central requires signed artifacts. To sign artifacts and generate the documentation the sign and document profiles need to be activated:

$ mvn release:perform -Psign,document
Note
 The artifacts will be signed using your default GPG key, so make sure you have a valid GPG key available.

This will build the code from the repository where it is triggered, run the tests and, finally, if everything succeeds, it will upload the signed artifacts to the Maven Central repository.

The rest of the process is manual, using the Central Sonatype web interface available here. Information about this publishing can be found here.