Class: VirtualBox::ExtraData

Inherits:
Hash
  • Object
show all
Includes:
AbstractModel::Dirty
Defined in:
lib/virtualbox/extra_data.rb

Overview

Represents "extra data" which can be set on a specific virtual machine or on VirtualBox as a whole. 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!

# Extra Data on a Virtual Machine

Setting extra data on a virtual machine is easy. All VM objects have a `extra_data` relationship which is just a simple ruby hash, so you can treat it like one! Once the data is set, simply saving the VM will save the extra data. An example below:

vm = VirtualBox::VM.find("FooVM")
vm.extra_data["ruby-accessed"]  = "yes, yes it was"
vm.save

Now, let's say you open up the VM again some other time:

vm = VirtualBox::VM.find("FooVM")
puts vm.extra_data["ruby-accessed"]

It acts just like a hash!

# Global Extra Data

Extra data doesn't need to be tied to a specific virtual machine. It can also exist globally. Setting global extra-data is just as easy:

VirtualBox::ExtraData.global["some-key"] = "some value"
VirtualBox::ExtraData.global.save

Constant Summary

@@global_data =
nil

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from AbstractModel::Dirty

#changed?, #changes, #clear_dirty!, #ignore_dirty, #method_missing, #set_dirty!

Constructor Details

#initialize(parent, interface) ⇒ ExtraData

Initializes an extra data object.



84
85
86
87
# File 'lib/virtualbox/extra_data.rb', line 84

def initialize(parent, interface)
  @parent = parent
  @interface = interface
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class VirtualBox::AbstractModel::Dirty

Instance Attribute Details

#interfaceObject (readonly)

Returns the value of attribute interface



38
39
40
# File 'lib/virtualbox/extra_data.rb', line 38

def interface
  @interface
end

#parentObject

Returns the value of attribute parent



37
38
39
# File 'lib/virtualbox/extra_data.rb', line 37

def parent
  @parent
end

Class Method Details

.global(reload = false) ⇒ Array<ExtraData>

Gets the global extra data. This will "cache" the data for future use unless you set the `reload` paramter to true.



48
49
50
51
52
53
54
# File 'lib/virtualbox/extra_data.rb', line 48

def global(reload=false)
  if !@@global_data || reload
    @@global_data = Global.global.extra_data
  end

  @@global_data
end

.populate_relationship(caller, interface) ⇒ Array<ExtraData>

Populates a relationship with another model.

**This method typically won't be used except internally.**



61
62
63
64
65
66
67
68
69
70
# File 'lib/virtualbox/extra_data.rb', line 61

def populate_relationship(caller, interface)
  data = new(caller, interface)

  interface.get_extra_data_keys.each do |key|
    data[key] = interface.get_extra_data(key)
  end

  data.clear_dirty!
  data
end

.save_relationship(caller, data) ⇒ Object

Saves the relationship. This simply calls #save on every member of the relationship.

**This method typically won't be used except internally.**



76
77
78
# File 'lib/virtualbox/extra_data.rb', line 76

def save_relationship(caller, data)
  data.save
end

Instance Method Details

#[]=(key, value) ⇒ Object

Set an extradata key-value pair. Overrides ruby hash implementation to set dirty state. Otherwise that, behaves the same way.



91
92
93
94
# File 'lib/virtualbox/extra_data.rb', line 91

def []=(key,value)
  set_dirty!(key, self[key], value)
  super
end

#delete(key) ⇒ Object Also known as: hash_delete

Deletes the specified extra data.



122
123
124
125
# File 'lib/virtualbox/extra_data.rb', line 122

def delete(key)
  interface.set_extra_data(key.to_s, nil)
  hash_delete(key.to_s)
end

#saveBoolean

Saves extra data. This method does the same thing for both new and existing extra data, since virtualbox will overwrite old data or create it if it doesn't exist.



103
104
105
106
107
108
109
110
111
112
113
114
# File 'lib/virtualbox/extra_data.rb', line 103

def save
  changes.each do |key, value|
    interface.set_extra_data(key.to_s, value[1].to_s)

    clear_dirty!(key)

    if value[1].nil?
      # Remove the key from the hash altogether
      hash_delete(key.to_s)
    end
  end
end