virtualbox 0.1.1 → 0.2.0

data/lib/virtualbox/command.rb

@@ -14,6 +14,13 @@ module VirtualBox
     @@vboxmanage = "VBoxManage"
     
     class <<self
+      # Returns true if the last run command was a success. Obviously this
+      # will introduce all sorts of thread-safe problems. Those will have to
+      # be addressed another time.
+      def success?
+        $?.to_i == 0
+      end
+      
       # Sets the path to VBoxManage, which is required for this gem to
       # work.
       def vboxmanage=(path)
@@ -22,7 +29,9 @@ module VirtualBox
       
       # Runs a VBoxManage command and returns the output.
       def vboxmanage(command)
-        execute("#{@@vboxmanage} #{command}")
+        result = execute("#{@@vboxmanage} #{command}")
+        raise Exceptions::CommandFailedException.new(result) if !Command.success?
+        result
       end
       
       # Runs a command and returns a boolean result showing
@@ -30,7 +39,7 @@ module VirtualBox
       # exit code.
       def test(command)
         execute(command)
-        $?.to_i == 0
+        success?
       end
     
       # Runs a command and returns the STDOUT result. The reason this is

data/lib/virtualbox/dvd.rb

@@ -9,6 +9,15 @@ module VirtualBox
   #
   #     DVD.all
   #
+  # # Empty Drives
+  # 
+  # Sometimes it is useful to have an empty drive. This is the case where you
+  # may have a DVD drive but it has no disk in it. To create an {AttachedDevice},
+  # an image _must_ be specified, and an empty drive is a simple option. Creating
+  # an empty drive is simple:
+  #
+  #     DVD.empty_drive
+  #
   class DVD < Image
     class <<self
       # Returns an array of all available DVDs as DVD objects
@@ -16,16 +25,55 @@ module VirtualBox
         raw = Command.vboxmanage("list dvds")
         parse_raw(raw)
       end
+      
+      # Returns an empty drive. This is useful for creating new
+      # or modifyingn existing {AttachedDevice} objects and
+      # attaching an empty drive to them.
+      #
+      # @return [DVD]
+      def empty_drive
+        new(:empty_drive)
+      end
+    end
+    
+    def initialize(*args)
+      if args.length == 1 && args[0] == :empty_drive
+        @empty_drive = true
+      else
+        super
+      end
+    end
+    
+    # Override of {Image#empty_drive?}. This will only be true if
+    # the DVD was created with {DVD.empty_drive}.
+    #
+    # @return [Boolean]
+    def empty_drive?
+      @empty_drive || false
+    end
+    
+    # Override of {Image#image_type}.
+    def image_type
+      "dvddrive"
     end
     
     # Deletes the DVD from VBox managed list and also from disk.
     # This method will fail if the disk is currently mounted to any
-    # virtual machine.
+    # virtual machine. This method also does nothing for empty drives
+    # (see {DVD.empty_drive}) and will return false automatically in
+    # that case.
     #
-    # @return [Boolean]
-    def destroy
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def destroy(raise_errors=false)
+      return false if empty_drive?
+      
       Command.vboxmanage("closemedium dvd #{uuid} --delete")
-      return $?.to_i == 0
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
     end
   end
 end

data/lib/virtualbox/exceptions.rb

@@ -0,0 +1,13 @@
+module VirtualBox
+  # Gem specific exceptions will reside under this namespace for easy
+  # documentation and searching.
+  module Exceptions
+    class Exception < ::Exception; end
+
+    class CommandFailedException < Exception; end
+    class InvalidObjectException < Exception; end
+    class InvalidRelationshipObjectException < Exception; end
+    class NonSettableRelationshipException < Exception; end
+    class NoParentException < Exception; end
+  end
+end

data/lib/virtualbox/hard_drive.rb

@@ -120,24 +120,44 @@ module VirtualBox
     #   single filename, since VirtualBox will place it in the hard
     #   drives folder.
     # @param [String] format The format to convert to.
-    # @return [HardDrive] The new, cloned hard drive.
-    def clone(outputfile, format="VDI")
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [HardDrive] The new, cloned hard drive, or nil on failure.
+    def clone(outputfile, format="VDI", raise_errors=false)
       raw = Command.vboxmanage("clonehd #{uuid} #{Command.shell_escape(outputfile)} --format #{format} --remember")
       return nil unless raw =~ /UUID: (.+?)$/
       
       self.class.find($1.to_s)
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      nil
+    end
+    
+    # Override of {Image#image_type}.
+    def image_type
+      "hdd"
     end
     
     # Creates a new hard drive. 
     #
     # **This method should NEVER be called. Call {#save} instead.**
-    def create
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def create(raise_errors=false)
       raw = Command.vboxmanage("createhd --filename #{location} --size #{size} --format #{read_attribute(:format)} --remember")
       return nil unless raw =~ /UUID: (.+?)$/
       
       # Just replace our attributes with the newly created ones. This also
       # will set new_record to false.
       populate_attributes(self.class.find($1.to_s).attributes)
+      
+      # Return the success of the command
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
     end
     
     # Saves the hard drive object. If the hard drive is new,
@@ -146,10 +166,14 @@ module VirtualBox
     # 
     # Currently, **saving existing hard drives does nothing**.
     # This is a limitation of VirtualBox, rather than the library itself.
-    def save
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save(raise_errors=false)
       if new_record?
         # Create a new hard drive
-        create
+        create(raise_errors)
       else
         super
       end
@@ -160,10 +184,15 @@ module VirtualBox
     # 
     # **This operation is not reversable.**
     #
-    # @return [Boolean]
-    def destroy
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def destroy(raise_errors=false)
       Command.vboxmanage("closemedium disk #{uuid} --delete")
-      return $?.to_i == 0
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
     end
   end
 end

data/lib/virtualbox/image.rb

@@ -72,6 +72,7 @@ module VirtualBox
       #
       # @return [Array<Image>]
       def populate_relationship(caller, data)
+        return DVD.empty_drive if data[:medium] == "emptydrive"
         return nil if data[:uuid].nil?
         
         subclasses.each do |subclass|
@@ -80,6 +81,22 @@ module VirtualBox
           matching = subclass.all.find { |obj| obj.uuid == data[:uuid] }
           return matching unless matching.nil?
         end
+        
+        nil
+      end
+      
+      # Sets an image onto a relationship and/or removes it from a
+      # relationship. This method is automatically called by {Relatable}.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Image]
+      def set_relationship(caller, old_value, new_value)
+        # We don't actually destroy any images using this method,
+        # so just return the new value as long as its a valid object
+        raise Exceptions::InvalidRelationshipObjectException.new if new_value && !new_value.is_a?(Image)
+        
+        return new_value
       end
     end
     
@@ -90,5 +107,25 @@ module VirtualBox
       
       populate_attributes(info) if info
     end
+    
+    # The image type as a string for the virtualbox command line. This
+    # method should be overridden by any subclass and is expected to
+    # return the type which is used in command line parameters for 
+    # attaching to storage controllers.
+    #
+    # @return [String]
+    def image_type
+      raise "This must be implemented by any subclasses"
+    end
+    
+    # Returns boolean showing if empty drive or not. This method should be
+    # overriden by any subclass and is expected to return true of false
+    # showing if this image represents an empty drive of whatever type
+    # the subclass is.
+    #
+    # @return [Boolean]
+    def empty_drive?
+      false
+    end
   end
 end

data/lib/virtualbox/nic.rb

@@ -142,7 +142,7 @@ module VirtualBox
     # called on {#save}.
     #
     # **This method typically won't be used except internally.**
-    def save_attribute(key, value, vmname)
+    def save_attribute(key, value, vmname)        
       Command.vboxmanage("modifyvm #{vmname} --#{key}#{@index} #{Command.shell_escape(value)}")
       super
     end

data/lib/virtualbox/proxies/collection.rb

@@ -0,0 +1,29 @@
+module VirtualBox
+  module Proxies
+    # A relationship which can be described as a collection, which
+    # is a set of items.
+    class Collection < Array
+      def initialize(parent)
+        super()
+        
+        @parent = parent
+      end
+      
+      def <<(item)
+        item.added_to_relationship(@parent) if item.respond_to?(:added_to_relationship)
+        push(item)
+      end
+      
+      def clear
+        each do |item|
+          delete(item)
+        end
+      end
+      
+      def delete(item)
+        return unless super
+        item.removed_from_relationship(@parent) if item.respond_to?(:removed_from_relationship)
+      end
+    end
+  end
+end

data/lib/virtualbox/storage_controller.rb

@@ -73,6 +73,17 @@ module VirtualBox
       def destroy_relationship(caller, data, *args)
         data.each { |v| v.destroy(*args) }
       end
+      
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, data)
+        # Just call save on each nic with the VM
+        data.each do |sc|
+          sc.save
+        end
+      end
     end
     
     # Since storage controllers still can't be created from scratch,

data/lib/virtualbox/vm.rb

@@ -226,7 +226,7 @@ module VirtualBox
     # Saves the virtual machine if modified. This method saves any modified
     # attributes of the virtual machine. If any related attributes were saved
     # as well (such as storage controllers), those will be saved, too.
-    def save
+    def save(raise_errors=false)
       # Make sure we save the new name first if that was changed, or
       # we'll get some inconsistencies later
       if name_changed?
@@ -234,7 +234,12 @@ module VirtualBox
         @original_name = name
       end
       
-      super
+      super()
+      
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      return false
     end
     
     # Saves a single attribute of the virtual machine. This should **not**
@@ -246,6 +251,42 @@ module VirtualBox
       super
     end
     
+    # Exports a virtual machine. The virtual machine will be exported
+    # to the specified OVF file name. This directory will also have the
+    # `mf` file which contains the file checksums and also the virtual
+    # drives of the machine.
+    #
+    # Export also supports an additional options hash which can contain
+    # information that will be embedded with the virtual machine. View
+    # below for more information on the available options.
+    #
+    # This method will block until the export is complete, which takes about
+    # 60 to 90 seconds on my 2.2 GHz 2009 model MacBook Pro.
+    #
+    # @param [String] filename The file (not directory) to save the exported
+    #   OVF file. This directory will also receive the checksum file and
+    #   virtual disks.
+    # @option options [String] :product (nil) The name of the product
+    # @option options [String] :producturl (nil) The URL of the product
+    # @option options [String] :vendor (nil) The name of the vendor
+    # @option options [String] :vendorurl (nil) The URL for the vendor
+    # @option options [String] :version (nil) The version information
+    # @option options [String] :eula (nil) License text
+    # @option options [String] :eulafile (nil) License file
+    def export(filename, options={}, raise_error=false)
+      options = options.inject([]) do |acc, kv|
+        acc.push("--#{kv[0]} #{Command.shell_escape(kv[1])}")
+      end
+      
+      options.unshift("--vsys 0") unless options.empty?
+      
+      raw = Command.vboxmanage("export #{@original_name} -o #{Command.shell_escape(filename)} #{options.join(" ")}".strip)
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_error
+      false
+    end
+    
     # Starts the virtual machine. The virtual machine can be started in a
     # variety of modes:
     #
@@ -255,15 +296,74 @@ module VirtualBox
     #
     # All modes will start their processes and return almost immediately.
     # Both the GUI and headless mode will not block the ruby process.
-    def start(mode=:gui)
+    #
+    # @param [Symbol] mode Described above.
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def start(mode=:gui, raise_errors=false)
       Command.vboxmanage("startvm #{@original_name} --type #{mode}")
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
     end
     
     # Stops the VM by directly calling "poweroff." Immediately halts the
     # virtual machine without saving state. This could result in a loss
     # of data.
-    def stop
-      Command.vboxmanage("controlvm #{@original_name} poweroff")
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def stop(raise_errors=false)
+      control(:poweroff, raise_errors)
+    end
+    
+    # Pauses the VM, putting it on hold temporarily. The VM can be resumed
+    # again by calling {#resume}
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def pause(raise_errors=false)
+      control(:pause, raise_errors)
+    end
+    
+    # Resume a paused VM.
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def resume(raise_errors=false)
+      control(:resume, raise_errors)
+    end
+    
+    # Saves the state of a VM and stops it. The VM can be resumed
+    # again by calling "start" again.
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save_state(raise_errors=false)
+      control(:savestate, raise_errors)
+    end
+    
+    # Controls the virtual machine. This method is used by {#stop},
+    # {#pause}, {#resume}, and {#save_state} to control the virtual machine.
+    # Typically, you won't ever have to call this method and should
+    # instead call those.
+    #
+    # @param [String] command The command to run on controlvm
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def control(command, raise_errors=false)
+      Command.vboxmanage("controlvm #{@original_name} #{command}")
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
     end
     
     # Destroys the virtual machine. This method also removes all attached

data/lib/virtualbox.rb

@@ -1,7 +1,8 @@
 $:.unshift(File.expand_path(File.dirname(__FILE__)))
-require 'virtualbox/errors'
+require 'virtualbox/exceptions'
 require 'virtualbox/command'
 require 'virtualbox/abstract_model'
+require 'virtualbox/proxies/collection'
 require 'virtualbox/image'
 require 'virtualbox/attached_device'
 require 'virtualbox/dvd'

data/test/virtualbox/abstract_model/dirty_test.rb

@@ -43,6 +43,14 @@ class DirtyTest < Test::Unit::TestCase
       assert !@model.changed?
     end
     
+    should "be able to clear dirty state on entire model" do
+      @model.foo = "changed"
+      @model.bar = "changed"
+      assert @model.changed?
+      @model.clear_dirty!
+      assert !@model.changed?
+    end
+    
     should "show changes on specific field" do
       assert !@model.changed?
       @model.foo = "my value"
@@ -51,6 +59,11 @@ class DirtyTest < Test::Unit::TestCase
       assert_equal "foo", @model.foo_was
     end
     
+    should "return nil for field_was if its not changed" do
+      assert !@model.foo_changed?
+      assert_nil @model.foo_was
+    end
+    
     should "show changes for the whole model" do
       assert !@model.changed?
       @model.foo = "foo2"
@@ -62,5 +75,9 @@ class DirtyTest < Test::Unit::TestCase
       assert_equal ["foo", "foo2"], changes[:foo]
       assert_equal ["bar", "bar2"], changes[:bar]
     end
+    
+    should "still forward non-dirty magic methods up method_missing" do
+      assert_raises(NoMethodError) { @model.foobarbaz }
+    end
   end
 end

data/test/virtualbox/abstract_model/relatable_test.rb

@@ -6,7 +6,10 @@ class RelatableTest < Test::Unit::TestCase
       "FOO"
     end
   end
-  class BarRelatee; end
+  class BarRelatee
+    def self.set_relationship(caller, old_value, new_value)
+    end
+  end
   
   class RelatableModel
     include VirtualBox::AbstractModel::Relatable
@@ -19,6 +22,37 @@ class RelatableTest < Test::Unit::TestCase
     @data = {}
   end
   
+  context "setting a relationship" do
+    setup do
+      @model = RelatableModel.new
+    end
+    
+    should "have a magic method relationship= which calls set_relationship" do
+      @model.expects(:set_relationship).with(:foos, "FOOS!")
+      @model.foos = "FOOS!"
+    end
+    
+    should "raise a NonSettableRelationshipException if relationship can't be set" do
+      assert_raises(VirtualBox::Exceptions::NonSettableRelationshipException) {
+        @model.foos = "FOOS!"
+      }
+    end
+    
+    should "call set_relationship on the relationship class" do
+      BarRelatee.expects(:populate_relationship).returns("foo")
+      @model.populate_relationships({})
+      
+      BarRelatee.expects(:set_relationship).with(@model, "foo", "bars")
+      assert_nothing_raised { @model.bars = "bars" }
+    end
+    
+    should "set the result of set_relationship as the new relationship data" do
+      BarRelatee.stubs(:set_relationship).returns("hello")
+      @model.bars = "zoo"
+      assert_equal "hello", @model.bars
+    end
+  end
+  
   context "subclasses" do
     class SubRelatableModel < RelatableModel
       relationship :bars, Relatee
@@ -122,6 +156,20 @@ class RelatableTest < Test::Unit::TestCase
     end
   end
   
+  context "checking for relationships" do
+    setup do
+      @model = RelatableModel.new
+    end
+    
+    should "return true for existing relationships" do
+      assert @model.has_relationship?(:foos)
+    end
+    
+    should "return false for nonexistent relationships" do
+      assert !@model.has_relationship?(:bazs)
+    end
+  end
+  
   context "populating relationships" do
     setup do
       @model = RelatableModel.new

data/test/virtualbox/abstract_model_test.rb

@@ -1,7 +1,12 @@
 require File.join(File.dirname(__FILE__), '..', 'test_helper')
 
 class AbstractModelTest < Test::Unit::TestCase
-  class Foo; end
+  class Foo
+    def self.set_relationship(caller, old_value, new_value)
+      new_value
+    end
+  end
+  
   class Bar; end
   
   class FakeModel < VirtualBox::AbstractModel
@@ -30,6 +35,20 @@ class AbstractModelTest < Test::Unit::TestCase
       @model.save
       assert !@model.new_record?
     end
+    
+    should "become a new record again if new_record! is called" do
+      assert @model.new_record?
+      @model.save
+      assert !@model.new_record?
+      @model.new_record!
+      assert @model.new_record?
+    end
+    
+    should "become an existing record if existing_record! is called" do
+      assert @model.new_record?
+      @model.existing_record!
+      assert !@model.new_record?
+    end
   end
   
   context "subclasses" do
@@ -120,6 +139,18 @@ class AbstractModelTest < Test::Unit::TestCase
     end
   end
   
+  context "integrating relatable" do
+    setup do
+      @model = FakeModel.new
+    end
+    
+    should "set dirty state when a relationship is set" do
+      assert !@model.changed?
+      @model.foos = "foo"
+      assert @model.changed?
+    end
+  end
+  
   context "integrating attributable and dirty" do
     setup do
       @model = FakeModel.new