diff --git a/src/oca/java/build.sh b/src/oca/java/build.sh index 875f68a438..967aa00e3f 100755 --- a/src/oca/java/build.sh +++ b/src/oca/java/build.sh @@ -76,7 +76,7 @@ do_documentation() -subpackages org.opennebula \ -windowtitle 'OpenNebula Cloud API' \ -doctitle 'OpenNebula Cloud API Specification' \ - -header 'OpenNebula
Java API' \ + -header 'OpenNebula
Cloud API' \ -bottom 'Visit OpenNebula.org
Copyright 2002-2010 © OpenNebula Project Leads (OpenNebula.org).' diff --git a/src/oca/java/share/examples/SessionInit.java b/src/oca/java/share/examples/SessionInit.java index b98c1712df..9bce826bd5 100644 --- a/src/oca/java/share/examples/SessionInit.java +++ b/src/oca/java/share/examples/SessionInit.java @@ -24,22 +24,35 @@ public class SessionInit { try { Client oneClient = new Client(); + System.out.println(" ok"); } catch (Exception e) { System.out.println(e.getMessage()); } - System.out.println("ok"); - System.out.println("Wrong session initialization..."); + System.out.println("Forcing a wrong user/password initialization..."); try { + // The secret string should be user:password. The url is null, so it + // will be set to default. Client oneClient = new Client("wrong_password_token",null); } catch (Exception e) { System.out.println("\t" + e.getMessage()); } + + System.out.println("Forcing a wrong url initialization..."); + try + { + // The HTTP is misspelled + Client oneClient = new Client(null,"HTP://localhost:2633/RPC2"); + } + catch (Exception e) + { + System.out.println("\t" + e.getMessage()); + } } } diff --git a/src/oca/java/share/examples/SessionInit.sh b/src/oca/java/share/examples/SessionInit.sh new file mode 100755 index 0000000000..b362986eaa --- /dev/null +++ b/src/oca/java/share/examples/SessionInit.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +java -cp ../../lib/*:../../jar/*:. SessionInit diff --git a/src/oca/java/share/examples/UserSample.java b/src/oca/java/share/examples/UserSample.java index 8198ae9807..093b601365 100644 --- a/src/oca/java/share/examples/UserSample.java +++ b/src/oca/java/share/examples/UserSample.java @@ -22,6 +22,12 @@ public class UserSample { public static void main(String[] args) { + // Let's try some of the OpenNebula Cloud API functionality. + + // First of all, a Client object has to be created. + // Here the client will try to connect to OpenNebula using the default + // options: the auth. file will be assumed to be at $ONE_AUTH, and the + // endpoint will be set to the environment variable $ONE_XMLRPC. Client oneClient; try @@ -34,17 +40,24 @@ public class UserSample return; } + // We will create a user pool and query some information. + // The info method retrieves and saves internally the information + // from OpenNebula. UserPool userpool = new UserPool(oneClient); OneResponse rc = userpool.info(); + // The response can be an error, in which case we have access to a + // human-readable error message. if (rc.isError()) { System.out.println(rc.getErrorMessage()); return; } + // Let's find out the current state of the users pool printUserPool(userpool); + // Now we will try to allocate a new user System.out.println("Allocating new user (javaUser,javaPassword)..."); rc = User.allocate(oneClient, "javaUser", "javaPassword"); @@ -54,22 +67,44 @@ public class UserSample return; } - User javaUser = new User(Integer.parseInt(rc.getMessage()),oneClient); + // If the allocation was successful, then the response message contains + // the new user's ID. + int userID = Integer.parseInt( rc.getMessage() ); + System.out.println("The allocation request returned this ID: " + userID); + // We can create a representation for the new user, using the returned + // user-ID + User javaUser = new User(userID, oneClient); + + // And request its information rc = javaUser.info(); + // Alternatively we could have requested the user's info with the + // static info method: + // rc = User.info(oneClient, userID); + // and processed the xml returned in the message of the OneResponse. + if (rc.isError()) { System.out.println(rc.getErrorMessage()); return; } + // This is how the info returned looks like... System.out.println("Info for " + javaUser.xpath("name") + "..."); System.out.println(rc.getMessage()); + // Wait a second... what was that xpath method for? + // Now that we have the user's info loaded, we can use xpath expressions + // without parsing and initializing any xml, as simple as + // String name = javaUser.xpath("name"); + + // The user pool information is now outdated, so we need to call the + // info method again userpool.info(); printUserPool(userpool); + // Let's delete this new user, using its ID System.out.println("Deleting " + javaUser.getName() + "..."); rc = javaUser.delete(); @@ -79,6 +114,7 @@ public class UserSample return; } + // Now the pool information is outdated again, it is time to reload it. userpool.info(); printUserPool(userpool); } @@ -89,6 +125,7 @@ public class UserSample System.out.println("Number of users: " + up.getLength()); System.out.println("User ID\t\tName\t\tEnabled"); + // You can use the for-each loops with the OpenNebula pools for( User user : up ) { String id = user.getId(); diff --git a/src/oca/java/share/examples/UserSample.sh b/src/oca/java/share/examples/UserSample.sh new file mode 100755 index 0000000000..c664e0ac4d --- /dev/null +++ b/src/oca/java/share/examples/UserSample.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +java -cp ../../lib/*:../../jar/*:. UserSample diff --git a/src/oca/java/share/examples/VMachineSample.java b/src/oca/java/share/examples/VMachineSample.java new file mode 100644 index 0000000000..9e481b49e3 --- /dev/null +++ b/src/oca/java/share/examples/VMachineSample.java @@ -0,0 +1,185 @@ +/******************************************************************************* + * Copyright 2002-2010, OpenNebula Project Leads (OpenNebula.org) + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + ******************************************************************************/ + +import org.opennebula.client.Client; +import org.opennebula.client.OneResponse; +import org.opennebula.client.vm.VirtualMachine; +import org.opennebula.client.vm.VirtualMachinePool; + +public class VMachineSample{ + + public static void main(String[] args) + { + // Let's try some of the OpenNebula Cloud API functionality for VMs. + + // First of all, a Client object has to be created. + // Here the client will try to connect to OpenNebula using the default + // options: the auth. file will be assumed to be at $ONE_AUTH, and the + // endpoint will be set to the environment variable $ONE_XMLRPC. + Client oneClient; + + try + { + oneClient = new Client(); + + // We will try to create a new virtual machine. The first thing we + // need is an OpenNebula virtual machine template. + + // This VM template is a valid one, but it will probably fail to run + // if we try to deploy it; the path for the image is unlikely to + // exist. + String vmTemplate = + "NAME = vm_from_java CPU = 0.1 MEMORY = 64\n" + + "DISK = [\n" + + "\tsource = \"/home/user/vmachines/ttylinux/ttylinux.img\",\n" + + "\ttarget = \"hda\",\n" + + "\treadonly = \"no\" ]\n" + + "# NIC = [ NETWORK = \"Non existing network\" ]\n" + + "FEATURES = [ acpi=\"no\" ]"; + + // You can try to uncomment the NIC line, in that case OpenNebula + // won't be able to insert this machine in the database. + + System.out.println("Virtual Machine Template:\n" + vmTemplate); + System.out.println(); + + System.out.print("Trying to allocate the virtual machine... "); + OneResponse rc = VirtualMachine.allocate(oneClient, vmTemplate); + + if( rc.isError() ) + { + System.out.println( "failed!"); + throw new Exception( rc.getErrorMessage() ); + } + + // The response message is the new VM's ID + int newVMID = Integer.parseInt(rc.getMessage()); + System.out.println("ok, ID " + newVMID + "."); + + // We can create a representation for the new VM, using the returned + // VM-ID + VirtualMachine vm = new VirtualMachine(newVMID, oneClient); + + // Let's hold the VM, so the scheduler won't try to deploy it + System.out.print("Trying to hold the new VM... "); + rc = vm.hold(); + + if(rc.isError()) + { + System.out.println("failed!"); + throw new Exception( rc.getErrorMessage() ); + } + else + System.out.println("ok."); + + // And now we can request its information. + rc = vm.info(); + + if(rc.isError()) + throw new Exception( rc.getErrorMessage() ); + + System.out.println(); + System.out.println( + "This is the information OpenNebula stores for the new VM:"); + System.out.println(rc.getMessage() + "\n"); + + // This VirtualMachine object has some helpers, so we can access its + // attributes easily (remember to load the data first using the info + // method). + System.out.println("The new VM " + + vm.getName() + " has status: " + vm.status()); + + // And we can also use xpath expressions + System.out.println("The path of the disk is"); + System.out.println( "\t" + vm.xpath("template/disk/source") ); + + // Let's delete the VirtualMachine object. + vm = null; + + // The reference is lost, but we can ask OpenNebula about the VM + // again. This time however, we are going to use the VM pool + VirtualMachinePool vmPool = new VirtualMachinePool(oneClient); + // Remember that we have to ask the pool to retrieve the information + // from OpenNebula + rc = vmPool.info(); + + if(rc.isError()) + throw new Exception( rc.getErrorMessage() ); + + System.out.println( + "\nThese are all the Virtual Machines in the pool:"); + for ( VirtualMachine vmachine : vmPool ) + { + System.out.println("\tID :" + vmachine.getId() + + ", Name :" + vmachine.getName() ); + + // Check if we have found the VM we are looking for + if ( vmachine.getId().equals( ""+newVMID ) ) + { + vm = vmachine; + } + } + + // We have also some useful helpers for the actions you can perform + // on a virtual machine, like cancel: + rc = vm.cancel(); + System.out.println("\nTrying to cancel the VM " + vm.getId() + + " (should fail)..."); + + // This is all the information you can get from the OneResponse: + System.out.println("\tOpenNebula response"); + System.out.println("\t Error: " + rc.isError()); + System.out.println("\t Msg: " + rc.getMessage()); + System.out.println("\t ErrMsg: " + rc.getErrorMessage()); + + rc = vm.finalizeVM(); + System.out.println("\nTrying to finalize (delete) the VM " + + vm.getId() + "..."); + + System.out.println("\tOpenNebula response"); + System.out.println("\t Error: " + rc.isError()); + System.out.println("\t Msg: " + rc.getMessage()); + System.out.println("\t ErrMsg: " + rc.getErrorMessage()); + + + } + catch (Exception e) + { + System.out.println(e.getMessage()); + } + + + } + + public static void printVMachinePool (VirtualMachinePool vmPool) + { + System.out.println("--------------------------------------------"); + System.out.println("Number of VMs: " + vmPool.getLength()); + System.out.println("User ID\t\tName\t\tEnabled"); + + // You can use the for-each loops with the OpenNebula pools + for( VirtualMachine vm : vmPool ) + { + String id = vm.getId(); + String name = vm.getName(); + String enab = vm.xpath("enabled"); + + System.out.println(id+"\t\t"+name+"\t\t"+enab); + } + + System.out.println("--------------------------------------------"); + } +} diff --git a/src/oca/java/share/examples/VMachineSample.sh b/src/oca/java/share/examples/VMachineSample.sh new file mode 100755 index 0000000000..b6dc89e7a5 --- /dev/null +++ b/src/oca/java/share/examples/VMachineSample.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +java -cp ../../lib/*:../../jar/*:. VMachineSample diff --git a/src/oca/java/src/org/opennebula/client/Client.java b/src/oca/java/src/org/opennebula/client/Client.java index 1fea68b32d..de8b9499a9 100644 --- a/src/oca/java/src/org/opennebula/client/Client.java +++ b/src/oca/java/src/org/opennebula/client/Client.java @@ -36,7 +36,7 @@ import org.apache.xmlrpc.client.XmlRpcClientConfigImpl; * xml-rpc calls. * */ -public class Client { +public class Client{ //-------------------------------------------------------------------------- // PUBLIC INTERFACE @@ -54,7 +54,7 @@ public class Client { public Client() throws Exception { setOneAuth(null); - setOneEndPoint(null); + setOneEndPoint(null); } /** @@ -160,7 +160,7 @@ public class Client { if(token.length != 2 ) { throw new Exception("Wrong format for authorization string: " - + oneSecret); + + oneSecret + "\nFormat expected is user:password"); } MessageDigest md = MessageDigest.getInstance("SHA-1"); diff --git a/src/oca/java/src/org/opennebula/client/OneResponse.java b/src/oca/java/src/org/opennebula/client/OneResponse.java index 98201ec769..917258360c 100644 --- a/src/oca/java/src/org/opennebula/client/OneResponse.java +++ b/src/oca/java/src/org/opennebula/client/OneResponse.java @@ -20,7 +20,7 @@ package org.opennebula.client; * carries a boolean indicating if it is an error. It can also contain a * success message, or an error message. */ -public class OneResponse { +public class OneResponse{ /** * Creates a new response. * @@ -34,7 +34,7 @@ public class OneResponse { this.success = success; this.msg = message; } - + /** * Returns true if the call resulted in error. * @@ -44,7 +44,7 @@ public class OneResponse { { return !success; } - + /** * Returns a string containing the error message, or null * if the response isn't an error. @@ -56,7 +56,7 @@ public class OneResponse { { return success ? null : msg; } - + /** * Returns a string containing the response information, or * null if the response was an error. Note that the success diff --git a/src/oca/java/src/org/opennebula/client/Pool.java b/src/oca/java/src/org/opennebula/client/Pool.java index 8762ce5088..194e914984 100644 --- a/src/oca/java/src/org/opennebula/client/Pool.java +++ b/src/oca/java/src/org/opennebula/client/Pool.java @@ -99,7 +99,7 @@ public abstract class Pool{ */ public PoolElement item(int index) { - PoolElement the_element = null; + PoolElement theElement = null; if (poolElements != null) { @@ -107,11 +107,11 @@ public abstract class Pool{ if (node != null) { - the_element = factory(node); + theElement = factory(node); } } - return the_element; + return theElement; } /** @@ -122,4 +122,4 @@ public abstract class Pool{ { return poolElements == null ? 0 : poolElements.getLength(); } -} \ No newline at end of file +} diff --git a/src/oca/java/src/org/opennebula/client/PoolElement.java b/src/oca/java/src/org/opennebula/client/PoolElement.java index cc93e948fd..faf4c3985e 100644 --- a/src/oca/java/src/org/opennebula/client/PoolElement.java +++ b/src/oca/java/src/org/opennebula/client/PoolElement.java @@ -44,7 +44,6 @@ public abstract class PoolElement { * Creates a new PoolElement with the specified attributes. * @param id Id of the element. * @param client XML-RPC Client. - * @param root Name of the xml's root element. */ protected PoolElement(int id, Client client) { @@ -63,7 +62,6 @@ public abstract class PoolElement { * * @param client XML-RPC Client. * @param xmlElement XML representation of the element. - * @param root Name of the xml's root element. */ protected PoolElement(Node xmlElement, Client client) { diff --git a/src/oca/java/src/org/opennebula/client/package.html b/src/oca/java/src/org/opennebula/client/package.html new file mode 100644 index 0000000000..bd3527ba32 --- /dev/null +++ b/src/oca/java/src/org/opennebula/client/package.html @@ -0,0 +1,37 @@ + + + + + +

+Provides the Java bindings for the OpenNebula Cloud API (OCA). +

+

+The included classes can be used as simple wrappers for the XML-RPC calls +supported by the OpenNebula core, or as objects that store the information +and provide useful helpers. +

+

Requirements

+

+Apart from this jar file, you need to add to the project's build-path the +Apache XML-RPC library. +

+

+You can download it from Apache's +distribution directory. +The jar files you need are xmlrpc-client-*.jar, ws-commons-util-*.jar and xmlrpc-common-*.jar.

+ +

Related Documentation

+

+Please visit the OpenNebula site for general information, +and consult the documentation section +to find up to date references, tutorials, and more. +

+

+You can learn about the OpenNebula XML-RPC API here. +

+ + + + + diff --git a/src/oca/java/src/org/opennebula/client/user/User.java b/src/oca/java/src/org/opennebula/client/user/User.java index 01c6382b56..931e35becb 100644 --- a/src/oca/java/src/org/opennebula/client/user/User.java +++ b/src/oca/java/src/org/opennebula/client/user/User.java @@ -25,106 +25,104 @@ import org.w3c.dom.Node; * This class represents an OpenNebula User. * It also offers static XML-RPC call wrappers. */ -public class User extends PoolElement { +public class User extends PoolElement{ -private static final String ROOT_NAME = "USER"; - - private static final String METHOD_PREFIX = "user."; - private static final String ALLOCATE = METHOD_PREFIX + "allocate"; - private static final String INFO = METHOD_PREFIX + "info"; - private static final String DELETE = METHOD_PREFIX + "delete"; - - /** - * Creates a new User representation. - * - * @param id The user id (uid). - * @param client XML-RPC Client. - */ - public User(int id, Client client) - { - super(id, client); - } + private static final String METHOD_PREFIX = "user."; + private static final String ALLOCATE = METHOD_PREFIX + "allocate"; + private static final String INFO = METHOD_PREFIX + "info"; + private static final String DELETE = METHOD_PREFIX + "delete"; + + /** + * Creates a new User representation. + * + * @param id The user id (uid). + * @param client XML-RPC Client. + */ + public User(int id, Client client) + { + super(id, client); + } - /** - * @see PoolElement - */ - protected User(Node xmlElement, Client client) - { + /** + * @see PoolElement + */ + protected User(Node xmlElement, Client client) + { super(xmlElement, client); - } - - - // ================================= - // Static XML-RPC methods - // ================================= - - /** - * Allocates a new user in OpenNebula. - * - * @param client XML-RPC Client. - * @param username Username for the new user. - * @param password Password for the new user - * @return If successful the message contains - * the associated id (int uid) generated for this user. - */ - public static OneResponse allocate(Client client, + } + + + // ================================= + // Static XML-RPC methods + // ================================= + + /** + * Allocates a new user in OpenNebula. + * + * @param client XML-RPC Client. + * @param username Username for the new user. + * @param password Password for the new user + * @return If successful the message contains + * the associated id (int uid) generated for this user. + */ + public static OneResponse allocate(Client client, String username, String password) { - return client.call(ALLOCATE, username, password); - } + return client.call(ALLOCATE, username, password); + } - /** Retrieves the information of the given user. - * - * @param client XML-RPC Client. - * @param id The user id (uid) for the user to - * retrieve the information from. - * @return if successful the message contains the - * string with the information about the user returned by OpenNebula. - */ - public static OneResponse info(Client client, int id) + /** Retrieves the information of the given user. + * + * @param client XML-RPC Client. + * @param id The user id (uid) for the user to + * retrieve the information from. + * @return if successful the message contains the + * string with the information about the user returned by OpenNebula. + */ + public static OneResponse info(Client client, int id) { - return client.call(INFO, id); - } - - /** - * Deletes a user from OpenNebula. - * - * @param client XML-RPC Client. - * @param id The user id (uid) of the target user we want to delete. - * @return If an error occurs the error message contains the reason. - */ - public static OneResponse delete(Client client, int id) + return client.call(INFO, id); + } + + /** + * Deletes a user from OpenNebula. + * + * @param client XML-RPC Client. + * @param id The user id (uid) of the target user we want to delete. + * @return If an error occurs the error message contains the reason. + */ + public static OneResponse delete(Client client, int id) { - return client.call(DELETE, id); - } + return client.call(DELETE, id); + } - // ================================= - // Instanced object XML-RPC methods - // ================================= - - /** - * Loads the xml representation of the user. - * The info is also stored internally. - * - * @see User#info(Client, int) - */ - public OneResponse info() + // ================================= + // Instanced object XML-RPC methods + // ================================= + + /** + * Loads the xml representation of the user. + * The info is also stored internally. + * + * @see User#info(Client, int) + */ + public OneResponse info() { - OneResponse response = info(client, id); + OneResponse response = info(client, id); - super.processInfo(response); + super.processInfo(response); - return response; - } - - /** - * Deletes the user from OpenNebula. - * - * @see User#delete(Client, int) - */ - public OneResponse delete() + return response; + } + + /** + * Deletes the user from OpenNebula. + * + * @see User#delete(Client, int) + */ + public OneResponse delete() { - return delete(client, id); - } + return delete(client, id); + } } diff --git a/src/oca/java/src/org/opennebula/client/user/UserPool.java b/src/oca/java/src/org/opennebula/client/user/UserPool.java index 3fb8988c7b..893a51725a 100644 --- a/src/oca/java/src/org/opennebula/client/user/UserPool.java +++ b/src/oca/java/src/org/opennebula/client/user/UserPool.java @@ -29,56 +29,53 @@ import org.w3c.dom.Node; * This class represents an OpenNebula user pool. * It also offers static XML-RPC call wrappers. */ -public class UserPool extends Pool implements Iterable -{ +public class UserPool extends Pool implements Iterable{ - private static final String ELEMENT_NAME = "USER"; - private static final String INFO_METHOD = "userpool.info"; - - /** - * Creates a new user pool - * @param client XML-RPC Client. - */ - public UserPool(Client client) - { - super(ELEMENT_NAME, client); - } + private static final String ELEMENT_NAME = "USER"; + private static final String INFO_METHOD = "userpool.info"; - @Override - public PoolElement factory(Node node) + /** + * Creates a new user pool + * @param client XML-RPC Client. + */ + public UserPool(Client client) { - return new User(node, client); - } + super(ELEMENT_NAME, client); + } - /** - * Loads the xml representation of the user pool. - * - * @see UserPool#info(Client) - */ - public OneResponse info() + @Override + public PoolElement factory(Node node) { - OneResponse response = client.call(INFO_METHOD); + return new User(node, client); + } + + /** + * Loads the xml representation of the user pool. + */ + public OneResponse info() + { + OneResponse response = client.call(INFO_METHOD); super.processInfo(response); return response; - } + } - public Iterator iterator() + public Iterator iterator() { - AbstractList ab = new AbstractList() + AbstractList ab = new AbstractList() { - public int size() + public int size() { - return getLength(); - } + return getLength(); + } - public User get(int index) + public User get(int index) { - return (User) item(index); - } - }; - - return ab.iterator(); - } + return (User) item(index); + } + }; + + return ab.iterator(); + } } diff --git a/src/oca/java/src/org/opennebula/client/virtualMachine/VirtualMachine.java b/src/oca/java/src/org/opennebula/client/virtualMachine/VirtualMachine.java new file mode 100644 index 0000000000..2a416f54e8 --- /dev/null +++ b/src/oca/java/src/org/opennebula/client/virtualMachine/VirtualMachine.java @@ -0,0 +1,395 @@ +/******************************************************************************* + * Copyright 2002-2010, OpenNebula Project Leads (OpenNebula.org) + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + ******************************************************************************/ +package org.opennebula.client.virtualMachine; + + +import org.opennebula.client.Client; +import org.opennebula.client.OneResponse; +import org.opennebula.client.PoolElement; +import org.w3c.dom.Node; + +/** + * This class represents an OpenNebula VM. + * It also offers static XML-RPC call wrappers. + */ +public class VirtualMachine extends PoolElement{ + + private static final String METHOD_PREFIX = "vm."; + private static final String ALLOCATE = METHOD_PREFIX + "allocate"; + private static final String INFO = METHOD_PREFIX + "info"; + private static final String DEPLOY = METHOD_PREFIX + "deploy"; + private static final String ACTION = METHOD_PREFIX + "action"; + private static final String MIGRATE = METHOD_PREFIX + "migrate"; + + private static final String[] VM_STATES = + { + "INIT", + "PENDING", + "HOLD", + "ACTIVE", + "STOPPED", + "SUSPENDED", + "DONE", + "FAILED" }; + + private static final String[] SHORT_VM_STATES = + { + "init", + "pend", + "hold", + "actv", + "stop", + "susp", + "done", + "fail" }; + + private static final String[] LCM_STATE = + { + "LCM_INIT", + "PROLOG", + "BOOT", + "RUNNING", + "MIGRATE", + "SAVE_STOP", + "SAVE_SUSPEND", + "SAVE_MIGRATE", + "PROLOG_MIGRATE", + "PROLOG_RESUME", + "EPILOG_STOP", + "EPILOG", + "SHUTDOWN", + "CANCEL", + "FAILURE", + "DELETE", + "UNKNOWN" }; + + private static final String[] SHORT_LCM_STATES = + { + null, + "prol", + "boot", + "runn", + "migr", + "save", + "save", + "save", + "migr", + "prol", + "epil", + "epil", + "shut", + "shut", + "fail", + "dele", + "unkn" }; + + /** + * Creates a new VM representation. + * + * @param id The virtual machine Id (vid). + * @param client XML-RPC Client. + */ + public VirtualMachine(int id, Client client) + { + super(id, client); + } + + /** + * @see PoolElement + */ + protected VirtualMachine(Node xmlElement, Client client) + { + super(xmlElement, client); + } + + + // ================================= + // Static XML-RPC methods + // ================================= + + /** + * Allocates a new VM in OpenNebula. + * + * @param client XML-RPC Client. + * @param description A string containing the template of the vm. + * @return If successful the message contains the associated + * id generated for this VM. + */ + public static OneResponse allocate(Client client, String description) + { + return client.call(ALLOCATE, description); + } + + /** + * Retrieves the information of the given VM. + * + * @param client XML-RPC Client. + * @param id The virtual machine id (vid) of the target instance. + * @return If successful the message contains the string + * with the information returned by OpenNebula. + */ + public static OneResponse info(Client client, int id) + { + return client.call(INFO, id); + } + + + // ================================= + // Instanced object XML-RPC methods + // ================================= + + /** + * Loads the xml representation of the virtual machine. + * The info is also stored internally. + * + * @see VirtualMachine#info(Client, int) + */ + public OneResponse info() + { + OneResponse response = info(client, id); + super.processInfo(response); + return response; + } + + /** + * Initiates the instance of the VM on the target host. + * + * @param hostId The host id (hid) of the target host where + * the VM will be instantiated. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse deploy(int hostId) + { + return client.call(DEPLOY, id, hostId); + } + + /** + * Submits an action to be performed on the virtual machine. + *
+ * It is recommended to use the helper methods instead: + *
    + *
  • {@link VirtualMachine#shutdown()}
    • + *
  • {@link VirtualMachine#cancel()}
    • + *
  • {@link VirtualMachine#hold()}
    • + *
  • {@link VirtualMachine#release()}
    • + *
  • {@link VirtualMachine#stop()}
    • + *
  • {@link VirtualMachine#suspend()}
    • + *
  • {@link VirtualMachine#resume()}
    • + *
  • {@link VirtualMachine#finalizeVM()}
    • + *
  • {@link VirtualMachine#restart()}
    • + *
+ * + * @param action The action name to be performed, can be:
+ * "shutdown", "hold", "release", "stop", "cancel", "suspend", + * "resume", "restart", "finalize". + * @return If an error occurs the error message contains the reason. + */ + protected OneResponse action(String action) + { + return client.call(ACTION, action, id); + } + + /** + * Migrates the virtual machine to the target host (hid). + * + * @param hostId The target host id (hid) where we want to migrate + * the vm. + * @param live If true we are indicating that we want livemigration, + * otherwise false. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse migrate(int hostId, boolean live) + { + return client.call(MIGRATE, id, hostId, live); + } + + + // ================================= + // Helpers + // ================================= + + /** + * Shuts down the already deployed VM. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse shutdown() + { + return action("shutdown"); + } + + /** + * Cancels the running VM. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse cancel() + { + return action("cancel"); + } + + /** + * Sets the VM to hold state. The VM will not be scheduled until it is + * released. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse hold() + { + return action("hold"); + } + + /** + * Releases a virtual machine from hold state. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse release() + { + return action("release"); + } + + /** + * Stops the virtual machine. The virtual machine state is transferred back + * to OpenNebula for a possible reschedule. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse stop() + { + return action("stop"); + } + + /** + * Suspends the virtual machine. The virtual machine state is left in the + * cluster node for resuming. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse suspend() + { + return action("suspend"); + } + + /** + * Resumes the execution of a saved VM. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse resume() + { + return action("resume"); + } + + /** + * Deletes the VM from the pool and database. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse finalizeVM() + { + return action("finalize"); + } + + /** + * Resubmits the virtual machine after failure. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse restart() + { + return action("shutdown"); + } + + + /** + * Migrates the virtual machine to the target host (hid). + *
+ * It does the same as {@link VirtualMachine#migrate(int, boolean)} + * with live set to false. + * + * @param hostId The target host id (hid) where we want to migrate + * the vm. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse migrate(int hostId) + { + return migrate(hostId, false); + } + + /** + * Performs a live migration of the virtual machine to the + * target host (hid). + *
+ * It does the same as {@link VirtualMachine#migrate(int, boolean)} + * with live set to true. + * + * @param hostId The target host id (hid) where we want to migrate + * the vm. + * @return If an error occurs the error message contains the reason. + */ + public OneResponse liveMigrate(int hostId) + { + return migrate(hostId, true); + } + + public int state() + { + return super.state(); + } + + /** + * Returns the VM state of the VirtualMachine (string value). + * @return The VM state of the VirtualMachine (string value). + */ + public String stateStr() + { + int state = state(); + return state != -1 ? VM_STATES[state()] : null; + } + + /** + * Returns the LCM state of the VirtualMachine (numeric value). + * @return The LCM state of the VirtualMachine (numeric value). + */ + public int lcmState() + { + String state = xpath("LCM_STATE"); + return state != null ? Integer.parseInt(state) : -1; + } + + /** + * Returns the LCM state of the VirtualMachine (string value). + * @return The LCM state of the VirtualMachine (string value). + */ + public String lcmStateStr() + { + int state = lcmState(); + return state != -1 ? LCM_STATE[state] : null; + } + + /** + * Returns the short status string for the VirtualMachine. + * @return The short status string for the VirtualMachine. + */ + public String status() + { + int state = state(); + String shortStateStr = null; + if(state != -1) + { + shortStateStr = SHORT_VM_STATES[state]; + if(shortStateStr.equals("actv")) + { + int lcmState = lcmState(); + if(lcmState != -1) + shortStateStr = SHORT_LCM_STATES[lcmState]; + } + } + return shortStateStr; + } +} diff --git a/src/oca/java/src/org/opennebula/client/virtualMachine/VirtualMachinePool.java b/src/oca/java/src/org/opennebula/client/virtualMachine/VirtualMachinePool.java new file mode 100644 index 0000000000..5b0f3d5f9e --- /dev/null +++ b/src/oca/java/src/org/opennebula/client/virtualMachine/VirtualMachinePool.java @@ -0,0 +1,129 @@ +/******************************************************************************* + * Copyright 2002-2010, OpenNebula Project Leads (OpenNebula.org) + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + ******************************************************************************/ +package org.opennebula.client.virtualMachine; + +import java.util.AbstractList; +import java.util.Iterator; + + +import org.opennebula.client.Client; +import org.opennebula.client.OneResponse; +import org.opennebula.client.Pool; +import org.opennebula.client.PoolElement; +import org.w3c.dom.Node; + +/** + * This class represents an OpenNebula VM pool. + * It also offers static XML-RPC call wrappers. + */ +public class VirtualMachinePool extends Pool implements Iterable{ + + private static final String ELEMENT_NAME = "VM"; + private static final String INFO_METHOD = "vmpool.info"; + + private int filter; + + /** + * Creates a new VM pool with the default filter flag value + * set to 0 (VMs belonging to user with UID 0) + * + * @param client XML-RPC Client. + * + * @see VirtualMachinePool#VirtualMachinePool(Client, int) + */ + public VirtualMachinePool(Client client) + { + super(ELEMENT_NAME, client); + this.filter = 0; + } + + /** + * Creates a new VM pool. + * + * @param client XML-RPC Client. + * @param filter Filter flag used by default in the method + * {@link VirtualMachinePool#info()}. Possible values: + *
    + *
  • <= -2: All VMs
    • + *
  • -1: Connected user's VMs
    • + *
  • >= 0: UID User's VMs
    • + *
+ */ + public VirtualMachinePool(Client client, int filter) + { + super(ELEMENT_NAME, client); + this.filter = filter; + } + + @Override + public PoolElement factory(Node node) + { + return new VirtualMachine(node, client); + } + + /** + * Retrieves all or part of the VMs in the pool. + * + * @param client XML-RPC Client. + * @param filter Filter flag. Possible values: + *
    + *
  • <= -2: All VMs
    • + *
  • -1: Connected user's VMs
    • + *
  • >= 0: UID User's VMs
    • + *
+ * @return If successful the message contains the string + * with the information returned by OpenNebula. + */ + public static OneResponse info(Client client, int filter) + { + return client.call(INFO_METHOD, filter); + } + + /** + * Loads the xml representation of all or part of the + * VMs in the pool. The filter used is the one set in + * the constructor. + * + * @see VirtualMachinePool#info(Client, int) + * + * @return If successful the message contains the string + * with the information returned by OpenNebula. + */ + public OneResponse info() + { + OneResponse response = info(client, filter); + super.processInfo(response); + return response; + } + + public Iterator iterator() + { + AbstractList ab = new AbstractList() + { + public int size() + { + return getLength(); + } + + public VirtualMachine get(int index) + { + return (VirtualMachine) item(index); + } + }; + + return ab.iterator(); + } +} diff --git a/src/oca/java/src/org/opennebula/client/virtualNetwork/VirtualNetwork.java b/src/oca/java/src/org/opennebula/client/virtualNetwork/VirtualNetwork.java new file mode 100644 index 0000000000..6982498eb4 --- /dev/null +++ b/src/oca/java/src/org/opennebula/client/virtualNetwork/VirtualNetwork.java @@ -0,0 +1,126 @@ +/******************************************************************************* + * Copyright 2002-2010, OpenNebula Project Leads (OpenNebula.org) + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + ******************************************************************************/ +package org.opennebula.client.virtualNetwork; + + +import org.opennebula.client.Client; +import org.opennebula.client.OneResponse; +import org.opennebula.client.PoolElement; +import org.w3c.dom.Node; + +/** + * This class represents an OpenNebula virtual network. + * It also offers static XML-RPC call wrappers. + */ +public class VirtualNetwork extends PoolElement{ + + private static final String METHOD_PREFIX = "vn."; + private static final String ALLOCATE = METHOD_PREFIX + "allocate"; + private static final String INFO = METHOD_PREFIX + "info"; + private static final String DELETE = METHOD_PREFIX + "delete"; + + + /** + * Creates a new virtual network representation. + * + * @param id The virtual network id (nid) . + * @param client XML-RPC Client. + */ + public VirtualNetwork(int id, Client client) + { + super(id, client); + } + + /** + * @see PoolElement + */ + protected VirtualNetwork(Node xmlElement, Client client) + { + super(xmlElement, client); + } + + // ================================= + // Static XML-RPC methods + // ================================= + + /** + * Allocates a new virtual network in OpenNebula. + * + * @param client XML-RPC Client. + * @param description A string containing the template + * of the virtual network. + * @return If successful the message contains the associated + * id generated for this virtual network. + */ + public static OneResponse allocate(Client client, String description) + { + return client.call(ALLOCATE, description); + } + + /** + * Retrieves the information of the given virtual network + * + * @param client XML-RPC Client. + * @param id the virtual network id (nid) for the network to + * retrieve the information from. + * @return If successful the message contains the string + * with the information returned by OpenNebula. + */ + public static OneResponse info(Client client, int id) + { + return client.call(INFO, id); + } + + /** + * Deletes a network from OpenNebula. + * + * @param client XML-RPC Client. + * @param id The virtual network id (nid) of the target network. + * @return A encapsulated response. + */ + public static OneResponse delete(Client client, int id) + { + return client.call(DELETE, id); + } + + + // ================================= + // Instanced object XML-RPC methods + // ================================= + + /** + * Loads the xml representation of the virtual network. + * The info is also stored internally. + * + * @see VirtualNetwork#info(Client, int) + */ + public OneResponse info() + { + OneResponse response = info(client, id); + super.processInfo(response); + return response; + } + + /** + * Deletes the network from OpenNebula. + * + * @return A encapsulated response. + */ + public OneResponse delete() + { + return delete(client, id); + } +} diff --git a/src/oca/java/src/org/opennebula/client/virtualNetwork/VirtualNetworkPool.java b/src/oca/java/src/org/opennebula/client/virtualNetwork/VirtualNetworkPool.java new file mode 100644 index 0000000000..cfc0dfd2d9 --- /dev/null +++ b/src/oca/java/src/org/opennebula/client/virtualNetwork/VirtualNetworkPool.java @@ -0,0 +1,128 @@ +/******************************************************************************* + * Copyright 2002-2010, OpenNebula Project Leads (OpenNebula.org) + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + ******************************************************************************/ +package org.opennebula.client.virtualNetwork; + +import java.util.AbstractList; +import java.util.Iterator; + + +import org.opennebula.client.Client; +import org.opennebula.client.OneResponse; +import org.opennebula.client.Pool; +import org.opennebula.client.PoolElement; +import org.w3c.dom.Node; + +/** + * This class represents an OpenNebula Virtual Network pool. + * It also offers static XML-RPC call wrappers. + */ +public class VirtualNetworkPool extends Pool implements Iterable{ + + private static final String ELEMENT_NAME = "VNET"; + private static final String INFO_METHOD = "vnpool.info"; + + private int filter; + + /** + * Creates a new VN pool with the default filter flag value + * set to 0 (VNs belonging to user with UID 0) + * + * @param client XML-RPC Client. + * + * @see VirtualNetworkPool#VirtualNetworkPool(Client, int) + */ + public VirtualNetworkPool(Client client) + { + super(ELEMENT_NAME, client); + this.filter = 0; + } + + /** + * Creates a new VN pool. + * + * @param client XML-RPC Client. + * @param filter Filter flag used by default in the method + * {@link VirtualNetworkPool#info()}. Possible values: + *
    + *
  • <= -2: All VNs
    • + *
  • -1: Connected user's VNs
    • + *
  • >= 0: UID User's VNs
    • + *
+ */ + public VirtualNetworkPool(Client client, int filter) + { + super(ELEMENT_NAME, client); + this.filter = filter; + } + + @Override + public PoolElement factory(Node node) + { + return new VirtualNetwork(node, client); + } + + /** + * Retrieves all or part of the VNs in the pool. + * + * @param client XML-RPC Client. + * @param filter Filter flag. Possible values: + *
    + *
  • <= -2: All VNs
    • + *
  • -1: Connected user's VNs
    • + *
  • >= 0: UID User's VNs
    • + *
+ * @return If successful the message contains the string + * with the information returned by OpenNebula. + */ + public static OneResponse info(Client client, int filter) + { + return client.call(INFO_METHOD, filter); + } + + /** + * Loads the xml representation of all or part of the + * VNs in the pool. The filter used is the one set in + * the constructor. + * + * @see VirtualNetworkPool#info(Client, int) + * @return If successful the message contains the string + * with the information returned by OpenNebula. + */ + public OneResponse info() + { + OneResponse response = info(client, filter); + super.processInfo(response); + return response; + } + + public Iterator iterator() + { + AbstractList ab = new AbstractList() + { + public int size() + { + return getLength(); + } + + public VirtualNetwork get(int index) + { + return (VirtualNetwork) item(index); + } + }; + + return ab.iterator(); + } +} diff --git a/src/oca/java/src/org/opennebula/client/vm/VirtualMachine.java b/src/oca/java/src/org/opennebula/client/vm/VirtualMachine.java index 77c0720162..7e92fa1a2c 100644 --- a/src/oca/java/src/org/opennebula/client/vm/VirtualMachine.java +++ b/src/oca/java/src/org/opennebula/client/vm/VirtualMachine.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. ******************************************************************************/ -package org.opennebula.client.virtualMachine; +package org.opennebula.client.vm; import org.opennebula.client.Client; diff --git a/src/oca/java/src/org/opennebula/client/vm/VirtualMachinePool.java b/src/oca/java/src/org/opennebula/client/vm/VirtualMachinePool.java index 5b0f3d5f9e..31b23e0be2 100644 --- a/src/oca/java/src/org/opennebula/client/vm/VirtualMachinePool.java +++ b/src/oca/java/src/org/opennebula/client/vm/VirtualMachinePool.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. ******************************************************************************/ -package org.opennebula.client.virtualMachine; +package org.opennebula.client.vm; import java.util.AbstractList; import java.util.Iterator; diff --git a/src/oca/java/src/org/opennebula/client/vnet/VirtualNetwork.java b/src/oca/java/src/org/opennebula/client/vnet/VirtualNetwork.java index 6982498eb4..3fcc3f9d0b 100644 --- a/src/oca/java/src/org/opennebula/client/vnet/VirtualNetwork.java +++ b/src/oca/java/src/org/opennebula/client/vnet/VirtualNetwork.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. ******************************************************************************/ -package org.opennebula.client.virtualNetwork; +package org.opennebula.client.vnet; import org.opennebula.client.Client; diff --git a/src/oca/java/src/org/opennebula/client/vnet/VirtualNetworkPool.java b/src/oca/java/src/org/opennebula/client/vnet/VirtualNetworkPool.java index cfc0dfd2d9..2c966e72d9 100644 --- a/src/oca/java/src/org/opennebula/client/vnet/VirtualNetworkPool.java +++ b/src/oca/java/src/org/opennebula/client/vnet/VirtualNetworkPool.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. ******************************************************************************/ -package org.opennebula.client.virtualNetwork; +package org.opennebula.client.vnet; import java.util.AbstractList; import java.util.Iterator;