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 collapse

@@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.

Parameters:

  • data (Hash) —

    Initial attributes to populate.



87
88
89
90
 
# File 'lib/virtualbox/extra_data.rb', line 87

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

#interface ⇒ Object (readonly)

Returns the value of attribute interface.



41
42
43
 
# File 'lib/virtualbox/extra_data.rb', line 41

def interface
  @interface
end

#parent ⇒ Object

Returns the value of attribute parent.



40
41
42
 
# File 'lib/virtualbox/extra_data.rb', line 40

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.

Parameters:

  • reload (Boolean) (defaults to: false) —

    If true, will reload new global data.

Returns:



51
52
53
54
55
56
57
 
# File 'lib/virtualbox/extra_data.rb', line 51

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.**

Returns:



64
65
66
67
68
69
70
71
72
73
 
# File 'lib/virtualbox/extra_data.rb', line 64

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.**



79
80
81
 
# File 'lib/virtualbox/extra_data.rb', line 79

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.



94
95
96
97
 
# File 'lib/virtualbox/extra_data.rb', line 94

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

#delete(key) ⇒ Object

Deletes the specified extra data.

Parameters:

  • key (String) —

    The extra data key to delete



125
126
127
128
 
# File 'lib/virtualbox/extra_data.rb', line 125

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

#hash_delete ⇒ Object

Alias away the old delete method so its still accessible somehow



120
 
# File 'lib/virtualbox/extra_data.rb', line 120

alias :hash_delete :delete

#save ⇒ Boolean

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.

Parameters:

  • raise_errors (Boolean) —

    If true, Exceptions::CommandFailedException will be raised if the command failed.

Returns:

  • (Boolean) —

    True if command was successful, false otherwise.



106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/virtualbox/extra_data.rb', line 106

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