Chapter 1 Oracle VM Web Services Overview
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 fromreturn
toeventTypes
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.
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_
,
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.
username
.properties
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