Class: VirtualBox::Global

Inherits:
AbstractModel show all
Defined in:
lib/virtualbox/global.rb

Overview

Represents the VirtualBox main configuration file (VirtualBox.xml) which VirtualBox uses to keep track of all known virtual machines and images. This "global" configuration has many relationships which allow the user to retrieve a list of all VMs, media, global extra data, etc. Indeed, even methods like VM.all are implemented using this class.

Setting the Path to VirtualBox.xml

This is extremely important.

Much of the virtualbox gem requires a proper path to the global XML configuration file for VirtualBox. This path is system and installation dependent. Global does its best to guess the path by trying the default paths based on the platform ruby is running on, but this is hardly foolproof. If you receive an Exceptions::ConfigurationException at some point while running virtualbox, you should use Global.vboxconfig= to set the path. An example is below:

# Most installations won't need to do this, since the gem "guesses"
# the path based on OS, but if you need to set vboxconfig path
# explicitly:
VirtualBox::Global.vboxconfig = "~/.MyCustom/VirtualBox.xml"

Getting Global Data

To retrieve the global data, use Global.global. This value is cached between calls, so subsequent calls will not go through the entire parsing process. To force a reload, set the reload parameter to true. Besides setting the parameter explicitly, some actions will implicitly force the global data to reload on the next call, such as saving a VM or destroying an image, for example.

# Retrieve global data for the first time. This will parse all the
# data.
global_object = VirtualBox::Global.global

# Subsequent calls are near-instant:
VirtualBox::Global.global

# Or we can choose to reload the data...
reloaded_object = VirtualBox::Global.global(true)

Relationships

While a global object doesn't have attributes, it does have many relationships. The relationships are listed below. If you don't understand this, read Relatable.

relationship :vms, VM, :lazy => true
relationship :media, Media
relationship :extra_data, ExtraData

Constant Summary

@@vboxconfig = The path to the global VirtualBox XML configuration file. 
if RUBY_PLATFORM.downcase.include?("darwin")
@@global_data = 
nil

Class Method Summary

Instance Method Summary

Methods inherited from AbstractModel

#destroy, #errors, #existing_record!, #inspect, #lazy_attribute?, #lazy_relationship?, #new_record!, #new_record?, #populate_attributes, #populate_relationship, #populate_relationships, #reload!, reload!, reload?, reloaded!, #save, #save_attribute, #set_relationship, #validate, #write_attribute

Methods included from AbstractModel::Attributable

#attributes, #has_attribute?, included, #lazy_attribute?, #loaded_attribute?, #populate_attributes, #read_attribute, #readonly_attribute?, #write_attribute

Methods included from AbstractModel::Dirty

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

Methods included from AbstractModel::Relatable

#destroy_relationship, #destroy_relationships, #has_relationship?, included, #lazy_relationship?, #loaded_relationship?, #populate_relationship, #populate_relationships, #read_relationship, #relationship_data, #save_relationship, #save_relationships, #set_relationship

Methods included from AbstractModel::Validatable

#add_error, #clear_errors, #errors, #valid?, #validate, #validates_presence_of

Constructor Details

- (Global) initialize(document)

A new instance of Global



117
118
119
120
 
# File 'lib/virtualbox/global.rb', line 117

def initialize(document)
  @document = document
  populate_attributes(@document)
end

Dynamic Method Handling

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

Class Method Details

+ (Nokogiri::XML::Document) config

Returns the XML document of the configuration. This will raise an Exceptions::ConfigurationException if the vboxconfig file doesn't exist.

Returns:

  • (Nokogiri::XML::Document)

Raises:



104
105
106
107
 
# File 'lib/virtualbox/global.rb', line 104

def config
  raise Exceptions::ConfigurationException.new("The path to the global VirtualBox config must be set. See Global.vboxconfig=") unless File.exist?(File.expand_path(@@vboxconfig))
  Command.parse_xml(File.expand_path(@@vboxconfig))
end

+ (String) expand_path(path)

Expands path relative to the configuration file.

Returns:

  • (String) 


112
113
114
 
# File 'lib/virtualbox/global.rb', line 112

def expand_path(path)
  File.expand_path(path, File.dirname(@@vboxconfig))
end

+ (Global) global(reload = false)

Retrieves the global data. The return value of this call is cached, and can be reloaded by setting the reload parameter to true. Besides explicitly setting the parameter, some actions within the library force global to reload itself on the next call, such as saving a VM, or destroying an image.

Parameters:

  • (Boolean) reload (defaults to: false) — True if you want to force a reload of the data.

Returns:



82
83
84
85
86
87
88
89
 
# File 'lib/virtualbox/global.rb', line 82

def global(reload = false)
  if !@@global_data || reload || reload?
    @@global_data = new(config)
    reloaded!
  end

  @@global_data
end

+ (Object) vboxconfig=(value)

Sets the path to the VirtualBox.xml file. This file should already exist. VirtualBox itself manages this file, not this library.

Parameters:

  • (String) Full — path to the VirtualBox.xml file 


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

def vboxconfig=(value)
  @@vboxconfig = value
end

Instance Method Details

- (Object) load_relationship(name) 



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

def load_relationship(name)
  populate_relationship(:vms, @document)
end