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

Class Method Summary

Instance Method Summary

Methods included from AbstractModel::Dirty

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

Constructor Details

- (ExtraData) initialize(parent = nil)

Initializes an extra data object.

Parameters:

  • (Hash) data — Initial attributes to populate. 


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

def initialize(parent=nil)
  @parent = parent || "global"
end

Dynamic Method Handling

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

Instance Attribute Details

- (Object) parent

Returns the value of attribute parent



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

def parent
  @parent
end

Class Method Details

+ (Array<ExtraData>) global(reload = false)

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

Parameters:

  • (Boolean) reload (defaults to: false) — If true, will reload new global data.

Returns:



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

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

  @@global_data
end

+ (Array<ExtraData>) populate_relationship(caller, doc)

Populates a relationship with another model.

This method typically won't be used except internally.

Returns:



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

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

  doc.css("ExtraData ExtraDataItem").each do |extradata|
    data[extradata["name"].to_s] = extradata["value"].to_s
  end

  data.clear_dirty!
  data
end

+ (Object) save_relationship(caller, data)

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

This method typically won't be used except internally.



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

def save_relationship(caller, data)
  data.save
end

Instance Method Details

- (Object) []=(key, value)

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



89
90
91
92
 
# File 'lib/virtualbox/extra_data.rb', line 89

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

- (Boolean) delete(key, raise_errors = false)

Deletes the extra data.

Parameters:

Returns:

  • (Boolean) — True if command was successful, false otherwise. 


131
132
133
134
135
136
137
138
 
# File 'lib/virtualbox/extra_data.rb', line 131

def delete(key, raise_errors=false)
  Command.vboxmanage("setextradata", parent_name, key)
  super(key)
  true
rescue Exceptions::CommandFailedException
  raise if raise_errors
  false
end

- (String) parent_name

Special accessor for parent name attribute. This returns either the parent name if its a VM object, otherwise just returns the default.

Returns:

  • (String) 


99
100
101
102
103
104
105
 
# File 'lib/virtualbox/extra_data.rb', line 99

def parent_name
  if parent.is_a?(VM)
    parent.name
  else
    parent
  end
end

- (Boolean) save(raise_errors = false)

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:

Returns:

  • (Boolean) — True if command was successful, false otherwise. 


114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/virtualbox/extra_data.rb', line 114

def save(raise_errors=false)
  changes.each do |key, value|
    Command.vboxmanage("setextradata", parent_name, key, value[1])
    clear_dirty!(key)
  end

  true
rescue Exceptions::CommandFailedException
  raise if raise_errors
  false
end