- 3.5.1 Authenticating
- 3.5.2 Checking Oracle VM Manager Run State
- 3.5.3 Listing Servers
- 3.5.4 Discovering Servers
- 3.5.5 Working with Jobs
- 3.5.6 Creating a Server Pool
- 3.5.7 Clustering
- 3.5.8 Managing Servers in a Server Pool
- 3.5.9 Discovering a Network File Server
- 3.5.10 Creating a Storage Repository
- 3.5.11 Presenting a Storage Repository
- 3.5.12 Creating Networks
- 3.5.13 Creating Virtual Machines
- 3.5.14 Importing Assemblies
The example code, provided in this section, steps through many common operations within Oracle VM Manager. For each example, we have provided code samples for both Java and Python. By nature, the SOAP API is language agnostic, so you may decide to use an alternative programming language to interface with the API. The code samples are provided to show how different operations might be performed using one of these two popular languages.
In a guide like this, the programming style and the choice of libraries used very much depend on the author and the version of the language used. More than likely, there are many more ways to achieve the same result, even within the same language. These samples are not intended to be authoritative in their approach, but can be used as guidelines to developing your own applications.
Notes on the Java samples provided in these examples
Our Java samples are built around the Java code and library provided in the SDK that is bundled with Oracle VM Manager.
The Java Sample Client provided in the SDK includes all of the code required to perform the majority of supported interactions with the WS-API. The code is separated into two packages:
com.oracle.ovm.mgr.ws.client: Contains the classes for both the REST and SOAP interfaces to the API. Notably, for these examples, the OvmWsSoapClient.java file contains much of the code referenced through this guide. In this guide, we attempt to describe how the actual client API code has been constructed to allow you to abstract many of the SOAP calls that you would need to make otherwise. In practice, you can use these classes without needing to know all of the underlying mechanics to the code, this is illustrated in the WSDevClient class discussed below.com.oracle.ovm.mgr.ws.sample: Contains the WsDevClient class, which performs particular actions using the API and which is set as your main class when you run the sample client. The WsDevClient class is an example of how you can use the client API classes to create your own applications drawing on all the abstraction provided by these classes. If you're just following this guide to work out how to use the API to write your own applications, you can concentrate on the code in the WsDevClient class.
The SDK also includes the Oracle VM Manager Web Services Client library in
the form of a precompiled jar file called
OvmWsClient.jar. This library contains models
for all of the different ObjectTypes exposed through the API, as
well as a variety of utilities that are useful to perform various
actions on objects in the API. The SOAP API can be easily
abstracted by using the methods provided within this library. This
library must be included in your project to allow you to work with
typical Oracle VM ObjectTypes.
Your code should import the models, that you intend to use, as they are described in the Web Services Client library. Typically, a full-scale Java IDE should handle this on your behalf when you import the library and as you make use of different models. The listing presented is provided for completeness. The following listing provides a full outline of model imports:
import com.oracle.ovm.mgr.ws.model.AccessGroup; import com.oracle.ovm.mgr.ws.model.AffinityGroup; import com.oracle.ovm.mgr.ws.model.Assembly; import com.oracle.ovm.mgr.ws.model.AssemblyVirtualDisk; import com.oracle.ovm.mgr.ws.model.AssemblyVm; import com.oracle.ovm.mgr.ws.model.BaseObject; import com.oracle.ovm.mgr.ws.model.CloneType; import com.oracle.ovm.mgr.ws.model.Cluster; import com.oracle.ovm.mgr.ws.model.ClusterHeartbeatDevice; import com.oracle.ovm.mgr.ws.model.ClusterStorageFs; import com.oracle.ovm.mgr.ws.model.ControlDomain; import com.oracle.ovm.mgr.ws.model.Cpu; import com.oracle.ovm.mgr.ws.model.CpuCompatibilityGroup; import com.oracle.ovm.mgr.ws.model.EthernetPort; import com.oracle.ovm.mgr.ws.model.Event; import com.oracle.ovm.mgr.ws.model.FileServer; import com.oracle.ovm.mgr.ws.model.FileServerPlugin; import com.oracle.ovm.mgr.ws.model.FileSystem; import com.oracle.ovm.mgr.ws.model.FileSystemMount; import com.oracle.ovm.mgr.ws.model.FsAccessGroup; import com.oracle.ovm.mgr.ws.model.Id; import com.oracle.ovm.mgr.ws.model.Job; import com.oracle.ovm.mgr.ws.model.LoggerManagementAttributes; import com.oracle.ovm.mgr.ws.model.LoginCertificate; import com.oracle.ovm.mgr.ws.model.Manager; import com.oracle.ovm.mgr.ws.model.Network; import com.oracle.ovm.mgr.ws.model.PeriodicTask; import com.oracle.ovm.mgr.ws.model.Repository; import com.oracle.ovm.mgr.ws.model.RepositoryExport; import com.oracle.ovm.mgr.ws.model.ResourceGroup; import com.oracle.ovm.mgr.ws.model.Server; import com.oracle.ovm.mgr.ws.model.ServerController; import com.oracle.ovm.mgr.ws.model.ServerPool; import com.oracle.ovm.mgr.ws.model.ServerPoolNetworkPolicy; import com.oracle.ovm.mgr.ws.model.ServerPoolPolicy; import com.oracle.ovm.mgr.ws.model.ServerUpdateConfiguration; import com.oracle.ovm.mgr.ws.model.ServerUpdateRepositoryConfiguration; import com.oracle.ovm.mgr.ws.model.SimpleId; import com.oracle.ovm.mgr.ws.model.Statistic; import com.oracle.ovm.mgr.ws.model.StorageArray; import com.oracle.ovm.mgr.ws.model.StorageArrayPlugin; import com.oracle.ovm.mgr.ws.model.StorageElement; import com.oracle.ovm.mgr.ws.model.StorageInitiator; import com.oracle.ovm.mgr.ws.model.StoragePath; import com.oracle.ovm.mgr.ws.model.StorageTarget; import com.oracle.ovm.mgr.ws.model.VirtualDisk; import com.oracle.ovm.mgr.ws.model.VirtualNic; import com.oracle.ovm.mgr.ws.model.VirtualSwitch; import com.oracle.ovm.mgr.ws.model.VlanInterface; import com.oracle.ovm.mgr.ws.model.Vm; import com.oracle.ovm.mgr.ws.model.VmCloneDefinition; import com.oracle.ovm.mgr.ws.model.VmCloneNetworkMapping; import com.oracle.ovm.mgr.ws.model.VmCloneStorageMapping; import com.oracle.ovm.mgr.ws.model.VolumeGroup; import com.oracle.ovm.mgr.ws.model.WsErrorDetails; import com.oracle.ovm.mgr.ws.model.WsException; import com.oracle.ovm.mgr.ws.model.Zone;
You can simplify these imports by simply doing:
import com.oracle.ovm.mgr.ws.model.*;
Additionally, to define how your application connects to the SOAP API and to use the methods provided, you must define the following imports:
import com.oracle.ovm.mgr.ws.client.OvmWsClient; import com.oracle.ovm.mgr.ws.client.OvmWsClientFactory;
You can use the com.oracle.ovm.mgr.ws.client
package within your own projects to reduce your development
overhead.
In these examples, we show how the SOAP client has been
implemented within the
com.oracle.ovm.mgr.ws.client package, and
also how it is used for particular actions in the WsDevClient
class.
The code included in the library expects that you are using JDK 7. Ensure that your project Source/Binary format is set to JDK7 and that you have the JDK7 libraries imported into your project. JDK 6 is not supported.
Notes on the Python samples provided in these examples
Our Python samples are intended to give the reader a feel for direct interaction with the API for the purpose of scripting quick interactions with Oracle VM Manager.
To keep the code simple, we have opted to make use of the latest stable version of the popular Python Suds (0.4.1) library to provide a complete SOAP client that can interact directly with the SOAP interface exposed by Oracle VM Manager's Web Services API. Your Python scripts should have at minimum, the following import defined:
from suds.client import Client
To properly use the Suds client library, you must provide the URL to the WSDL to the client when you instantiate an instance:
url = "https://localhost:7002/ovm/core/wsapi/soap?wsdl" client=Client(url)
The url specified above follows the format described
in Section 3.1, “Connecting To The SOAP API”. It may vary
depending on your own environment and where you intend your script
to run from.
Once the WSDL has been loaded, you are able to inspect the service object to obtain a list of methods provided by the Oracle VM Manager Web Services SOAP API:
print client
Truncated output follows:
Suds ( https://fedorahosted.org/suds/ ) version: 0.4 GA build: R699-20100913
Service ( OvmApi ) tns="http://ws.mgr.ovm.oracle.com/"
Prefixes (2)
ns0 = "http://ws.mgr.ovm.oracle.com/"
ns1 = "http://www.w3.org/2005/08/addressing"
Ports (1):
(OvmApiPort)
Methods (420):
accessGroupAddStorageInitiator(id accessGroupId, id storageInitiatorId, )
accessGroupGetAll()
accessGroupGetById(id accessGroupId, )
accessGroupGetIds()
accessGroupGetListById(id[] accessGroupIds, )
accessGroupModify(accessGroup accessGroup, )
accessGroupRemoveStorageInitiator(id accessGroupId, id storageInitiatorId, )
affinityGroupAddServer(id affinityGroupId, id serverId, )
affinityGroupAddVm(id affinityGroupId, id vmId, )
affinityGroupGetAll()
affinityGroupGetById(id affinityGroupId, )
affinityGroupGetIds()
affinityGroupGetListById(id[] affinityGroupIds, )
affinityGroupModify(affinityGroup affinityGroup, )
affinityGroupRemoveServer(id affinityGroupId, id serverId, )
affinityGroupRemoveVm(id affinityGroupId, id vmId, )
assemblyGetAll()
assemblyGetById(id assemblyId, )
assemblyGetIds()
assemblyGetListById(id[] assemblyIds, )
assemblyModify(assembly assembly, )
assemblyRefresh(id assemblyId, )
assemblyVirtualDiskGetAll()
assemblyVirtualDiskGetById(id assemblyVirtualDiskId, )
assemblyVirtualDiskGetIds()
assemblyVirtualDiskGetListById(id[] assemblyVirtualDiskIds, )
assemblyVirtualDiskModify(assemblyVirtualDisk assemblyVirtualDisk, )
assemblyVmGetAll()
assemblyVmGetById(id assemblyVmId, )
assemblyVmGetIds()
assemblyVmGetListById(id[] assemblyVmIds, )
assemblyVmModify(assemblyVm assemblyVm, )
...
vmGetAll()
vmGetById(id vmId, )
vmGetConsoleUrl(id vmId, )
vmGetIds()
vmGetListById(id[] vmIds, )
vmGetSerialConsoleUrl(id vmId, )
vmGetSupportedOsTypes()
vmKill(id vmId, )
vmMigrate(id vmId, id destinationServerId, )
vmModify(vm vm, )
vmMove(id vmId, id repositoryId, id vmCloneDefinitionId, )
vmRestart(id vmId, )
vmResume(id vmId, )
vmSendApiMessage(id vmId, WsKeyValuePair[] message, xs:boolean logFlag, )
vmStart(id vmId, )
vmStop(id vmId, )
vmSuspend(id vmId, )
...
If you experience any trouble using the Suds library, you may decide to import the standard Python logging library and set log levels for components in the Suds library that you are using, to help with any troubleshooting that you need to do:
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.client').setLevel(logging.DEBUG)
logging.getLogger('suds.transport').setLevel(logging.DEBUG)
logging.getLogger('suds.xsd.schema').setLevel(logging.DEBUG)
logging.getLogger('suds.wsdl').setLevel(logging.DEBUG) It is recommended that you refer to the Suds library documentation at:
https://fedorahosted.org/suds/wiki/Documentation
Please also refer to Section 5.2, “Notable Issues for Suds Users” for some common problems that developers using the Suds Library may encounter.
Due to the syntax of some of our example code, we assume that you are using Python 2.6 or above.