= 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 http://central.maven.org/maven2/org/ovirt/engine/api/sdk[Maven Central]
in binary form, already built. All you need to do is include the correct dependency
in your `pom.xml` file:

[source,xml]
----
<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 http://search.maven.org/#search|gav|1|g:%22org.ovirt.engine.api%22%20AND%20a:%22sdk%22[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:

[source,java]
----
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:

[source,java]
----
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:

[source,java]
----
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 https://gerrit.ovirt.org[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 https://oss.sonatype.org[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.
