commented machine utils

labs/virtualbox/src/main/java/org/jclouds/virtualbox/util/MachineUtils.java

@@ -45,7 +45,7 @@ import com.google.inject.Inject;
 /**
  * Utilities for executing functions on a VirtualBox machine.
  * 
- * @author Adrian Cole, Mattias Holmqvist, Andrea Turli
+ * @author Adrian Cole, Mattias Holmqvist, Andrea Turli, David Alves
  */
 
 @Singleton
@@ -101,10 +101,34 @@ public class MachineUtils {
       });
    }
    
+   /**
+    * Locks the machine and executes the given function using the machine matching the given id.
+    * The machine is write locked and modifications to the session that reflect on the machine can be done safely.
+    * <p/>
+    * Unlocks the machine before returning.
+    * 
+    * @param machineId
+    *           the id of the machine
+    * @param function
+    *           the function to execute
+    * @return the result from applying the function to the machine.
+    */
    public <T> T writeLockMachineAndApplyToSession(final String machineId, final Function<ISession, T> function) {
       return lockSessionOnMachineAndApply(machineId, LockType.Write, function);
    }
    
+   /**
+    * Locks the machine and executes the given function using the machine matching the given id.
+    * The machine is read locked, which means that settings can be read safely (but not changed) by function.
+    * <p/>
+    * Unlocks the machine before returning.
+    * 
+    * @param machineId
+    *           the id of the machine
+    * @param function
+    *           the function to execute
+    * @return the result from applying the function to the machine.
+    */
    public <T> T readLockMachineAndApply(final String machineId, final Function<IMachine, T> function) {
       return lockSessionOnMachineAndApply(machineId, LockType.Shared, new Function<ISession, T>() {
 
@@ -121,6 +145,18 @@ public class MachineUtils {
       });
    }
    
+   /**
+    * Locks the machine and executes the given function to the session using the machine matching the given id.
+    * The machine is read locked, which means that settings can be read safely (but not changed) by function.
+    * <p/>
+    * Unlocks the machine before returning.
+    * 
+    * @param machineId
+    *           the id of the machine
+    * @param function
+    *           the function to execute
+    * @return the result from applying the function to the machine.
+    */
    public <T> T readLockMachineAndApplyToSession(final String machineId, final Function<ISession, T> function) {
       return lockSessionOnMachineAndApply(machineId, LockType.Shared, function);
    }
@@ -132,6 +168,9 @@ public class MachineUtils {
     * <p/>
     * Unlocks the machine before returning.
     * 
+    * Tries to obtain a lock 5 times before giving up waiting 1 sec between tries. When no machine
+    * is found null is returned.
+    * 
     * @param type
     *           the kind of lock to use when initially locking the machine.
     * @param machineId
@@ -141,7 +180,6 @@ public class MachineUtils {
     * @return the result from applying the function to the session.
     */
    private <T> T lockSessionOnMachineAndApply(String machineId, LockType type, Function<ISession, T> function) {
-      try {
       int retries = 5;
       int count = 0;
       ISession session;
@@ -159,8 +197,8 @@ public class MachineUtils {
             count++;
             logger.warn("Could not lock machine (try %i of %i). Error: %s", retries, count, e.getMessage());
             if (count == retries) {
-                  throw new RuntimeException(String.format("error locking %s with %s lock: %s", machineId,
+               throw new RuntimeException(String.format("error locking %s with %s lock: %s", machineId, type,
-                           type, e.getMessage()), e);   
+                        e.getMessage()), e);
             }
             try {
                Thread.sleep(1000L);
@@ -170,12 +208,11 @@ public class MachineUtils {
       }
       try {
          return function.apply(session);
-         } finally {
-            session.unlockMachine();
-         }
       } catch (VBoxException e) {
          throw new RuntimeException(String.format("error applying %s to %s with %s lock: %s", function, machineId,
                   type, e.getMessage()), e);
+      } finally {
+         session.unlockMachine();
       }
    }