virtualbox 0.5.4 → 0.6.0

data/lib/virtualbox/attached_device.rb

@@ -1,249 +0,0 @@
-module VirtualBox
-  # Represents an device which is attached to a storage controller. An example
-  # of such a device would be a CD or hard drive attached to an IDE controller.
-  #
-  # # Creating a New Attached Device
-  #
-  # Creating a new attached device is simple. The following is a simple example
-  # of creating a DVD with an empty drive:
-  #
-  #     ad = VirtualBox::AttachedDevice.new
-  #     ad.port = 0
-  #     ad.image = VirtualBox::DVD.empty_drive
-  #     storage_controller.devices << ad
-  #     ad.save
-  #
-  # The only quirk is that the attached device **must** be attached to a
-  # storage controller. The above assumes that `storage_controller` exists,
-  # which adds the device.
-  #
-  # Any {Image} subclass can be set to the `image` relationship.
-  #
-  # The following is an example using {VM.find}:
-  #
-  #     # First creating the new device...
-  #     ad = VirtualBox::AttachedDevice.new
-  #     ad.port = 0
-  #     ad.image = VirtualBox::DVD.empty_drive
-  #
-  #     # Now attaching to existing VM
-  #     vm = VirtualBox::VM.find("FooVM")
-  #     vm.storage_controllers[0].devices << ad
-  #     vm.save
-  #
-  # The interesting thing in this example is that the `save` method is called on
-  # the virtual machine rather than the AttachedDevice. This will actually work
-  # as expected! Saving a virtual machine automatically saves all it's relationships
-  # as well.
-  #
-  # # Attributes and Relationships
-  #
-  # Properties of the model are exposed using standard ruby instance
-  # methods which are generated on the fly. Because of this, they are not listed
-  # below as available instance methods.
-  #
-  # These attributes can be accessed and modified via standard ruby-style
-  # `instance.attribute` and `instance.attribute=` methods. The attributes are
-  # listed below.
-  #
-  # Relationships are also accessed like attributes but can't be set. Instead,
-  # they are typically references to other objects such as an {AttachedDevice} which
-  # in turn have their own attributes which can be modified.
-  #
-  # ## Attributes
-  #
-  # This is copied directly from the class header, but lists all available
-  # attributes. If you don't understand what this means, read {Attributable}.
-  #
-  #     attribute :parent, :readonly => true
-  #     attribute :uuid
-  #     attribute :medium
-  #     attribute :port
-  #
-  # ## Relationships
-  #
-  # In addition to the basic attributes, a virtual machine is related
-  # to other things. The relationships are listed below. If you don't
-  # understand this, read {Relatable}.
-  #
-  #     relationship :image, Image
-  #
-  class AttachedDevice < AbstractModel
-    attribute :parent, :readonly => true
-    attribute :uuid, :readonly => true
-    attribute :port
-    attribute :type, :readonly => true
-    relationship :image, Image
-
-    class <<self
-      # Populate relationship with another model.
-      #
-      # **This method typically won't be used except internally.**
-      #
-      # @return [Array<AttachedDevice>]
-      def populate_relationship(caller, data)
-        relation = Proxies::Collection.new(caller)
-
-        counter = 0
-        data.css("AttachedDevice").each do |ad|
-          relation << new(counter, caller, ad)
-          counter += 1
-        end
-
-        relation
-      end
-
-      # Destroy attached devices associated with another model.
-      #
-      # **This method typically won't be used except internally.**
-      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 |ad|
-          ad.save
-        end
-      end
-    end
-
-    # @overload initialize(data={})
-    #   Creates a new AttachedDevice which is a new record. This
-    #   should be attached to a storage controller and saved.
-    #   @param [Hash] data (optional) A hash which contains initial attribute
-    #     values for the AttachedDevice.
-    # @overload initialize(index, caller, data)
-    #   Creates an AttachedDevice for a relationship. **This should
-    #   never be called except internally.**
-    #   @param [Integer] index Index of the port
-    #   @param [Object] caller The parent
-    #   @param [Hash] data A hash of data which must be used
-    #     to extract the relationship data.
-    def initialize(*args)
-      super()
-
-      if args.length == 3
-        populate_from_data(*args)
-      elsif args.length == 1
-        populate_attributes(*args)
-        new_record!
-      elsif args.empty?
-        return
-      else
-        raise NoMethodError.new
-      end
-    end
-
-    # Validates an attached device.
-    def validate
-      super
-
-      validates_presence_of :parent
-      validates_presence_of :image
-      validates_presence_of :port
-    end
-
-    # Saves or creates an attached device.
-    #
-    # @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)
-      return true unless changed?
-
-      if !valid?
-        raise Exceptions::ValidationFailedException.new(errors) if raise_errors
-        return false
-      end
-
-      # If the port changed, we have to destroy the old one, then create
-      # a new one
-      destroy({:port => port_was}, raise_errors) if port_changed? && !port_was.nil?
-
-      Command.vboxmanage("storageattach", parent.parent.name, "--storagectl", parent.name, "--port", port, "--device", "0", "--type", image.image_type, "--medium", medium)
-      existing_record!
-      clear_dirty!
-
-      true
-    rescue Exceptions::CommandFailedException
-      raise if raise_errors
-      false
-    end
-
-    # Medium of the attached image. This attribute will be dependent
-    # on the attached image and will return one of the following values:
-    #
-    # * **none** - There is no attached image
-    # * **emptydrive** - An image with an empty drive is attached (see
-    #     {DVD.empty_drive})
-    # * **image uuid** - The image's UUID
-    #
-    # @return [String]
-    def medium
-      if image.nil?
-        "none"
-      elsif image.empty_drive?
-        "emptydrive"
-      else
-        image.uuid
-      end
-    end
-
-    # Destroys the attached device. By default, this only removes any
-    # media inserted within the device, but does not destroy it. This
-    # option can be specified, however, through the `destroy_image`
-    # option.
-    #
-    # @option options [Boolean] :destroy_image (false) If true, will also
-    #   destroy the image associated with device.
-    # @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(options={}, raise_errors=false)
-      # parent = storagecontroller
-      # parent.parent = vm
-      destroy_port = options[:port] || port
-      Command.vboxmanage("storageattach", parent.parent.name, "--storagectl", parent.name, "--port", destroy_port, "--device", "0", "--medium", "none")
-      image.destroy(raise_errors) if options[:destroy_image] && image
-    rescue Exceptions::CommandFailedException
-      raise if raise_errors
-      false
-    end
-
-    # Relationship callback when added to a collection. This is automatically
-    # called by any relationship collection when this object is added.
-    def added_to_relationship(parent)
-      write_attribute(:parent, parent)
-    end
-
-    protected
-
-    # Populates the model based on data from a parsed vminfo. This
-    # method is used to create a model which already exists and is
-    # part of a relationship.
-    #
-    # **This method should never be called except internally.**
-    def populate_from_data(index, caller, data)
-      # 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

@@ -1,109 +0,0 @@
-module VirtualBox
-  def self.version
-    Command.version
-  end
-
-  # Used by the rest of the virtualbox library to call shell commands.
-  # It also can be used to change the path for your VBoxManage program.
-  #
-  # # Changing VBoxManage Path
-  #
-  # The rest of the library won't work without a proper path to VBoxManage,
-  # so it is crucial to set this properly right away. By default its set
-  # to `VBoxManage` which assumes that it is in your `PATH`.
-  #
-  #     VirtualBox::Command.vboxmanage = "/opt/local/bin/VBoxManage"
-  #
-  class Command
-    @@vboxmanage = "VBoxManage"
-
-    class <<self
-      # Returns a string of the version of VirtualBox installed, or nil if
-      # it can't detect VirtualBox.
-      #
-      # @return [String]
-      def version
-        result = execute("#{@@vboxmanage} --version")
-        return nil unless Command.success?
-        result.chomp
-      end
-
-      # 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.
-      def success?
-        $?.to_i == 0
-      end
-
-      # Sets the path to VBoxManage, which is required for this gem to
-      # work.
-      #
-      # @param [String] Full path to `VBoxManage`.
-      def vboxmanage=(path)
-        @@vboxmanage = path
-      end
-
-      # Runs a VBoxManage command and returns the output. This method will automatically
-      # shell escape all args passed to it. There is no way to avoid this at the moment
-      # (since it hasn't been necessary to). This will raise an {Exceptions::CommandFailedException}
-      # if the exit status of the command is nonzero. It is up to the caller to figure
-      # out how to handle this; there is no way to suppress it via a parameter to this
-      # call.
-      #
-      # Upon success, {vboxmanage} returns the stdout output from the command.
-      #
-      # @return [String] The data from stdout of the command.
-      def vboxmanage(*args)
-        args.collect! { |arg| shell_escape(arg.to_s) }
-        result = execute("#{@@vboxmanage} -q #{args.join(" ")}")
-        raise Exceptions::CommandFailedException.new(result) if !Command.success?
-        result
-      end
-
-      # Runs a command and returns a boolean result showing
-      # if the command ran successfully or not based on the
-      # exit code.
-      def test(command)
-        execute(command)
-        success?
-      end
-
-      # Runs a command and returns the STDOUT result. The reason this is
-      # a method at the moment is because in the future we may want to
-      # change the way commands are run (replace the backticks), plus it
-      # makes testing easier.
-      def execute(command)
-        `#{command}`
-      end
-
-      # Shell escapes a string. This is almost a direct copy/paste from
-      # the ruby mailing list. I'm not sure how well it works but so far
-      # it hasn't failed!
-      def shell_escape(str)
-        if Platform.windows?
-          # Special case for windows. This is probably not 100% bullet proof
-          # but it gets the job done until we find trouble
-          str = "\"#{str}\"" if str =~ /\s/
-          return str
-        end
-
-        str.to_s.gsub(/(?=[^a-zA-Z0-9_.\/\-\x7F-\xFF\n])/n, '\\').
-                 gsub(/\n/, "'\n'").
-                 sub(/^$/, "''")
-      end
-    end
-  end
-end

data/lib/virtualbox/image.rb

@@ -1,137 +0,0 @@
-require 'virtualbox/ext/subclass_listing'
-
-module VirtualBox
-  # An abstract class which encapsulates the shared behaviour of
-  # images such as {HardDrive} and {DVD}.
-  #
-  # ## Attributes
-  #
-  # All images expose the following attributes. If you don't know how to read
-  # this than read {Attributable}.
-  #
-  #     attribute :uuid, :readonly => true
-  #     attribute :location
-  #     attribute :accessible, :readonly => true
-  #
-  # @abstract
-  class Image < AbstractModel
-    include SubclassListing
-
-    attribute :uuid, :readonly => true
-    attribute :location
-    attribute :accessible, :readonly => true, :lazy => true
-
-    class <<self
-      # Parses the raw output of virtualbox into image objects. Used by
-      # subclasses to parse the output of their respective listing functions.
-      #
-      # **This method typically won't be used except internally.**
-      #
-      # @return [Array<Image>]
-      def parse_raw(raw)
-        parse_blocks(raw).collect { |v| new(v) }
-      end
-
-      # Parses the blocks of the output from virtualbox. VirtualBox outputs
-      # image listing in "blocks" which are then parsed down to their attributes.
-      #
-      # **This method typically won't be used except internally.**
-      #
-      # @return [Array<Hash>]
-      def parse_blocks(raw)
-        raw.split(/\n\n/).collect { |v| parse_block(v.chomp) }.compact
-      end
-
-      # Parses a single block from VirtualBox output.
-      #
-      # **This method typically won't be used except internally.**
-      #
-      # @return [Hash]
-      def parse_block(block)
-        return nil unless block =~ /^UUID:/i
-        hd = {}
-
-        # Parses each line which should be in the format:
-        # KEY: VALUE
-        block.split("\n").each do |line|
-          next unless line =~ /^(.+?):\s+(.+?)$/
-          hd[$1.downcase.to_sym] = $2.to_s
-        end
-
-        # If we don't have a location but have a path, use that, as they
-        # are equivalent but not consistent.
-        hd[:location] = hd[:path] if hd.has_key?(:path)
-
-        hd
-      end
-
-      # Searches the subclasses which implement all method, searching for
-      # a matching UUID and returning that as the relationship.
-      #
-      # **This method typically won't be used except internally.**
-      #
-      # @return [Array<Image>]
-      def populate_relationship(caller, data)
-        return DVD.empty_drive if data[:uuid].nil?
-
-        subclasses.each do |subclass|
-          next unless subclass.respond_to?(:all)
-
-          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
-
-    # **This should never be called directly on {Image}.** Instead, initialize
-    # one of the subclasses.
-    def initialize(info=nil)
-      super()
-
-      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
-
-    # Returns the basename of the images location (the file name +extension)
-    #
-    # @return [String]
-    def filename
-      File.basename(location.to_s)
-    end
-  end
-end