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.

# 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 AbstractModel::Relatable.

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

Constant Summary

@@global_data =
nil

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from AbstractModel

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

Methods included from AbstractModel::Validatable

#__validates_extract_options, #add_error, #clear_errors, #errors, #errors_on, #full_error_messages, #valid?, #validate, #validates_format_of, #validates_inclusion_of, #validates_numericality_of, #validates_presence_of

Methods included from AbstractModel::Relatable

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

Methods included from AbstractModel::VersionMatcher

#assert_version_match, #split_version, #version_match?

Methods included from AbstractModel::Dirty

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

Methods included from AbstractModel::InterfaceAttributes

#load_interface_attribute, #load_interface_attributes, #save_interface_attribute, #save_interface_attributes, #spec_to_proc

Methods included from AbstractModel::Attributable

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

Methods included from Logger

included, #logger, #logger_output=

Constructor Details

- (Global) initialize(lib)

Returns a new instance of Global



73
74
75
76
77
78
# File 'lib/virtualbox/global.rb', line 73

def initialize(lib)
  write_attribute(:lib, lib)

  # Required to load lazy relationships
  existing_record!
end

Dynamic Method Handling

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

Class Method Details

+ (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:

  • reload (Boolean) (defaults to: false)

    True if you want to force a reload of the data.

Returns:



59
60
61
62
63
64
65
# File 'lib/virtualbox/global.rb', line 59

def global(reload=false)
  if !@@global_data || reload
    @@global_data = new(Lib.lib)
  end

  @@global_data
end

+ (Object) reset!

Resets the global data singleton. This is used for testing purposes.



68
69
70
# File 'lib/virtualbox/global.rb', line 68

def reset!
  @@global_data = nil
end

Instance Method Details

- (Object) load_relationship(name)



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
# File 'lib/virtualbox/global.rb', line 80

def load_relationship(name)
  # "Lazy loaded" associations table. These associate the relationship
  # with the data it needs to load. The data is wrapped in lambdas so
  # that the evaluation doesn't occur unless necessary.
  relationships = {
    :vms => lambda { lib.virtualbox.machines },
    :media => lambda { lib },
    :extra_data => lambda { lib.virtualbox },
    :system_properties => lambda { lib.virtualbox.system_properties },
    :host => lambda { lib.virtualbox.host },
    :dhcp_servers => lambda { lib.virtualbox.dhcp_servers }
  }

  populate_relationship(name, relationships[name].call)
end