module VirtualBox
  # 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 {Relatable}.
  #
  #     relationship :vms, VM
  #     relationship :media, Media
  #     relationship :extra_data, ExtraData
  #     relationship :system_properties, :SystemProperties, :lazy => true
  #
  class Global < AbstractModel
    attribute :lib, :readonly => true

    relationship :vms, :VM, :lazy => true
    relationship :media, :Media, :lazy => true
    relationship :extra_data, :ExtraData, :lazy => true
    relationship :system_properties, :SystemProperties, :lazy => true
    relationship :host, :Host, :lazy => true
    relationship :dhcp_servers, :DHCPServer, :lazy => true

    @@global_data = nil

    class << self
      # 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.
      #
      # @param [Boolean] reload True if you want to force a reload of the data.
      # @return [Global]
      def global(reload=false)
        if !@@global_data || reload
          @@global_data = new(Lib.lib)
        end

        @@global_data
      end

      # Resets the global data singleton. This is used for testing purposes.
      def reset!
        @@global_data = nil
      end
    end

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

      # Required to load lazy relationships
      existing_record!
    end

    def create_machine(name, type)
      imachine = lib.virtualbox.create_machine(name, type)
      lib.virtualbox.register_machine(imachine)
      VirtualBox::VM.find(imachine.id)
    end

    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
  end
end