[PATCH] Some updates to the Java Cloud API

src/oca/java/build.sh

@@ -76,7 +76,7 @@ do_documentation()
       -subpackages org.opennebula \
       -windowtitle 'OpenNebula Cloud API' \
       -doctitle 'OpenNebula Cloud API Specification' \
-      -header '<b>OpenNebula</b><br><font size="-1">Java API</font>' \
+      -header '<b>OpenNebula</b><br><font size="-1">Cloud API</font>' \
       -bottom 'Visit <a
 href="http://opennebula.org/">OpenNebula.org</a><br>Copyright 2002-2010 &copy;
 OpenNebula Project Leads (OpenNebula.org).'

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());
+        }
     }
 }

src/oca/java/share/examples/SessionInit.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+java -cp ../../lib/*:../../jar/*:. SessionInit

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();

src/oca/java/share/examples/UserSample.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+java -cp ../../lib/*:../../jar/*:. UserSample

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("--------------------------------------------");
+    }
+}

src/oca/java/share/examples/VMachineSample.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+java -cp ../../lib/*:../../jar/*:. VMachineSample

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");

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

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();
     }
-}
+}

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)
     {

src/oca/java/src/org/opennebula/client/package.html

@@ -0,0 +1,37 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+</head>
+<body bgcolor="white">
+<p>
+Provides the Java bindings for the OpenNebula Cloud API (OCA).
+</p>
+<p>
+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.
+</p>
+<h2>Requirements</h2>
+<p>
+Apart from this jar file, you need to add to the project's build-path the
+<a href="http://ws.apache.org/xmlrpc/index.html">Apache XML-RPC</a> library.
+</p>
+<p>
+You can download it from Apache's
+<a href="http://www.apache.org/dyn/closer.cgi/ws/xmlrpc/">distribution directory</a>.
+The jar files you need are xmlrpc-client-*.jar, ws-commons-util-*.jar and xmlrpc-common-*.jar.</p>
+
+<h2>Related Documentation</h2>
+<p>
+Please visit the <a href="http://opennebula.org">OpenNebula</a> site for general information,
+and consult the <a href="http://opennebula.org/doku.php?id=documentation">documentation section</a>
+to find up to date references, tutorials, and more.
+</p>
+<p>
+You can learn about the OpenNebula XML-RPC API <a href="http://opennebula.org/doku.php?id=documentation:rel1.4:api">here</a>.
+</p>
+
+<!-- Put @see and @since tags down here. -->
+
+</body>
+</html>

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);
+    }
 }

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<User>
-{
+public class UserPool extends Pool implements Iterable<User>{
 
-	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<User> iterator()
+    public Iterator<User> iterator()
     {
-		AbstractList<User> ab = new AbstractList<User>()
+        AbstractList<User> ab = new AbstractList<User>()
         {
-			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();
+    }
 }

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.
+     * <br/>
+     * It is recommended to use the helper methods instead:
+     * <ul>
+     * <li>{@link VirtualMachine#shutdown()}</li>
+     * <li>{@link VirtualMachine#cancel()}</li>
+     * <li>{@link VirtualMachine#hold()}</li>
+     * <li>{@link VirtualMachine#release()}</li>
+     * <li>{@link VirtualMachine#stop()}</li>
+     * <li>{@link VirtualMachine#suspend()}</li>
+     * <li>{@link VirtualMachine#resume()}</li>
+     * <li>{@link VirtualMachine#finalizeVM()}</li>
+     * <li>{@link VirtualMachine#restart()}</li>
+     * </ul>
+     * 
+     * @param action The action name to be performed, can be:<br/>
+     * "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).
+     * <br/>
+     * 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).
+     * <br/>
+     * 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;
+    }
+}

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<VirtualMachine>{
+
+    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:
+     * <ul>
+     * <li><= -2: All VMs</li>
+     * <li>-1: Connected user's VMs</li>
+     * <li>>= 0: UID User's VMs</li>
+     * </ul>
+     */
+    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:
+     * <ul>
+     * <li><= -2: All VMs</li>
+     * <li>-1: Connected user's VMs</li>
+     * <li>>= 0: UID User's VMs</li>
+     * </ul>
+     * @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<VirtualMachine> iterator()
+    {
+        AbstractList<VirtualMachine> ab = new AbstractList<VirtualMachine>()
+        {
+            public int size()
+            {
+                return getLength();
+            }
+
+            public VirtualMachine get(int index)
+            {
+                return (VirtualMachine) item(index);
+            }
+        };
+
+        return ab.iterator();
+    }
+}

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);
+    }
+}

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<VirtualNetwork>{
+
+    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:
+     * <ul>
+     * <li><= -2: All VNs</li>
+     * <li>-1: Connected user's VNs</li>
+     * <li>>= 0: UID User's VNs</li>
+     * </ul>
+     */
+    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:
+     * <ul>
+     * <li><= -2: All VNs</li>
+     * <li>-1: Connected user's VNs</li>
+     * <li>>= 0: UID User's VNs</li>
+     * </ul>
+     * @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<VirtualNetwork> iterator()
+    {
+        AbstractList<VirtualNetwork> ab = new AbstractList<VirtualNetwork>()
+        {
+            public int size()
+            {
+                return getLength();
+            }
+
+            public VirtualNetwork get(int index)
+            {
+                return (VirtualNetwork) item(index);
+            }
+        };
+
+        return ab.iterator();
+    }
+}

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;

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;

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;

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;