virtualbox 0.5.4 → 0.6.0

data/.gitignore

@@ -3,4 +3,5 @@ doc/*
 pkg/*
 test/coverage/*
 .bundle/*
-Gemfile.lock
+Gemfile.lock
+test.rb

data/Gemfile

@@ -1,7 +1,7 @@
 source :gemcutter
 
 # External Dependencies
-gem "nokogiri", "1.4.1"
+gem "ffi"
 
 # Gems required for testing only.
 group :test do

data/Rakefile

@@ -9,7 +9,7 @@ begin
     gemspec.authors = ["Mitchell Hashimoto"]
     gemspec.executables = []
 
-    gemspec.add_dependency('nokogiri', '>= 1.4.1')
+    gemspec.add_dependency('ffi', '>= 0.6.3')
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/Readme.md

@@ -11,10 +11,9 @@ Windows, Linux, and OS X. After installation, install the gem:
 
     sudo gem install virtualbox
 
-The gem assumes that `VBoxManage` will be available on the `PATH`. If not, before using
-the gem, you must set the path to your `VBoxManage` binary:
-
-    VirtualBox::Command.vboxmanage = "/path/to/my/VBoxManage"
+The gem uses the native COM interface with VirtualBox provides to communicate with
+VirtualBox. On Windows, this is globally available. On Linux-based machines, the gem
+uses Ruby-FFI to talk to a dynamic library. No configuration should be necessary.
 
 ## Basic Usage
 
@@ -33,30 +32,15 @@ Below are some examples:
     vm = VirtualBox::VM.find("my-vm")
 
     # Let's first print out some basic info about the VM
-    puts "Memory: #{vm.memory}"
-
-    vm.storage_controllers.each do |sc|
-      sc.attached_devices.each do |device|
-        puts "Attached Device: #{device.uuid}"
-      end
-    end
+    puts "Memory: #{vm.memory_size}"
 
     # Let's modify the memory and name...
-    vm.memory = 360
+    vm.memory_size = 360
     vm.name = "my-renamed-vm"
 
     # Save it!
     vm.save
 
-Or here is an example of creating a hard drive:
-
-    require 'virtualbox'
-
-    hd = VirtualBox::HardDrive.new
-    hd.location = "foo.vdi"
-    hd.size = 2000 # megabytes
-    hd.save
-
 ## Known Issues or Uncompleted Features
 
 VirtualBox has a _ton_ of features! As such, this gem is still not totally complete.

data/VERSION

@@ -1 +1 @@
-0.5.4
+0.6.0

data/docs/WhatsNew.md

@@ -1,50 +1,12 @@
-# What's New in 0.5.x?
+# What's New in 0.6.x?
 
-## HUGE Speed Boost! Very few system calls!
+## Native Interface
 
-Most of the data retrieved by the virtualbox library now comes via XML parsing, rather
-than making calls to `VBoxManage`. This results in a drastic speedup. The few relationships or
-attributes which require a system call are typically _lazy loaded_ (covered below), so they
-don't incur a performance penalty unless they're used.
+The VirtualBox gem no longer piggy-backs on top of `VBoxManage` or XML configuration files.
+The gem now uses the native interface provided by VirtualBox to communicate. The result of
+this is a _huge_ speed increase which simply would not have been possible otherwise, and
+stability across versions. In addition to that, the entire VirtualBox API is now at your
+disposal. While the gem itself doesn't yet support creating VMs and so on, the API is available
+for you to do it manually (if you really wanted to!).
 
-The one caveat is that you now need to set the path to the global VirtualBox configuration
-XML. The virtualbox library will do its best to guess this path based on the operating
-system, but this is hardly foolproof. To set the virtualbox config path, it is a simple
-one-liner:
-
-    # Remember, this won't be necessary MOST of the time
-    VirtualBox::Global.vboxconfig = "~/path/to/VirtualBox.xml"
-
-## Lazy Loading of Attributes and Relationships
-
-Although still not widely used (will be in future patch releases), some attributes and
-relationships are now _lazy loaded_. This means that since they're probably expensive
-to load (many system calls, heavy parsing, etc.) they aren't loaded initially. Instead,
-they are only loaded if they're used. This means that you don't incur the penalty cost
-of loading them unless you use it! Fantastic!
-
-There is no real "example code" for this feature since to the casual user, it happens
-transparently in the background and generally "just works." If you're _really_ curious,
-then feel free to check out any class which derives from {VirtualBox::AbstractModel}
-and any attribute or relationship with the `:lazy => true` option is lazy loaded!
-
-## System Properties
-
-A small but meaningful update is the ability to view the system properties for the
-host system which VirtualBox is running. This is done via the {VirtualBox::SystemProperty}
-class, which is simply a `Hash`. System properties are immutable properties defined
-by the host system, which typically are limits imposed upon VirtualBox, such as
-maximum RAM size or default path to machine files. Retrieving the system properties
-is quite easy:
-
-    properties = VirtualBox::SystemProperty.all
-    properties.each do |key, value|
-      puts "#{key} = #{value}"
-    end
-
-## USB Device Relationship on VMs
-
-Previously, {VirtualBox::VM VM} object would only be able to tell you if there
-were USB devices enabled or not. Now, `usbs` is a full-fledged relationship
-on VM. This relationship is access just like any other. For more information
-view the {VirtualBox::USB USB} class.
+Future versions will support more and more of the API.

data/lib/virtualbox.rb

@@ -1,34 +1,11 @@
-$:.unshift(File.expand_path(File.dirname(__FILE__)))
+# Load the glob loader, which will handle the loading of all the other files
+libdir = File.join(File.dirname(__FILE__), "virtualbox")
+require File.expand_path("ext/glob_loader", libdir)
 
-# External Dependencies
-require 'nokogiri'
-
-# Internal Dependencies
-require 'virtualbox/ext/platform'
-require 'virtualbox/exceptions'
-require 'virtualbox/command'
-require 'virtualbox/abstract_model'
-require 'virtualbox/proxies/collection'
-require 'virtualbox/image'
-require 'virtualbox/attached_device'
-require 'virtualbox/dvd'
-require 'virtualbox/extra_data'
-require 'virtualbox/forwarded_port'
-require 'virtualbox/hard_drive'
-require 'virtualbox/nic'
-require 'virtualbox/usb'
-require 'virtualbox/shared_folder'
-require 'virtualbox/storage_controller'
-require 'virtualbox/vm'
-require 'virtualbox/media'
-require 'virtualbox/global'
-require 'virtualbox/system_property'
+# Load them up
+VirtualBox::GlobLoader.glob_require(libdir, %w{ext/logger ext/platform ext/subclass_listing com abstract_model medium})
 
+# Setup the top-level module methods
 module VirtualBox
-  class <<self
-    # Returns installed VirtualBox version like '3.1.2r56127'.
-    def version
-      Command.vboxmanage("-v").chomp.strip
-    end
-  end
+  extend Version
 end

data/lib/virtualbox/abstract_model.rb

@@ -1,7 +1,10 @@
-require 'virtualbox/abstract_model/attributable'
-require 'virtualbox/abstract_model/dirty'
-require 'virtualbox/abstract_model/relatable'
-require 'virtualbox/abstract_model/validatable'
+['abstract_model/attributable',
+  'abstract_model/interface_attributes',
+  'abstract_model/dirty',
+  'abstract_model/relatable',
+  'abstract_model/validatable'].each do |lib|
+  require File.expand_path(lib, File.dirname(__FILE__))
+end
 
 module VirtualBox
   # AbstractModel is the base class used for most of virtualbox's classes.
@@ -9,7 +12,10 @@ module VirtualBox
   #
   # @abstract
   class AbstractModel
+    include Logger
+
     include Attributable
+    include InterfaceAttributes
     include Dirty
     include Relatable
     include Validatable
@@ -122,6 +128,20 @@ module VirtualBox
       clear_dirty!(key)
     end
 
+    # Saves only changed interface attributes.
+    def save_changed_interface_attributes(interface)
+      changes.each do |key, values|
+        save_interface_attribute(key, interface)
+      end
+    end
+
+    # Overrides {InterfaceAttributes.save_interface_attribute} to clear the
+    # dirty state of the attribute.
+    def save_interface_attribute(key, interface)
+      super
+      clear_dirty!(key)
+    end
+
     # Overriding {Attributable#lazy_attribute?} to always return false for
     # new records, since new records shouldn't load lazy data.
     def lazy_attribute?(*args)
@@ -217,7 +237,7 @@ module VirtualBox
 
       self.class.attributes.each do |name, options|
         value = read_attribute(name)
-        value = if value.is_a?(AbstractModel)
+        value = if value.is_a?(AbstractModel) || value.is_a?(COM::AbstractInterface)
           "#<#{value.class.name}>"
         else
           value.inspect

data/lib/virtualbox/abstract_model/attributable.rb

@@ -214,7 +214,11 @@ module VirtualBox
             load_attribute(name.to_sym)
           end
 
-          attributes[name] || self.class.attributes[name][:default]
+          if attributes[name].nil?
+            self.class.attributes[name][:default]
+          else
+            attributes[name]
+          end
         end
       end
 

data/lib/virtualbox/abstract_model/dirty.rb

@@ -93,6 +93,8 @@ module VirtualBox
       # @param [Object] value The new value being set
       def set_dirty!(name, current, value)
         if current != value
+          name = name.to_sym
+
           # If its the first time this attribute has changed, store the
           # original value in the first field
           changes[name] ||= [current, nil]

data/lib/virtualbox/abstract_model/interface_attributes.rb

@@ -0,0 +1,96 @@
+module VirtualBox
+  class AbstractModel
+    # Module which can be included which defines helper methods to DRY out the
+    # code which handles attributes with {VirtualBox::COM} interfaces. This
+    # module works _alongside_ the {Attributable} module, so **both are required**.
+    module InterfaceAttributes
+      # Loads the attributes which have an interface getter and writes
+      # their values.
+      #
+      # @param [VirtualBox::COM::Interface] interface
+      def load_interface_attributes(interface)
+        self.class.attributes.each do |key, options|
+          load_interface_attribute(key, interface)
+        end
+      end
+
+      # Loads a single interface attribute.
+      #
+      # @param [Symbol] key The attribute to load
+      # @param [VirtualBox::COM::Interface] interface The interface
+      def load_interface_attribute(key, interface)
+        # Return unless we have a valid interface attribute with a getter
+        return unless has_attribute?(key)
+        options = self.class.attributes[key.to_sym]
+        return if options.has_key?(:property) && !options[:property]
+        getter = options[:property] || options[:property_getter] || key.to_sym
+        return unless getter
+
+        # Convert the getter to a proc and call it
+        getter = spec_to_proc(getter)
+        write_attribute(key, getter.call(interface))
+      end
+
+      # Saves all the attributes which have an interface setter.
+      def save_interface_attributes(interface)
+        self.class.attributes.each do |key, options|
+          save_interface_attribute(key, interface)
+        end
+      end
+
+      # Saves a single interface attribute
+      #
+      # @param [Symbol] key The attribute to write
+      # @param [VirtualBox::COM::Interface] interface The interface
+      # @param [Object] value The value to write
+      def save_interface_attribute(key, interface)
+        # Return unless we have a valid interface attribute with a setter
+        return unless has_attribute?(key)
+        options = self.class.attributes[key.to_sym]
+        return if options[:readonly]
+        return if options.has_key?(:property) && !options[:property]
+
+        setter = options[:property] || options[:property_setter] || "#{key}=".to_sym
+        return unless setter
+
+        # Convert the setter to a proc and call it
+        setter = spec_to_proc(setter)
+        setter.call(interface, read_attribute(key))
+      end
+
+      # Converts a getter/setter specification to a Proc which can be called
+      # to obtain or set a value. There are multiple ways to specify the getter
+      # and/or setter of an interface attribute:
+      #
+      # ## Symbol
+      #
+      # A symbol represents a method to call on the interface. An example of the
+      # declaration and resulting method call are shown below:
+      #
+      #     attribute :foo, :property_getter => :get_foo
+      #
+      # Converts to:
+      #
+      #     interface.get_foo
+      #
+      # ## Proc
+      #
+      # A proc is called with the interface and it is expected to return the value
+      # for a getter. For a setter, the interface and the value is sent in as
+      # parameters to the Proc.
+      #
+      #     attribute :foo, :property_getter => Proc.new { |i| i.get_foo }
+      #
+      def spec_to_proc(spec)
+        # Return the spec as-is if its a proc
+        return spec if spec.is_a?(Proc)
+
+        if spec.is_a?(Symbol)
+          # For symbols, wrap up a method send in a Proc and return
+          # that
+          return Proc.new { |m, *args| m.send(spec, *args) }
+        end
+      end
+    end
+  end
+end

data/lib/virtualbox/abstract_model/relatable.rb

@@ -209,8 +209,8 @@ module VirtualBox
       # calls `save_relationship` on the relationship class.
       def save_relationship(name, *args)
         options = self.class.relationships_hash[name]
-        return unless options[:klass].respond_to?(:save_relationship)
-        options[:klass].save_relationship(self, relationship_data[name], *args)
+        return unless relationship_class(name).respond_to?(:save_relationship)
+        relationship_class(name).save_relationship(self, relationship_data[name], *args)
       end
 
       # The equivalent to {Attributable#populate_attributes}, but with
@@ -224,8 +224,8 @@ module VirtualBox
       # Populate a single relationship.
       def populate_relationship(name, data)
         options = self.class.relationships_hash[name]
-        return unless options[:klass].respond_to?(:populate_relationship)
-        relationship_data[name] = options[:klass].populate_relationship(self, data)
+        return unless relationship_class(name).respond_to?(:populate_relationship)
+        relationship_data[name] = relationship_class(name).populate_relationship(self, data)
       end
 
       # Calls `destroy_relationship` on each of the relationships. Any
@@ -244,13 +244,13 @@ module VirtualBox
       # @param [Symbol] name The name of the relationship
       def destroy_relationship(name, *args)
         options = self.class.relationships_hash[name]
-        return unless options && options[:klass].respond_to?(:destroy_relationship)
+        return unless options && relationship_class(name).respond_to?(:destroy_relationship)
 
         # Read relationship, which forces lazy relationships to load, which is
         # probably necessary for destroying
         read_relationship(name)
 
-        options[:klass].destroy_relationship(self, relationship_data[name], *args)
+        relationship_class(name).destroy_relationship(self, relationship_data[name], *args)
       end
 
       # Hash to data associated with relationships. You should instead
@@ -281,6 +281,17 @@ module VirtualBox
         relationship_data.has_key?(key)
       end
 
+      # Returns the class for a given relationship. This method handles converting
+      # a string/symbol into the proper class.
+      #
+      # @return [Class]
+      def relationship_class(key)
+        options = self.class.relationships_hash[key.to_sym]
+        klass = options[:klass]
+        klass = Object.module_eval("#{klass}") unless klass.is_a?(Class)
+        klass
+      end
+
       # Sets a relationship to the given value. This is not guaranteed to
       # do anything, since "set_relationship" will be called on the class
       # that the relationship is associated with and its expected to return
@@ -299,8 +310,8 @@ module VirtualBox
         relationship = self.class.relationships_hash[key]
         return unless relationship
 
-        raise Exceptions::NonSettableRelationshipException.new unless relationship[:klass].respond_to?(:set_relationship)
-        relationship_data[key] = relationship[:klass].set_relationship(self, relationship_data[key], value)
+        raise Exceptions::NonSettableRelationshipException.new unless relationship_class(key).respond_to?(:set_relationship)
+        relationship_data[key] = relationship_class(key).set_relationship(self, relationship_data[key], value)
       end
     end
   end

data/lib/virtualbox/appliance.rb

@@ -0,0 +1,59 @@
+module VirtualBox
+  # Represents an VirtualBox "appliance" which is an exported virtual machine or
+  # virtual machines. Appliances typically come with an OVF file and one or more
+  # compressed hard disks, and can be used to import directly into other VirtualBox
+  # installations. Appliances allow for virtual machine portability.
+  class Appliance < AbstractModel
+    attribute :path
+    attribute :interface, :readonly => true, :property => false
+    relationship :virtual_systems, :VirtualSystemDescription
+
+    def initialize(*args)
+      write_attribute(:interface, Lib.lib.virtualbox.create_appliance)
+
+      initialize_from_path(*args) if args.length == 1
+
+      clear_dirty!
+    end
+
+    # Initializes this Appliance instance from a path to an OVF file. This sets
+    # up the relationships and so on.
+    #
+    # @param [String] path Path to the OVF file.
+    def initialize_from_path(path)
+      # Read in the data from the path
+      interface.read(path).wait_for_completion(-1)
+
+      # Interpret the data to fill in the interface properties
+      interface.interpret
+
+      # Load the interface attributes
+      load_interface_attributes(interface)
+
+      # Fill in the virtual systems
+      populate_relationship(:virtual_systems, interface.virtual_system_descriptions)
+
+      # Should be an existing record
+      existing_record!
+    end
+
+    # Imports the machines associated with this appliance. If a block is given,
+    # it will be yielded every percent that the operation progresses. This can be
+    # done to check the progress of the import.
+    def import(&block)
+      interface.import_machines.wait(&block)
+    end
+
+    # Exports the machines to the given path. If a block is given, it will be yielded
+    # every percent that the operation progresses. This can be done to check the progress
+    # of the export in real-time.
+    def export(&block)
+      interface.write("ovf-1.0", path).wait(&block)
+    end
+
+    # Adds a VM to the appliance
+    def add_machine(vm)
+      vm.interface.export(interface)
+    end
+  end
+end