JavaScript must be enabled to correctly display this content

Chapter 1 Oracle VM Web Services Overview

Table of Contents

The Oracle VM Web Services Application Programming Interface (API) provides a Web Services interface for building applications with Oracle VM. Both SOAP and REST interfaces are supported. Both offer the same underlying functionality; however, the SOAP interface is deprecated as of release 3.4.1. Mixing SOAP and REST based interactions in the same application is not supported and may cause unexpected results.

The Web Services API allows you to write applications to customize, control, and automate Oracle VM. For example, you can

Create, start, restart and stop virtual machines, and migrate them between different Oracle VM Servers.
Expand the capacity of the Oracle VM environment by adding more Oracle VM Servers and storage providers.
Integrate Oracle VM with other third-party tools such as monitoring applications
Facilitate repetitive tasks like creating new instances of frequently deployed virtual machines from templates, switching between policies or turning them on or off depending on the time of the day or week, performing maintenance on the hardware or virtualized environment, and so on.

This guide introduces you to the Oracle VM Web Services API, providing the basic concepts and API examples. For the complete API documentation, see the Oracle VM Web Services API documentation included in the SDK on the Oracle VM Manager installation ISO.

The Web Services API to Oracle VM can be accessed using any programming language. The general interaction pattern with the API is to first find an object, retrieve a client-side instance of the object, and then execute certain authorized manipulations.

An object must be retrieved by its ID. These object IDs can be obtained via other related objects, or in some cases by requesting a list of all object IDs of a given type. Once the ID is available, various operations can be performed on the object. The exact set of operations depends on the type of object.

Operations that are not simple retrievals are performed asynchronously. These methods return a Job object that can be used to subsequently query the status of the operation. In case the operation is an object creation, the Job object, once completed, will also include the ID of the created object so that other operations can be performed on this object.

1.1 Changes to the Oracle VM Web Services API in Release 3.4

Changes in the Oracle VM Web Services API in Release 3.4 include the following:

SOAP API is deprecated as of Release 3.4 and will be removed in a future version. Oracle recommends that you use the REST web service for any client application.
Virtual IP addresses are deprecated. You can configure a virtual IP address to maintain backwards compatibility with a previous release of Oracle VM Server.
Virtual appliances replace assemblies. In previous releases of Oracle VM Manager, virtual appliances were referred to as assemblies. To maintain backwards compatibility, Oracle VM Web Services API uses the term assembly throughout the code. However the Oracle VM Manager Web Interface and Oracle VM Manager Command Line Interface use the term virtual appliance.
The member variable in the response class for the eventGetTypes call in the SOAP API was changed from return to eventTypes in Oracle VM Release 3.3.3. If you have client code written for the SOAP API using the WSDL or client library, OvmWsClient.jar, the parser for this call might fail.

Important

If you have created client applications to use the Oracle VM Web Services API, you should review the changes in Release 3.4 to evaluate how they affect runtime functionality. In some cases, changes and improvements to the underlying Oracle VM implementation might require you to update your client code to account for behavior changes, such as a new rule exception, and then re-compile and deploy your application before returning to production capability.

1.2 Using the Oracle VM Web Services SDK

The Oracle VM Web Services SDK is included on the Oracle VM Manager installation ISO, compressed in zip format. To access the SDK, copy the zip file from the mounted ISO to a working directory and unzip it.

The SDK contains all of the resources that you need to get started developing to the Oracle VM Web Services API:

Full documentation of the Web Services API as exposed by the provided library and sample source code.
An Oracle VM web services client library.
Sample Java source code that can be used to get started building your own client application.

1.3 Using the Oracle VM Web Services Client Library and Sample Code

Since Oracle VM Manager provides a generic REST API, you are able to use this documentation to develop your own code to directly interact with the API based on your understanding of REST and the methods that are supported by the exposed API. However, the Oracle VM Web Services SDK includes a Java client library and example Java source code that can dramatically reduce the amount of work that you need to do to code an application that uses the API. The example code also includes a number of utilities that are useful when working with an API, but which are not part of the API itself. For this reason, it is recommended that you take advantage of the provided code and library when programming a Java application that interfaces with Oracle VM Manager.

In this guide, we take a closer look at the Oracle VM Web Services Client Library and how it is commonly used. Full coverage of the methods supported by the library can be found in the documentation included with the SDK.

To get started using the SDK, you can import the source code provided into a new Java project within your preferred IDE. The SDK requires that you use the Oracle JDK 7 for your project. JDK 6 is not supported.

You must add the provided client library, OvmWsClient.jar, to your project to compile the source code. Additionally, the example source code makes use of some external libraries, such as the Jersey Bundle to handle calls to the REST API. While you are free to choose any other tools to create your own application, the example source code requires this library to compile as the example code is capable of being configured to use either the REST API or the deprecated SOAP API when it runs. Information on downloading and installing the Jersey Bundle is provided in About the Java samples provided.

The sample code includes a properties file called WsDevClient.properties. This file contains the default values used for different variables defined in the code. In most cases, many of these variable values must be overridden for your own environment. For values that you wish to override, create a file in the same directory, named WsDevClient_username.properties, where username matches the username that you use to log into the environment where you intend to compile the code. Note that this properties file is only required for the sample client and is not required when building your own application using the provided libraries.

If the value for wsimpl variable, defined in your properties file, is set to SOAP and debugHttpTraffic is set to true, the output from the sample code includes all of the SOAP interactions that the sample client application performs, including the HTTP headers and the SOAP messages exchanged within the body of each request. Remember that the SOAP API is deprecated in Oracle VM Manager 3.4.

If the value for wsimpl variable, defined in your properties file, is set to REST and debugHttpTraffic is set to true, the output from the sample code includes all of the REST interactions that the sample client application performs, including the XML or JSON body content and the HTTP headers. This allows you to watch the actual HTTP requests that are involved in an interaction between a client and Oracle VM Manager, and can help you to understand the underlying code within the client.

Once the code has been compiled, you can run it easily from the command line using:

java -cp wsclient.jar com.oracle.ovm.mgr.ws.sample.WsDevClient