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.



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

#interface ⇒ Object (readonly)

Returns the value of attribute interface.



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

def interface
  @interface
end

#parent ⇒ Object

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.

Parameters:

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

    If true, will reload new global data.

Returns:



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

Returns:



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

Deletes the specified extra data.

Parameters:

  • key (String) —

    The extra data key to delete



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

#hash_delete ⇒ Object

Alias away the old delete method so its still accessible somehow



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

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.



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