virtualbox 0.4.3 → 0.5.0

data/.gitignore

@@ -1,6 +1,6 @@
-bin/*
-vendor/gems/*
 doc/*
 .yardoc/*
 pkg/*
-test/coverage/*
+test/coverage/*
+.bundle/*
+Gemfile.lock

data/Gemfile

@@ -1,12 +1,12 @@
-# Gems required for testing only. To install run
-# gem bundle test
-only :test do
+source :gemcutter
+
+# External Dependencies
+gem "nokogiri", "1.4.1"
+
+# Gems required for testing only.
+group :test do
   gem "contest", ">= 0.1.2"
   gem "mocha"
   gem "ruby-debug", ">= 0.10.3" if RUBY_VERSION < '1.9'
   gem "ruby-debug19", ">= 0.11.6" if RUBY_VERSION >= '1.9'
-end
-
-# Makes sure that our code doesn't request gems outside
-# of our dependency list.
-disable_system_gems
+end

data/Rakefile

@@ -8,6 +8,8 @@ begin
     gemspec.homepage = "http://github.com/mitchellh/virtualbox"
     gemspec.authors = ["Mitchell Hashimoto"]
     gemspec.executables = []
+
+    gemspec.add_dependency('nokogiri', '>= 1.4.1')
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/Readme.md

@@ -69,10 +69,19 @@ Please use the [issue tracker](https://github.com/mitchellh/virtualbox/issues).
 ## Contributing
 
 If you'd like to contribute to VirtualBox, the first step to developing is to
-clone this repo, get [wycat's bundler](http://github.com/wycats/bundler) if you
+clone this repo, get [bundler](http://github.com/carlhuda/bundler) if you
 don't have it already, and do the following:
 
-    gem bundle test
+    bundle install
+    bundle lock
     rake
 
 This will run the test suite, which should come back all green! Then you're good to go!
+
+## Special Thanks
+
+These folks went above and beyond with contributions to the virtualbox gem, and
+for that, I have to say "thanks!"
+
+* [Kieran Pilkington](http://github.com/KieranP)
+* [Aleksey Palazhchenko](http://github.com/AlekSi)

data/VERSION

@@ -1 +1 @@
-0.4.3
+0.5.0

data/docs/WhatsNew.md

@@ -1,34 +1,50 @@
-# What's New in 0.4.x?
+# What's New in 0.5.x?
 
-## "Extra Data" on VMs / Global
+## HUGE Speed Boost! Very few system calls!
 
-Extra data is persistent key-value storage which is available as a way to store any information
-wanted. VirtualBox uses it for storing statistics and settings. You can use it for anything!
-Setting extra data on virtual machines is now as easy as a ruby hash:
+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.
 
-    vm = VirtualBox::VM.find("FooVM")
-    vm.extra_data["i_was_here"] = "yes!"
-    vm.save
+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:
 
-Read more about extra data {VirtualBox::ExtraData here}.
+    # Remember, this won't be necessary MOST of the time
+    VirtualBox::Global.vboxconfig = "~/path/to/VirtualBox.xml"
 
-## Port Forwarding
+## Lazy Loading of Attributes and Relationships
 
-If a VM is using NAT for its network, the host machine can't access any outward facing
-services of the guest (for example: a web host, ftp server, etc.). Port forwarding is
-one way to facilitate this need. Port forwarding is straight forward to setup:
+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!
 
-    vm = VirtualBox::VM.find("FooVM")
-    port = VirtualBox::ForwardedPort.new
-    port.name = "http"
-    port.guestport = 80
-    port.hostport = 8080
-    vm.forwarded_ports << port
-    vm.save
+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!
 
-Read more about port forwarding {VirtualBox::ForwardedPort here}.
+## System Properties
 
-## More Ruby Versions Supported!
+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:
 
-Previously, virtualbox only supported 1.8.7. It now supports 1.8.6 and 1.9.x thanks
-to AlekSi.
+    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.

data/lib/virtualbox.rb

@@ -1,4 +1,9 @@
 $:.unshift(File.expand_path(File.dirname(__FILE__)))
+
+# External Dependencies
+require 'nokogiri'
+
+# Internal Dependencies
 require 'virtualbox/exceptions'
 require 'virtualbox/command'
 require 'virtualbox/abstract_model'
@@ -10,9 +15,13 @@ 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'
 
 module VirtualBox
   class <<self

data/lib/virtualbox/abstract_model.rb

@@ -14,6 +14,30 @@ module VirtualBox
     include Relatable
     include Validatable
 
+    class <<self
+      # Returns whether or not the class should be reloaded.
+      #
+      # @return [Boolean]
+      def reload?
+        !!@_reload
+      end
+
+      def reload!
+        @_reload = true
+      end
+
+      def reloaded!
+        @_reload = false
+      end
+    end
+
+    # Signals to the class that it should be reloaded. This simply toggles
+    # a boolean value to true. It is up to the subclass to implement functionality
+    # around it. See {reload?}
+    def reload!
+      self.class.reload!
+    end
+
     # Returns a boolean denoting if the record is new or existing. This
     # method is provided for subclasses to use to differentiate between
     # creating a new object or saving an existing one. An example of this
@@ -78,7 +102,12 @@ module VirtualBox
         save_attribute(key, values[1], *args)
       end
 
-      save_relationships(*args)
+      # Go through and only save the loaded relationships, since
+      # only those would be modified.
+      self.class.relationships.each do |name, options|
+        next if lazy_relationship?(name) && !loaded_relationship?(name)
+        save_relationship(name, *args)
+      end
 
       # No longer a new record
       @new_record = false
@@ -93,6 +122,20 @@ module VirtualBox
       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)
+      return false if new_record?
+      super
+    end
+
+    # Overriding {Relatable#lazy_relationship?} to always return false for
+    # new records, since new records shouldn't load lazy data.
+    def lazy_relationship?(*args)
+      return false if new_record?
+      super
+    end
+
     # Sets the initial attributes from a hash. This method is meant to be used
     # once to initially setup the attributes. It is **not a mass-assignment**
     # method for updating attributes.
@@ -108,21 +151,39 @@ module VirtualBox
     #
     # Calling this method will also cause the model to assume that it is not
     # a new record (see {#new_record?}).
-    def populate_attributes(attribs)
-      # No longer a new record
-      @new_record = false
-
+    def populate_attributes(attribs, opts={})
       ignore_dirty do
-        super
+        super(attribs)
 
-        populate_relationships(attribs)
+        populate_relationships(attribs) unless opts[:ignore_relationships]
       end
+
+      # No longer a new record
+      existing_record!
+    end
+
+    # Loads and populates the relationships with the given data. This method
+    # is meant to be used once to initially setup the relatoinships.
+    #
+    # This methods does **not** affect dirtiness, but also does not clear it.
+    #
+    # Calling this method will also cuase the model to assume that it is not
+    # a new record (see {#new_record?})
+    def populate_relationships(data)
+      existing_record!
+      ignore_dirty { super }
+    end
+
+    # Populates a single relationship with the given data.
+    def populate_relationship(name, data)
+      existing_record!
+      ignore_dirty { super }
     end
 
     # Overwrites {Attributable#write_attribute} to set the dirty state of
     # the written attribute. See {Dirty#set_dirty!} as well.
     def write_attribute(name, value)
-      set_dirty!(name, read_attribute(name), value)
+      set_dirty!(name, read_attribute(name), value) unless lazy_attribute?(name) && !loaded_attribute?(name)
       super
     end
 
@@ -148,12 +209,21 @@ module VirtualBox
     # Creates a human-readable format for this model. This method overrides the
     # default `#<class>` syntax since this doesn't work well for AbstractModels.
     # Instead, it abbreviates it, instead showing all the attributes and their
-    # values, and `...` for relationships.
+    # values, and `...` for relationships. For attributes which are themselves
+    # AbstractModels, it shows the class name to avoid extremely verbose inspections
+    # and infinite loops.
     def inspect
       values = []
 
       self.class.attributes.each do |name, options|
-        values.push("#{name.inspect}=#{read_attribute(name).inspect}")
+        value = read_attribute(name)
+        value = if value.is_a?(AbstractModel)
+          "#<#{value.class.name}>"
+        else
+          value.inspect
+        end
+
+        values.push("#{name.inspect}=#{value}")
       end
 
       self.class.relationships.each do |name, options|

data/lib/virtualbox/abstract_model/attributable.rb

@@ -73,6 +73,50 @@ module VirtualBox
     #       puts path # => "Home"
     #     end
     #
+    # ## Lazy Loading Attributes
+    #
+    # While most attributes are fairly trivial to calculate and populate, sometimes
+    # attributes may have an expensive cost to populate, and are generally not worth
+    # populating unless a user of the class requests that attribute. This is known as
+    # _lazy loading_ the attributes. This is possibly by specifying the `:lazy` option
+    # on the attribute. In this case, the first time (and _only_ the first time) the
+    # attribute is requested, `load_attribute` will be called with the name of the
+    # attribute as the parameter. This method is then expected to call `write_attribute`
+    # on that attribute to give it a value.
+    #
+    #     class ExpensiveAttributeModel
+    #       include VirtualBox::AbstractModel::Attributable
+    #       attribute :expensive_attribute, :lazy => true
+    #
+    #       def load_attribute(name)
+    #         if name == :expensive_attribute
+    #           write_attribute(name, perform_expensive_calculation)
+    #         end
+    #       end
+    #     end
+    #
+    # Using the above definition, we could use the class like so:
+    #
+    #     # Initializing is fast, since no attribute population is done
+    #     model = ExpensiveAttributeModel.new
+    #
+    #     # But this is slow, since it has to calculate.
+    #     puts model.expensive_attribute
+    #
+    #     # But ONLY THE FIRST TIME. This time is FAST!
+    #     puts model.expensive_attribute
+    #
+    # In addition to calling `load_attribute` on initial read, `write_attribute`
+    # when performed on a lazy loaded attribute will mark it as "loaded" so there
+    # will be no load called on the first request. Example, using the above class
+    # once again:
+    #
+    #     model = ExpensiveAttributeModel.new
+    #     model.write_attribute(:expensive_attribute, 42)
+    #
+    #     # This is FAST, since "load_attribute" is not called
+    #     puts model.expensive_attribute # => 42
+    #
     module Attributable
       def self.included(base)
         base.extend ClassMethods
@@ -146,7 +190,7 @@ module VirtualBox
       def populate_attributes(attribs)
         self.class.attributes.each do |key, options|
           value_key = options[:populate_key] || key
-          write_attribute(key, attribs[value_key])
+          write_attribute(key, attribs[value_key]) if attribs.has_key?(value_key)
         end
       end
 
@@ -165,6 +209,11 @@ module VirtualBox
       # if specified.
       def read_attribute(name)
         if has_attribute?(name)
+          if lazy_attribute?(name) && !loaded_attribute?(name)
+            # Load the lazy attribute
+            load_attribute(name.to_sym)
+          end
+
           attributes[name] || self.class.attributes[name][:default]
         end
       end
@@ -179,6 +228,17 @@ module VirtualBox
         self.class.attributes.has_key?(name.to_sym)
       end
 
+      # Returns boolean value denoting if an attribute is "lazy loaded"
+      def lazy_attribute?(name)
+        has_attribute?(name) && self.class.attributes[name.to_sym][:lazy]
+      end
+
+      # Returns boolean value denoting if an attribute has been loaded
+      # yet.
+      def loaded_attribute?(name)
+        attributes.has_key?(name)
+      end
+
       # Returns a boolean value denoting if an attribute is readonly.
       # This method also returns false for **nonexistent attributes**
       # so it should be used in conjunction with {#has_attribute?} if

data/lib/virtualbox/abstract_model/relatable.rb

@@ -78,6 +78,46 @@ module VirtualBox
     #
     # This is not a feature built-in to Relatable but figured it should be
     # mentioned here.
+    #
+    # # Lazy Relationships
+    #
+    # Often, relationships are pretty heavy things to load. Data may have to be
+    # retrieved, classes instantiated, etc. If a class has many relationships, or
+    # many relationships within many relationships, the time and memory required
+    # for relationships really begins to add up. To address this issue, _lazy relationships_
+    # are available. Lazy relationships defer loading their content until the
+    # last possible moment, or rather, when a user requests the data. By specifing
+    # the `:lazy => true` option to relationships, relationships will not be loaded
+    # immediately. Instead, when they're first requested, `load_relationship` will
+    # be called on the model, with the name of the relationship given as a
+    # parameter. It is up to this method to call {#populate_relationship} at some
+    # point with the data to setup the relationship. An example follows:
+    #
+    #     class SomeModel
+    #       include VirtualBox::AbstractModel::Relatable
+    #
+    #       relationship :foos, Foo, :lazy => true
+    #
+    #       def load_relationship(name)
+    #         if name == :foos
+    #           populate_relationship(name, get_data_for_a_long_time)
+    #         end
+    #       end
+    #     end
+    #
+    # Using the above class, we can use it like so:
+    #
+    #     model = SomeModel.new
+    #
+    #     # This initial load takes awhile as it loads...
+    #     model.foos
+    #
+    #     # Instant! (Just a hash lookup. No load necessary)
+    #     model.foos
+    #
+    # One catch: If a model attempts to {#destroy_relationship destroy} a lazy
+    # relationship, it will first load the relationship, since destroy typically
+    # depends on some data of the relationship.
     module Relatable
       def self.included(base)
         base.extend ClassMethods
@@ -99,7 +139,7 @@ module VirtualBox
           relationships << [name, { :klass => klass }.merge(options)]
 
           # Define the method to read the relationship
-          define_method(name) { relationship_data[name] }
+          define_method(name) { read_relationship(name) }
 
           # Define the method to set the relationship
           define_method("#{name}=") { |*args| set_relationship(name, *args) }
@@ -138,9 +178,19 @@ module VirtualBox
         end
       end
 
+      # Reads a relationship. This is equivalent to {Attributable#read_attribute},
+      # but for relationships.
+      def read_relationship(name)
+        if lazy_relationship?(name) && !loaded_relationship?(name)
+          load_relationship(name)
+        end
+
+        relationship_data[name.to_sym]
+      end
+
       # Saves the model, calls save_relationship on all relations. It is up to
       # the relation to determine whether anything changed, etc. Simply
-      # calls `save_relationship` on each relationshp class passing in the
+      # calls `save_relationship` on each relationship class passing in the
       # following parameters:
       #
       # * **caller** - The class which is calling save
@@ -150,20 +200,34 @@ module VirtualBox
       # end and they'll be pushed through to the `save_relationship` method.
       def save_relationships(*args)
         self.class.relationships.each do |name, options|
-          next unless options[:klass].respond_to?(:save_relationship)
-          options[:klass].save_relationship(self, relationship_data[name], *args)
+          save_relationship(name, *args)
         end
       end
 
+      # Saves a single relationship. It is up to the relationship class to
+      # determine whether anything changed and how saving is implemented. Simply
+      # 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)
+      end
+
       # The equivalent to {Attributable#populate_attributes}, but with
       # relationships.
       def populate_relationships(data)
         self.class.relationships.each do |name, options|
-          next unless options[:klass].respond_to?(:populate_relationship)
-          relationship_data[name] = options[:klass].populate_relationship(self, data)
+          populate_relationship(name, data) unless lazy_relationship?(name)
         end
       end
 
+      # 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)
+      end
+
       # Calls `destroy_relationship` on each of the relationships. Any
       # arbitrary args may be added and they will be forarded to the
       # relationship's `destroy_relationship` method.
@@ -181,6 +245,11 @@ module VirtualBox
       def destroy_relationship(name, *args)
         options = self.class.relationships_hash[name]
         return unless options && options[:klass].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)
       end
 
@@ -199,6 +268,19 @@ module VirtualBox
         self.class.has_relationship?(key.to_sym)
       end
 
+      # Returns boolean denoting if a relationship is to be lazy loaded.
+      #
+      # @return [Boolean]
+      def lazy_relationship?(key)
+        options = self.class.relationships_hash[key.to_sym]
+        !options.nil? && options[:lazy]
+      end
+
+      # Returns boolean denoting if a relationship has been loaded.
+      def loaded_relationship?(key)
+        relationship_data.has_key?(key)
+      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