virtualbox 0.1.0

data/lib/virtualbox/abstract_model/dirty.rb

@@ -0,0 +1,164 @@
+module VirtualBox
+  class AbstractModel
+    # Tracks "dirtiness" of values for a class. Its not tied to AbstractModel
+    # in any way other than the namespace. 
+    #
+    # # Checking if a Value was Changed
+    #
+    # Dynamic methods allow functionality for checking if values changed:
+    #
+    #     obj.foo_changed?
+    #
+    # # Previous Value
+    #
+    # Can also view the previous value of an attribute:
+    # 
+    #     obj.foo # => "foo" initially
+    #     obj.foo = "bar"
+    #     obj.foo_was # => "foo"
+    #
+    # # Previous and Current Value
+    #
+    # Using the `_change` dynamic method, can view the changes of a field.
+    #
+    #     obj.foo # => "foo" initially
+    #     obj.foo = "bar"
+    #     obj.foo_change # => ["foo", "bar"]
+    #
+    # # All Changes
+    #
+    # Can also view all changes for a class with the `changes` method.
+    #
+    #     obj.foo # => "foo" initially
+    #     obj.bar # => "bar" initially
+    #     obj.foo = "far"
+    #     obj.bar = "baz"
+    #     obj.changes # => { :foo => ["foo", "far"], :bar => ["bar", "baz"]}
+    #
+    # # Setting Dirty
+    #
+    # Dirtiness tracking only occurs for values which the implementor
+    # explicitly sets as dirty. This is done with the {#set_dirty!}
+    # method. Example implementation below:
+    #
+    #     class Person
+    #       include VirtualBox::AbstractModel::Dirty
+    #
+    #       attr_reader :name
+    #
+    #       def name=(value)
+    #         set_dirty!(:name, @name, value)
+    #         @name = value
+    #       end
+    #     end
+    #
+    # The above example has all the changes necessary to track changes
+    # on an attribute.
+    #
+    # # Ignoring Dirtiness Tracking
+    # 
+    # Sometimes, for features such as mass assignment, dirtiness tracking
+    # should be disabled. This can be done with the `ignore_dirty` method.
+    #
+    #     ignore_dirty do |obj|
+    #       obj.name = "Foo"
+    #     end
+    #     
+    #     obj.changed? # => false
+    #
+    # # Clearing Dirty State
+    #
+    # Sometimes, such as after saving a model, dirty states should be cleared.
+    # This can be done with the `clear_dirty!` method.
+    #
+    #     obj.clear_dirty!(:name)
+    #     obj.name_changed? # => false
+    #
+    module Dirty
+      # Manages dirty state for an attribute. This method will handle
+      # setting the dirty state of an attribute (or even clearing it
+      # if the old value is reset). Any implementors of this mixin should
+      # call this for any fields they want tracked.
+      #
+      # @param [Symbol] name Name of field
+      # @param [Object] current Current value (not necessarilly the
+      #   original value, but the **current** value)
+      # @param [Object] value The new value being set
+      def set_dirty!(name, current, value)
+        if current != value
+          # If its the first time this attribute has changed, store the
+          # original value in the first field
+          changes[name] ||= [current, nil]
+
+          # Then store the changed value
+          changes[name][1] = value
+
+          # If the value changed back to the original value, remove from the
+          # dirty hash
+          if changes[name][0] == changes[name][1]
+            changes.delete(name)
+          end
+        end
+      end
+      
+      # Clears dirty state for a field.
+      #
+      # @param [Symbol] key The field to clear dirty state.
+      def clear_dirty!(key)
+        changes.delete(key)
+      end
+
+      # Ignores any dirty changes during the duration of the block. 
+      # Guarantees the dirty state will be the same before and after 
+      # the method call, but not within the block itself.
+      def ignore_dirty(&block)
+        current_changes = @changed_attributes.dup rescue nil
+        yield self
+        @changed_attributes = current_changes
+      end
+
+      # Returns boolean denoting if field changed or not. If no attribute
+      # is specified, returns true of false showing whether the model
+      # changed at all.
+      #
+      # @param [Symbol] attribute The attribute to check, or if nil,
+      #   all fields checked.
+      def changed?(attribute = nil)
+        if attribute.nil?
+          !changes.empty?
+        else
+          changes.has_key?(attribute)
+        end
+      end
+
+      # Returns hash of changes. Keys are fields, values are an
+      # array of the original value and the current value.
+      #
+      # @return [Hash]
+      def changes
+        @changed_attributes ||= {}
+      end
+      
+      # Method missing is used to implement the "magic" methods of
+      # `field_changed`, `field_change`, and `field_was`.
+      def method_missing(meth, *args)
+        meth_string = meth.to_s
+        
+        if meth_string =~ /^(.+?)_changed\?$/ 
+          changed?($1.to_sym)
+        elsif meth_string =~ /^(.+?)_change$/
+          changes[$1.to_sym]
+        elsif meth_string =~ /^(.+?)_was$/
+          change = changes[$1.to_sym]
+          if change.nil?
+            nil
+          else
+            change[0]
+          end
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/virtualbox/abstract_model/relatable.rb

@@ -0,0 +1,163 @@
+module VirtualBox
+  class AbstractModel
+    # Provides simple relationship features to any class. These relationships
+    # can be anything, since this module makes no assumptions and doesn't
+    # differentiate between "has many" or "belongs to" or any of that. 
+    #
+    # The way it works is simple:
+    # 
+    # 1. Relationships are defined with a relationship name and a
+    #    class of the relationship objects.
+    # 2. When {#populate_relationships} is called, `populate_relationship` is
+    #    called on each relationship class (example: {StorageController.populate_relationship}).
+    #    This is expected to return the relationship, which can be any object.
+    # 3. When {#save_relationships} is called, `save_relationship` is
+    #     called on each relationship class, which manages saving its own
+    #     relationship.
+    # 4. When {#destroy_relationships} is called, `destroy_relationship` is
+    #     called on each relationship class, which manages destroying
+    #     its own relationship.
+    #
+    # Be sure to read {ClassMethods} for complete documentation of methods.
+    #
+    # # Defining Relationships
+    #
+    # Every relationship has two mandatory parameters: the name and the class.
+    #
+    #     relationship :bacons, Bacon
+    #
+    # In this case, there is a relationship `bacons` which refers to the `Bacon`
+    # class.
+    #
+    # # Accessing Relationships
+    #
+    # Relatable offers up dynamically generated accessors for every relationship
+    # which simply returns the relationship data.
+    #
+    #     relationship :bacons, Bacon
+    #
+    #     # Accessing through an instance "instance"
+    #     instance.bacons # => whatever Bacon.populate_relationship created
+    #
+    # # Dependent Relationships
+    #
+    # By setting `:dependent => :destroy` on relationships, {AbstractModel}
+    # will automatically call {#destroy_relationships} when {AbstractModel#destroy}
+    # is called.
+    #
+    # This is not a feature built-in to Relatable but figured it should be
+    # mentioned here.
+    module Relatable
+      def self.included(base)
+        base.extend ClassMethods
+      end
+      
+      module ClassMethods
+        # Define a relationship. The name and class must be specified. This
+        # class will be used to call the `populate_relationship, 
+        # `save_relationship`, etc. methods.
+        #
+        # @param [Symbol] name Relationship name. This will also be used for
+        #   the dynamically generated accessor.
+        # @param [Class] klass Class of the relationship.
+        # @option options [Symbol] :dependent (nil) - If set to `:destroy`
+        #   {AbstractModel#destroy} will propagate through to relationships.
+        def relationship(name, klass, options = {})
+          @relationships ||= {}
+          @relationships[name] = { :klass => klass }.merge(options)
+        end
+        
+        # Returns a hash of all the relationships.
+        #
+        # @return [Hash]
+        def relationships
+          @relationships ||= {}
+        end
+        
+        # Used to propagate relationships to subclasses. This method makes sure that
+        # subclasses of a class with {Relatable} included will inherit the
+        # relationships as well, which would be the expected behaviour.
+        def inherited(subclass)
+          super rescue NoMethodError
+          
+          relationships.each do |name, options|
+            subclass.relationship(name, nil, options)
+          end
+        end
+      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
+      # following parameters:
+      #
+      # * **caller** - The class which is calling save
+      # * **data** - The data associated with the relationship
+      #
+      # In addition to those two args, any arbitrary args may be tacked on to the
+      # 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)
+        end
+      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)
+        end
+      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.
+      def destroy_relationships(*args)
+        self.class.relationships.each do |name, options|
+          destroy_relationship(name, *args)
+        end
+      end
+      
+      # Destroys only a single relationship. Any arbitrary args
+      # may be added to the end and they will be pushed through to
+      # the class's `destroy_relationship` method.
+      #
+      # @param [Symbol] name The name of the relationship
+      def destroy_relationship(name, *args)
+        options = self.class.relationships[name]
+        return unless options && options[:klass].respond_to?(:destroy_relationship)
+        options[:klass].destroy_relationship(self, relationship_data[name], *args)
+      end
+      
+      # Hash to data associated with relationships. You should instead
+      # use the accessors created by Relatable.
+      #
+      # @return [Hash]
+      def relationship_data
+        @relationship_data ||= {}
+      end
+      
+      # Returns boolean denoting if a relationship exists.
+      #
+      # @return [Boolean]
+      def has_relationship?(key)
+        self.class.relationships.has_key?(key.to_sym)
+      end
+      
+      # Method missing is used to add dynamic handlers for relationship
+      # accessors.
+      def method_missing(meth, *args)
+        meth_string = meth.to_s
+
+        if has_relationship?(meth)
+          relationship_data[meth.to_sym]
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/virtualbox/attached_device.rb

@@ -0,0 +1,104 @@
+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.
+  #
+  # **Currently, attached devices can not be created from scratch. The only way
+  # to access them is through relationships with other models such as
+  # {StorageController}.**
+  #
+  # # 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
+    attribute :medium
+    attribute :port
+    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 = []
+        
+        counter = 0
+        loop do
+          break unless data["#{caller.name}-#{counter}-0".downcase.to_sym]
+          nic = new(counter, caller, data)
+          relation.push(nic)
+          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
+    end
+    
+    # Since attached devices can not be created from scratch yet, this
+    # method should never be called. Instead access attached devices
+    # through relationships from other models such as {StorageController}.
+    def initialize(index, caller, data)
+      super()
+      
+      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]
+      })
+    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.
+    def destroy(options={})
+      # parent = storagecontroller
+      # parent.parent = vm
+      Command.vboxmanage("storageattach #{Command.shell_escape(parent.parent.name)} --storagectl #{Command.shell_escape(parent.name)} --port #{port} --device 0 --medium none")      
+      image.destroy if options[:destroy_image] && image
+    end
+  end
+end

data/lib/virtualbox/command.rb

@@ -0,0 +1,54 @@
+module VirtualBox
+  # 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
+      # Sets the path to VBoxManage, which is required for this gem to
+      # work.
+      def vboxmanage=(path)
+        @@vboxmanage = path
+      end
+      
+      # Runs a VBoxManage command and returns the output.
+      def vboxmanage(command)
+        execute("#{@@vboxmanage} #{command}")
+      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)
+        $?.to_i == 0
+      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)
+        str.to_s.gsub(/(?=[^a-zA-Z0-9_.\/\-\x7F-\xFF\n])/n, '\\').
+                 gsub(/\n/, "'\n'").
+                 sub(/^$/, "''")
+      end
+    end
+  end
+end