Skip to content

Latest commit

 

History

History
162 lines (123 loc) · 5.76 KB

README.adoc

File metadata and controls

162 lines (123 loc) · 5.76 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 via the Sonatype OSSRH repository.

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 gerrit. Go there, review and merge them. Once the patches are merged the tag can be pushed:

$ git push origin 4.0.5

Perform the release

This is also automated using the Maven release plugin. But in this case it is necessary to sign the artifacts, as both Sonatype OSSRH and Maven Central require signed artifacts. To sign artifacts and generate the documentation the 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 use the tag to checkout the code from the remote repository, it will build it, run the tests and, finally, if everything succeeds, it will upload the signed artifacts to the OSSRH repository.

The rest of the process is manual, using the OSSRH web interface available here. Log in with your user name and password and select the Staging Repositories option. Then use the search bar in the top right corner to search for ovirt. In the result list you should see you repository, and in the panel below you should see the details, including the contents of the repository. Inspect those contents, and when you are satisfied click the Close button. Wait a bit, maybe clicking the Refresh button a few times, till the Release button is enabled. Click the Release button, it will ask for a message, write something like Release 4.0.5 and then OK. The release is now ready, and it will be propagated to Maven Central later, it usually takes around 30 minutes.