Module: VirtualBox::AbstractModel::Attributable

Module which can be included into any other class which allows that class to have attributes using the "attribute" class method. This creates the reader/writer for the attribute but also provides other useful options such as readonly attributes, default values, and more.

Make sure to also see the ClassMethods.

Defining a Basic Attribute

attribute :name

The example above would put the "name" attribute on the class. This would give the class the following abilities

instance.name = "Harry!"
puts instance.name # => "Harry!"

Basic attributes alone are not different than ruby's built-in attr_* methods.

Defining a Readonly Attribute

attribute :age, :readonly => true

The example above allows age to be read, but not written to via the age= method. The attribute is still able to written using #write_attribute but this is generally only for inter-class use, and not for users of it.

Defining Default Values

attribute :format, :default => "VDI"

The example above applies a default value to format. So if no value is ever given to it, format would return VDI.

Populating Multiple Attributes

Attributes can be mass populated using #populate_attributes. Below is an example of the use.

class Person
  include Attributable

  attribute :name
  attribute :age, :readonly => true

  def initialize
    populate_attributes({
      :name => "Steven",
      :age => 27
    })
  end
end

Note: Populating attributes is not the same as mass-updating attributes. #populate_attributes is meant to do initial population only. There is currently no method for mass assignment for updating.

Custom Populate Keys

Sometimes the attribute names don't match the keys of the hash that will be used to populate it. For this purpose, you can define a custom populate_key. Example:

attribute :path, :populate_key => :location

def initialize
  populate_attributes(:location => "Home")
  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