virtualbox 0.4.3 → 0.5.0

data/lib/virtualbox/attached_device.rb

@@ -72,6 +72,7 @@ module VirtualBox
     attribute :parent, :readonly => true
     attribute :uuid, :readonly => true
     attribute :port
+    attribute :type, :readonly => true
     relationship :image, Image
 
     class <<self
@@ -84,10 +85,8 @@ module VirtualBox
         relation = Proxies::Collection.new(caller)
 
         counter = 0
-        loop do
-          break unless data["#{caller.name}-#{counter}-0".downcase.to_sym]
-          nic = new(counter, caller, data)
-          relation.push(nic)
+        data.css("AttachedDevice").each do |ad|
+          relation << new(counter, caller, ad)
           counter += 1
         end
 
@@ -230,12 +229,21 @@ module VirtualBox
     #
     # **This method should never be called except internally.**
     def populate_from_data(index, caller, data)
-      populate_attributes({
-        :parent => caller,
-        :port => index,
-        :medium => data["#{caller.name}-#{index}-0".downcase.to_sym],
-        :uuid => data["#{caller.name}-ImageUUID-#{index}-0".downcase.to_sym]
-      })
+      # Get the regular attributes
+      attrs = {}
+      data.attributes.each do |key, value|
+        attrs[key.downcase.to_sym] = value.to_s
+      end
+
+      # Get the Image UUID
+      image = data.css("Image")
+      if image.empty?
+        attrs[:uuid] = nil
+      else
+        attrs[:uuid] = image[0]["uuid"][1..-2]
+      end
+
+      populate_attributes(attrs.merge({ :parent => caller }))
     end
   end
 end

data/lib/virtualbox/command.rb

@@ -14,6 +14,19 @@ module VirtualBox
     @@vboxmanage = "VBoxManage"
 
     class <<self
+      # Reads the XML file and returns a Nokogiri document. Reads the XML data
+      # from the specified file and returns a Nokogiri document.
+      #
+      # @param [String] File name.
+      # @return [Nokogiri::XML::Document]
+      def parse_xml(filename)
+        f = File.open(filename, "r")
+        result = Nokogiri::XML(f)
+        f.close
+
+        result
+      end
+
       # 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.

data/lib/virtualbox/dvd.rb

@@ -22,6 +22,12 @@ module VirtualBox
     class <<self
       # Returns an array of all available DVDs as DVD objects
       def all
+        Global.global.media.dvds
+      end
+
+      # Returns an array of all available DVDs by parsing the VBoxManage
+      # output
+      def all_from_command
         raw = Command.vboxmanage("list", "dvds")
         parse_raw(raw)
       end
@@ -34,6 +40,26 @@ module VirtualBox
       def empty_drive
         new(:empty_drive)
       end
+
+      def populate_relationship(caller, doc)
+        result = Proxies::Collection.new(caller)
+
+        # TODO: Location in this case is relative the vboxconfig path.
+        # We need to expand it. Also, size/accessible is not available.
+        doc.css("MediaRegistry DVDImages Image").each do |hd_node|
+          data = {}
+          hd_node.attributes.each do |key, value|
+            data[key.downcase.to_sym] = value.to_s
+          end
+
+          # Massage UUID to proper format
+          data[:uuid] = data[:uuid][1..-2]
+
+          result << new(data)
+        end
+
+        result
+      end
     end
 
     def initialize(*args)
@@ -70,10 +96,19 @@ module VirtualBox
       return false if empty_drive?
 
       Command.vboxmanage("closemedium", "dvd", uuid, "--delete")
+      Global.reload!
       true
     rescue Exceptions::CommandFailedException
       raise if raise_errors
       false
     end
+
+    # Lazy load the lazy attributes for this model.
+    def load_attribute(name)
+      # Since the lazy attributes are related, we just load them all at once
+      loaded_image = self.class.all_from_command.detect { |o| o.uuid == self.uuid }
+
+      write_attribute(:accessible, loaded_image.accessible)
+    end
   end
 end

data/lib/virtualbox/exceptions.rb

@@ -5,6 +5,7 @@ module VirtualBox
     class Exception < ::Exception; end
 
     class CommandFailedException < Exception; end
+    class ConfigurationException < Exception; end
     class InvalidRelationshipObjectException < Exception; end
     class NonSettableRelationshipException < Exception; end
     class ValidationFailedException < Exception; end

data/lib/virtualbox/extra_data.rb

@@ -46,37 +46,26 @@ module VirtualBox
       # @return [Array<ExtraData>]
       def global(reload=false)
         if !@@global_data || reload
-          raw = Command.vboxmanage("getextradata", "global", "enumerate")
-          @@global_data = parse_kv_pairs(raw)
+          @@global_data = Global.global.extra_data
         end
 
         @@global_data
       end
 
-      # Parses the key-value pairs from the extra data enumerated
-      # output.
-      #
-      # @param [String] raw The raw output from enumerating extra data.
-      # @return [Hash]
-      def parse_kv_pairs(raw, parent=nil)
-        data = new(parent)
-        raw.split("\n").each do |line|
-          next unless line =~ /^Key: (.+?), Value: (.+?)$/i
-          data[$1.to_s] = $2.strip.to_s
-        end
-
-        data.clear_dirty!
-        data
-      end
-
       # Populates a relationship with another model.
       #
       # **This method typically won't be used except internally.**
       #
       # @return [Array<ExtraData>]
-      def populate_relationship(caller, data)
-        raw = Command.vboxmanage("getextradata", caller.name, "enumerate")
-        parse_kv_pairs(raw, caller)
+      def populate_relationship(caller, doc)
+        data = new(caller)
+
+        doc.css("ExtraData ExtraDataItem").each do |extradata|
+          data[extradata["name"].to_s] = extradata["value"].to_s
+        end
+
+        data.clear_dirty!
+        data
       end
 
       # Saves the relationship. This simply calls {#save} on every

data/lib/virtualbox/global.rb

@@ -0,0 +1,126 @@
+module VirtualBox
+  # Represents the VirtualBox main configuration file (VirtualBox.xml)
+  # which VirtualBox uses to keep track of all known virtual machines
+  # and images. This "global" configuration has many relationships which
+  # allow the user to retrieve a list of all VMs, media, global extra data,
+  # etc. Indeed, even methods like {VM.all} are implemented using this class.
+  #
+  # # Setting the Path to VirtualBox.xml
+  #
+  # **This is extremely important.**
+  #
+  # Much of the virtualbox gem requires a proper path to the global XML configuration
+  # file for VirtualBox. This path is system and installation dependent. {Global}
+  # does its best to guess the path by trying the default paths based on the
+  # platform ruby is running on, but this is hardly foolproof. If you receive an
+  # {Exceptions::ConfigurationException} at some point while running virtualbox,
+  # you should use {Global.vboxconfig=} to set the path. An example is below:
+  #
+  #     # Most installations won't need to do this, since the gem "guesses"
+  #     # the path based on OS, but if you need to set vboxconfig path
+  #     # explicitly:
+  #     VirtualBox::Global.vboxconfig = "~/.MyCustom/VirtualBox.xml"
+  #
+  # # Getting Global Data
+  #
+  # To retrieve the global data, use `Global.global`. This value is _cached_
+  # between calls, so subsequent calls will not go through the entire parsing
+  # process. To force a reload, set the `reload` parameter to true. Besides
+  # setting the parameter explicitly, some actions will implicitly force the
+  # global data to reload on the next call, such as saving a VM or destroying
+  # an image, for example.
+  #
+  #     # Retrieve global data for the first time. This will parse all the
+  #     # data.
+  #     global_object = VirtualBox::Global.global
+  #
+  #     # Subsequent calls are near-instant:
+  #     VirtualBox::Global.global
+  #
+  #     # Or we can choose to reload the data...
+  #     reloaded_object = VirtualBox::Global.global(true)
+  #
+  # # Relationships
+  #
+  # While a global object doesn't have attributes, it does have many
+  # relationships. The relationships are listed below. If you don't
+  # understand this, read {Relatable}.
+  #
+  #     relationship :vms, VM, :lazy => true
+  #     relationship :media, Media
+  #     relationship :extra_data, ExtraData
+  #
+  class Global < AbstractModel
+    # The path to the global VirtualBox XML configuration file. This is
+    # entirely system dependent and can be set with {vboxconfig=}. The default
+    # is guessed based on the platform.
+    #
+    # TODO: Windows
+    @@vboxconfig = if RUBY_PLATFORM.downcase.include?("darwin")
+      "~/Library/VirtualBox/VirtualBox.xml"
+    elsif RUBY_PLATFORM.downcase.include?("linux")
+      "~/.VirtualBox/VirtualBox.xml"
+    else
+      "Unknown"
+    end
+
+    relationship :vms, VM, :lazy => true
+    relationship :media, Media
+    relationship :extra_data, ExtraData
+
+    @@global_data = nil
+
+    class <<self
+      # Retrieves the global data. The return value of this call is cached,
+      # and can be reloaded by setting the `reload` parameter to true. Besides
+      # explicitly setting the parameter, some actions within the library
+      # force global to reload itself on the next call, such as saving a VM,
+      # or destroying an image.
+      #
+      # @param [Boolean] reload True if you want to force a reload of the data.
+      # @return [Global]
+      def global(reload = false)
+        if !@@global_data || reload || reload?
+          @@global_data = new(config)
+          reloaded!
+        end
+
+        @@global_data
+      end
+
+      # Sets the path to the VirtualBox.xml file. This file should already
+      # exist. VirtualBox itself manages this file, not this library.
+      #
+      # @param [String] Full path to the VirtualBox.xml file
+      def vboxconfig=(value)
+        @@vboxconfig = value
+      end
+
+      # Returns the XML document of the configuration. This will raise an
+      # {Exceptions::ConfigurationException} if the vboxconfig file doesn't
+      # exist.
+      #
+      # @return [Nokogiri::XML::Document]
+      def config
+        raise Exceptions::ConfigurationException.new("The path to the global VirtualBox config must be set. See Global.vboxconfig=") unless File.exist?(File.expand_path(@@vboxconfig))
+        Command.parse_xml(File.expand_path(@@vboxconfig))
+      end
+
+      # Expands path relative to the configuration file.
+      #
+      # @return [String]
+      def expand_path(path)
+        File.expand_path(path, File.dirname(@@vboxconfig))
+      end
+    end
+
+    def initialize(document)
+      @document = document
+      populate_attributes(@document)
+    end
+
+    def load_relationship(name)
+      populate_relationship(:vms, @document)
+    end
+  end
+end

data/lib/virtualbox/hard_drive.rb

@@ -78,21 +78,15 @@ module VirtualBox
   #
   class HardDrive < Image
     attribute :format, :default => "VDI"
-    attribute :size
+    attribute :size, :lazy => true
 
     class <<self
       # Returns an array of all available hard drives as HardDrive
       # objects.
       #
-      # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
-      #   will be raised if the command failed.
       # @return [Array<HardDrive>]
-      def all(raise_errors=false)
-        raw = Command.vboxmanage("list", "hdds")
-        parse_blocks(raw).collect { |v| find(v[:uuid], raise_errors) }
-      rescue Exceptions::CommandFailedException
-        raise if raise_errors
-        false
+      def all
+        Global.global.media.hard_drives
       end
 
       # Finds one specific hard drive by UUID or file name. If the
@@ -117,6 +111,27 @@ module VirtualBox
         raise if raise_errors
         nil
       end
+
+      def populate_relationship(caller, doc)
+        result = Proxies::Collection.new(caller)
+
+        doc.css("MediaRegistry HardDisks HardDisk").each do |hd_node|
+          data = {}
+          hd_node.attributes.each do |key, value|
+            data[key.downcase.to_sym] = value.to_s
+          end
+
+          # Strip the brackets off of UUID
+          data[:uuid] = data[:uuid][1..-2]
+
+          # Expand location relative to config location
+          data[:location] = Global.expand_path(data[:location]) if data[:location]
+
+          result << new(data)
+        end
+
+        result
+      end
     end
 
     # Clone hard drive, possibly also converting formats. All formats
@@ -215,5 +230,14 @@ module VirtualBox
       raise if raise_errors
       false
     end
+
+    # Lazy load the lazy attributes for this model.
+    def load_attribute(name)
+      # Since the lazy attributes are related, we just load them all at once
+      loaded_hd = self.class.find(uuid, true)
+
+      write_attribute(:size, loaded_hd.size)
+      write_attribute(:accessible, loaded_hd.accessible)
+    end
   end
 end

data/lib/virtualbox/image.rb

@@ -19,7 +19,7 @@ module VirtualBox
 
     attribute :uuid, :readonly => true
     attribute :location
-    attribute :accessible, :readonly => true
+    attribute :accessible, :readonly => true, :lazy => true
 
     class <<self
       # Parses the raw output of virtualbox into image objects. Used by
@@ -72,8 +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?
+        return DVD.empty_drive if data[:uuid].nil?
 
         subclasses.each do |subclass|
           next unless subclass.respond_to?(:all)

data/lib/virtualbox/media.rb

@@ -0,0 +1,19 @@
+module VirtualBox
+  # Represents the media registry within the global VirtualBox configuration.
+  class Media < AbstractModel
+    attribute :parent, :readonly => true
+    relationship :hard_drives, HardDrive
+    relationship :dvds, DVD
+
+    class <<self
+      def populate_relationship(caller, data)
+        new(caller, data)
+      end
+    end
+
+    def initialize(parent, document)
+      populate_attributes({ :parent => parent }, :ignore_relationships => true)
+      populate_relationships(document)
+    end
+  end
+end

data/lib/virtualbox/nic.rb

@@ -35,72 +35,22 @@ module VirtualBox
   class Nic < AbstractModel
     attribute :parent, :readonly => :readonly
     attribute :nic
-    attribute :nictype
-    attribute :macaddress
-    attribute :cableconnected
+    attribute :nictype, :populate_key => "type"
+    attribute :macaddress, :populate_key => "MACAddress"
+    attribute :cableconnected, :populate_key => "cable"
     attribute :bridgeadapter
 
     class <<self
-      # Retrives the Nic data from human-readable vminfo. Since some data about
-      # nics is not exposed in the machine-readable virtual machine info, some
-      # extra parsing must be done to get these attributes. This method parses
-      # the nic-specific data from this human readable information.
-      #
-      # **This method typically won't be used except internally.**
-      #
-      # @return [Hash]
-      def nic_data(vmname)
-        raw = VM.human_info(vmname)
-
-        # Complicated chain of methods just maps parse_nic over each line,
-        # removing invalid ones, and then converting it into a single hash.
-        raw.split("\n").collect { |v| parse_nic(v) }.compact.inject({}) do |acc, obj|
-          acc.merge({ obj[0] => obj[1] })
-        end
-      end
-
-      # Parses nic data out of a single line of the human readable output
-      # of vm info.
-      #
-      # **This method typically won't be used except internally.**
-      #
-      # @return [Array] First element is nic name, second is data.
-      def parse_nic(raw)
-        return unless raw =~ /^NIC\s(\d):\s+(.+?)$/
-        return if $2.to_s.strip == "disabled"
-
-        data = {}
-        nicname = "nic#{$1}"
-        $2.to_s.split(/,\s+/).each do |raw_property|
-          next unless raw_property =~ /^(.+?):\s+(.+?)$/
-
-          data[$1.downcase.to_sym] = $2.to_s
-        end
-
-        return nicname.to_sym, data
-      end
-
       # Populates the nic relationship for anything which is related to it.
       #
       # **This method typically won't be used except internally.**
       #
       # @return [Array<Nic>]
-      def populate_relationship(caller, data)
-        nic_data = nic_data(caller.name)
-
-        relation = []
-
-        counter = 1
-        loop do
-          break unless data["nic#{counter}".to_sym]
+      def populate_relationship(caller, doc)
+        relation = Proxies::Collection.new(caller)
 
-          nictype = nic_data["nic#{counter}".to_sym][:type] rescue nil
-
-          nic = new(counter, caller, data.merge({
-            "nictype#{counter}".to_sym => nictype
-          }))
-          relation.push(nic)
-          counter += 1
+        doc.css("Hardware Network Adapter").each do |adapter|
+          relation << new(caller, adapter)
         end
 
         relation
@@ -121,21 +71,32 @@ module VirtualBox
     # Since there is currently no way to create a _new_ nic, this is
     # only used internally. Developers should NOT try to initialize their
     # own nic objects.
-    def initialize(index, caller, data)
+    def initialize(caller, data)
       super()
 
-      @index = index
+      @index = data["slot"].to_i + 1
+
+      # Set the parent
+      write_attribute(:parent, caller)
+
+      # Convert each attribute value to a string
+      attrs = {}
+      data.attributes.each do |key, value|
+        attrs[key] = value.to_s
+      end
+
+      populate_attributes(attrs)
 
-      # Setup the index specific attributes
-      populate_data = {}
-      self.class.attributes.each do |name, options|
-        value = data["#{name}#{index}".to_sym]
-        populate_data[name] = value
+      # The `nic` attribute is a bit more complicated, but not by
+      # much
+      if data["enabled"] == "true"
+        write_attribute(:nic, data.children[1].name.downcase)
+      else
+        write_attribute(:nic, "none")
       end
 
-      populate_attributes(populate_data.merge({
-        :parent => caller
-      }))
+      # Clear dirtiness
+      clear_dirty!
     end
 
     # Saves a single attribute of the nic. This method is automatically