vcloud-core 0.13.0 → 0.14.0

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.14.0 (2014-11-10)
+
+API changes:
+
+  - Automatic pagination of `Vcloud::QueryRunner` results can now be
+    overridden with `page` and `pageSize` options.
+
+Documentation:
+
+  - Documented all the public methods in vcloud-core to comply with semver.org recommendations.
+
 ## 0.13.0 (2014-10-13)
 
 Features:

data/lib/vcloud/core/api_interface.rb

@@ -5,30 +5,59 @@ module Vcloud
     # if functionality does not exist in Core
     class ApiInterface
 
+      # Private interface to Fog service layer to allow direct access to Fog
+      # for functionality not exposed elsewhere in Vcloud::Core.
+      #
+      # @api private
       def fog_service_interface
         @fog_service_interface ||= Vcloud::Core::Fog::ServiceInterface.new
       end
 
+      # Private interface to Fog model layer to allow direct access to Fog for
+      # functionality not exposed elsewhere in Vcloud::Core.
+      #
+      # @api private
       def fog_model_interface
         @fog_model_interface ||= Vcloud::Core::Fog::ModelInterface.new
       end
 
+      # Get a vApp by name and vdc_name
+      #
+      # @param name [String] Name of the vApp
+      # @param vdc_name [String] Name of the vDC
+      # @return [String] Response body describing the vApp
       def get_vapp_by_name_and_vdc_name(name, vdc_name)
         fog_service_interface.get_vapp_by_name_and_vdc_name(name, vdc_name)
       end
 
+      # Get a vApp by id
+      #
+      # @param  id [String] ID of the vApp to get
+      # @return [String] Response body describing the vApp
       def get_vapp(id)
         fog_service_interface.get_vapp(id)
       end
 
+      # Delete a vApp by id
+      #
+      # @param id [String] ID of the vApp to delete
+      # @return [Boolean] return true or throw error
       def delete_vapp(id)
         fog_service_interface.delete_vapp(id)
       end
 
+      # Delete a network by id
+      #
+      # @param id [String] ID of the network to delete
+      # @return [Boolean] return true or throw error
       def delete_network(id)
         fog_service_interface.delete_network(id)
       end
 
+      # Returns a Fog::Compute::VcloudDirector::Organization instance representing
+      # the current organization
+      #
+      # @return [Fog::Compute::VcloudDirector::Organization]
       def current_organization
         fog_model_interface.current_organization
       end

data/lib/vcloud/core/compute_metadata.rb

@@ -2,6 +2,10 @@ module Vcloud
   module Core
     module ComputeMetadata
 
+        # Returns the metadata for a compute resource
+        #
+        # @param id [String] The ID of the vApp or VM to retrieve metadata for
+        # @return [Hash] Metadata keys/values
         def get_metadata id
           vcloud_compute_metadata =  Vcloud::Core::Fog::ServiceInterface.new.get_vapp_metadata(id)
           MetadataHelper.extract_metadata(vcloud_compute_metadata[:MetadataEntry])

data/lib/vcloud/core/config_loader.rb

@@ -4,6 +4,17 @@ module Vcloud
   module Core
     class ConfigLoader
 
+      # Loads the configuration from +config_file+, optionally rendering
+      # +config_file+ as a Mustache template using vars in +vars_file+ and
+      # optionally validating config against +schema+ supplied.
+      #
+      # @param config_file [String]      Location of the YAML config file
+      # @param schema      [String, nil] Location of the validation schema
+      #                                  if nil, no validation takes place.
+      # @param vars_file   [String, nil] Location of the vars_file (YAML),
+      #                                  if nil, config_file is not rendered
+      #                                  by Mustache
+      # @return [Hash]
       def load_config(config_file, schema = nil, vars_file = nil)
         if vars_file
           rendered_config = Mustache.render(

data/lib/vcloud/core/edge_gateway.rb

@@ -4,6 +4,12 @@ module Vcloud
 
       attr_reader :id
 
+      # Initialize a new EdgeGateway and check that the provided ID
+      # is in the correct format (lowercase string containing
+      # hexadecimal characters or hyphens)
+      #
+      # @param id [String] The ID of gateway
+      # @return [Vcloud::Core::EdgeGateway] an instance of an EdgeGateway
       def initialize(id)
         unless id =~ /^[-0-9a-f]+$/
           raise "EdgeGateway id : #{id} is not in correct format"
@@ -11,6 +17,10 @@ module Vcloud
         @id = id
       end
 
+      # Find a list of EdgeGateway IDs that match a name
+      #
+      # @param name [String] The name of the EdgeGateway
+      # @return [Array] An array of IDs found.
       def self.get_ids_by_name(name)
         q = Vcloud::Core::QueryRunner.new
         query_results = q.run('edgeGateway', :filter => "name==#{name}")
@@ -20,11 +30,20 @@ module Vcloud
         end
       end
 
+
+      # Update configuration for EdgeGateway
+      #
+      # @param config [Hash] A configuration for EdgeGateway
       def update_configuration(config)
         fsi = Vcloud::Core::Fog::ServiceInterface.new
         fsi.post_configure_edge_gateway_services(id, config)
       end
 
+
+      # Return the Vcloud::Core::EdgeGatewayInterface of EdgeGateway which matches an ID
+      #
+      # @param id [String] The id of the EdgeGatewayInterface
+      # @return [Vcloud::Core::EdgeGatewayInterface] the EdgeGatewayInterface instance
       def vcloud_gateway_interface_by_id gateway_interface_id
         gateway_interfaces = vcloud_attributes[:Configuration][:GatewayInterfaces][:GatewayInterface]
         unless gateway_interfaces.empty?
@@ -34,6 +53,11 @@ module Vcloud
         end
       end
 
+      # Return the EdgeGateway instance that is the first match for the
+      # supplied name.
+      #
+      # @param name [String] The name of the EdgeGateway
+      # @return [Vcloud::Core::EdgeGateway] the EdgeGateway instance
       def self.get_by_name(name)
         ids = self.get_ids_by_name(name)
         raise "edgeGateway #{name} not found" if ids.size == 0
@@ -41,19 +65,33 @@ module Vcloud
         return self.new(ids.first)
       end
 
+      # Get the vCloud attributes for EdgeGateway
+      #
+      # @return [String] Excon::Response#body from vCloud for EdgeGateway
       def vcloud_attributes
         fsi = Vcloud::Core::Fog::ServiceInterface.new
         fsi.get_edge_gateway(id)
       end
 
+      # Return the +href+ of EdgeGateway
+      #
+      # @return [String] href of EdgeGateway
       def href
         vcloud_attributes[:href]
       end
 
+      # Return the +name+ of EdgeGateway
+      #
+      # @return [String] name of EdgeGateway
       def name
         vcloud_attributes[:name]
       end
 
+      # For each GatewayInterfaces item in the configuration, create an
+      # EdgeGatewayInterface object to allow decisions based on the connected
+      # networks to be taken without inspecting the API details.
+      #
+      # @return [Array] An array of Vcloud::Core::EdgeGatewayInterface objects
       def interfaces
         gateway_config = vcloud_attributes[:Configuration]
         return [] unless gateway_config[:GatewayInterfaces]

data/lib/vcloud/core/edge_gateway_interface.rb

@@ -4,6 +4,10 @@ module Vcloud
 
       attr_accessor :name, :network_href, :network_name
 
+      # Return a new instance of an EdgeGatewayInterface
+      #
+      # @param gateway_interface_hash [Hash] The configuration of EdgeGatewayInterface
+      # @return [Vcloud::Core::EdgeGatewayInterface]
       def initialize(gateway_interface_hash)
         if gateway_interface_hash.nil?
           raise "EdgeGatewayInterface: gateway_interface_hash cannot be nil"
@@ -17,6 +21,9 @@ module Vcloud
         @network_name = gateway_interface_hash[:Network][:name]
       end
 
+      # Get the ID of EdgeGatewayInterface from the @network_href
+      #
+      # @return [String] The ID of EdgeGatewayInterface
       def network_id
         network_href.split('/').last
       end

data/lib/vcloud/core/fog.rb

@@ -10,10 +10,18 @@ module Vcloud
       TOKEN_ENV_VAR_NAME = 'FOG_VCLOUD_TOKEN'
       FOG_CREDS_PASS_NAME = :vcloud_director_password
 
+      # Run any checks needed against the Fog credentials
+      # currently only used to disallow plaintext passwords
+      # in .fog files.
+      #
       def self.check_credentials
         check_plaintext_pass
       end
 
+      # Attempt to load the password from the fog credentials file
+      #
+      # @return [String, nil] The password if it could be loaded, 
+      #                       else nil.
       def self.fog_credentials_pass
         begin
           pass = ::Fog.credentials[FOG_CREDS_PASS_NAME]
@@ -28,6 +36,10 @@ module Vcloud
 
       private
 
+      # Check whether a plaintext password is in the Fog config
+      # file
+      #
+      # @return [void]
       def self.check_plaintext_pass
         pass = fog_credentials_pass
         unless pass.nil? or pass.empty?

data/lib/vcloud/core/independent_disk.rb

@@ -9,6 +9,10 @@ module Vcloud
 
       attr_reader :id
 
+      # Return an object referring to a particular IndependentDisk
+      #
+      # @param id [String] The ID of the independent disk
+      # @return [Vcloud::Core::IndependentDisk]
       def initialize(id)
         unless id =~ /^[-0-9a-f]+$/
           raise "IndependentDisk id : #{id} is not in correct format"
@@ -16,6 +20,11 @@ module Vcloud
         @id = id
       end
 
+      # Return the ID of an IndependentDisk referred to by name and vDC
+      #
+      # @param name [String] The name of the disk
+      # @param vdc [String] The name of the vDC
+      # @return [Vcloud::Core::IndependentDisk] An object representing the IndependentDisk
       def self.get_by_name_and_vdc_name(name, vdc_name)
         q = Vcloud::Core::QueryRunner.new
         query_results = q.run('disk', :filter => "name==#{name};vdcName==#{vdc_name}")
@@ -33,6 +42,15 @@ module Vcloud
         return self.new(query_results.first[:href].split('/').last)
       end
 
+      # Create a named, sized IndependentDisk in a particular named vDC
+      #
+      # @param vdc [String] The name of the vDC
+      # @param name [String] The name of the IndependentDisk
+      # @param size [String, Integer] The size as an integer of bytes, or an
+      #                               integer with units
+      #                               (see convert_size_to_bytes)
+      # @return [Vcloud::Core::IndependentDisk] An object representing
+      #                                         the new disk
       def self.create(vdc, name, size)
         vdc_name = vdc.name
         begin
@@ -52,18 +70,31 @@ module Vcloud
         return self.new(body[:href].split('/').last)
       end
 
+      # Return all the vcloud attributes of IndependentDisk
+      #
+      # @return [Hash] a hash describing all the attributes of disk
       def vcloud_attributes
         Vcloud::Core::Fog::ServiceInterface.new.get_disk(id)
       end
 
+      # Return the name of IndependentDisk
+      #
+      # @return [String] the name of instance
       def name
         vcloud_attributes[:name]
       end
 
+      # Return the href of IndependentDisk
+      #
+      # @return [String] the href of instance
       def href
         vcloud_attributes[:href]
       end
 
+      # Return an array of Vcloud::Core::Vm objects which are attached to
+      # independent disk
+      #
+      # @return [Array] an array of Vcloud::Core::Vm
       def attached_vms
         body = Vcloud::Core::Fog::ServiceInterface.new.get_vms_disk_attached_to(id)
         vms = body.fetch(:VmReference)
@@ -74,6 +105,11 @@ module Vcloud
         end
       end
 
+      # Convert an integer and units suffix (e.g. 10mb) into an integer of bytes
+      # Allowed suffixes are: mb, gb, mib, gib
+      #
+      # @param size [String] the intended size of the disk (optionally with units)
+      # @return [Integer] the disk size in bytes
       def self.convert_size_to_bytes(size)
         if size.to_s =~ /^(\d+)mb$/i
           Integer($1) * (10**6)

data/lib/vcloud/core/login_cli.rb

@@ -4,12 +4,20 @@ require 'highline'
 module Vcloud
   module Core
     class LoginCli
+
+      # Create a new instance of the CLI, parsing the arguments supplied
+      #
+      # @param argv_array [Array] The Array of ARGV arguments
+      # @return [Vcloud::Core::LoginCLI]
       def initialize(argv_array)
         @usage_text = nil
 
         parse(argv_array)
       end
 
+      # Login to vCloud and print shell commands suitable for setting the vcloud_token
+      #
+      # @return [void]
       def run
         begin
           pass = read_pass

data/lib/vcloud/core/metadata_helper.rb

@@ -2,6 +2,13 @@ module Vcloud
   module Core
     module MetadataHelper
 
+      # Convert the fog metadata into a hash of standard Ruby types
+      # Fog and vCloud currently expose the types used in the API, which are
+      # unnecessary for most needs. This class maps those custom Fog types back
+      # to Ruby types if possible.
+      #
+      # @param vcloud_metadata_entries [Hash] vCloud data as returned from Fog
+      # @return [Hash] a hash of only the metadata using Ruby types
       def extract_metadata vcloud_metadata_entries
         metadata = {}
         vcloud_metadata_entries.each do |entry|

data/lib/vcloud/core/org_vdc_network.rb

@@ -4,6 +4,10 @@ module Vcloud
 
       attr_reader :id
 
+      # Return an object referring to a particular OrgVdcNetwork
+      #
+      # @param id [String] The ID of the network
+      # @return [Vcloud::Core::OrgVdcNetwork]
       def initialize(id)
         unless id =~ /^[-0-9a-f]+$/
           raise "orgVdcNetwork id : #{id} is not in correct format"
@@ -11,6 +15,10 @@ module Vcloud
         @id = id
       end
 
+      # Configure OrgVdcNetwork
+      #
+      # @param config [Hash] the configuration to apply to network
+      # @return [Vcloud::Core::OrgVdcNetwork] an object referring to network
       def self.provision(config)
         raise "Must specify a name" unless config[:name]
         raise "Must specify a vdc_name" unless config[:vdc_name]
@@ -45,18 +53,30 @@ module Vcloud
 
       end
 
+      # Return all the vcloud attributes of OrgVdcNetwork
+      #
+      # @return [Hash] a hash describing all the attributes of OrgVdcNetwork
       def vcloud_attributes
         Vcloud::Core::Fog::ServiceInterface.new.get_network_complete(id)
       end
 
+      # Return the name of OrgVdcNetwork
+      #
+      # @return [String] the name of instance
       def name
         vcloud_attributes[:name]
       end
 
+      # Return the href of OrgVdcNetwork
+      #
+      # @return [String] the href of instance
       def href
         vcloud_attributes[:href]
       end
 
+      # Delete OrgVdcNetwork
+      #
+      # @return [void]
       def delete
         Vcloud::Core::Fog::ServiceInterface.new.delete_network(id)
       end

data/lib/vcloud/core/query.rb

@@ -4,6 +4,12 @@ module Vcloud
   module Core
     class Query
 
+      # Initialize a new Vcloud::Core::Query object
+      #
+      # @param type [String] Restrict query results to this type (see QueryRunner#available_query_types)
+      # @param options [Hash] key :output_type defines the output type and defaults to tsv; csv and yaml are valid options
+      # @param query_runner [Method] default=Vcloud::Core::QueryRunner.new
+      # @return [Vcloud::Core::Query]
       def initialize(type=nil, options={}, query_runner = Vcloud::Core::QueryRunner.new)
         @type = type
         @options = options
@@ -11,6 +17,9 @@ module Vcloud
         @query_runner = query_runner
       end
 
+      # Run the query and print to standard out
+      #
+      # @return [void]
       def run()
         if @type.nil?
           output_available_query_types

data/lib/vcloud/core/query_cli.rb

@@ -3,6 +3,11 @@ require 'optparse'
 module Vcloud
   module Core
     class QueryCli
+
+      # Create a new instance of the CLI, parsing the arguments supplied
+      #
+      # @param argv_array [Array] The Array of ARGV arguments
+      # @return [Vcloud::Core::QueryCLI]
       def initialize(argv_array)
         @usage_text = nil
         @type = nil
@@ -11,6 +16,9 @@ module Vcloud
         parse(argv_array)
       end
 
+      # Run a query and print results to standard out
+      #
+      # @return [void]
       def run
         begin
           Vcloud::Core::Query.new(@type, @options).run

data/lib/vcloud/core/query_runner.rb

@@ -2,15 +2,38 @@ module Vcloud
   module Core
     class QueryRunner
 
+      # Create a new instance of the ServiceInterface as the @fsi global
       def initialize
         @fsi = Vcloud::Core::Fog::ServiceInterface.new
       end
 
+      # Run a query (optionally for a particular entity type)
+      #
+      # @param type [String] Name of type to query for - default: nil
+      #                      See integration test of this module for examples
+      # @param options [Hash] options for the query API
+      #                       see Fog::Compute::VcloudDirector::Real for more
+      #                       documentation of valid options.
+      #                       Default: {}
+      # @option options [String] :filter Filter the query e.g. "name==foo"
+      # @option options [String] :format Unsupported - do not use
+      # @option options [String] :page Override automatic pagination
+      # @option options [String] :pageSize Override automatic pagination
+      # @return [Array] List of results
       def run(type=nil, options={})
         raise ArgumentError, "Query API :format option is not supported" if options[:format]
-        get_all_results(type, options)
+
+        if options.has_key?(:page) || options.has_key?(:pageSize)
+          get_results_page(options.fetch(:page, 1), type, options) || []
+        else
+          get_all_results(type, options)
+        end
       end
 
+      # List the available entity types which can be queried
+      #   See integration test of this module for examples
+      #
+      # @return [Array] list of valid types
       def available_query_types
         query_body = @fsi.get_execute_query()
         get_entity_types_in_record_format(query_body)

data/lib/vcloud/core/vapp.rb

@@ -5,6 +5,10 @@ module Vcloud
 
       attr_reader :id
 
+      # Initialize a Vcloud::Core::Vapp
+      #
+      # @param id [String] the vApp ID
+      # @return [Vcloud::Core::Vapp]
       def initialize(id)
         unless id =~ /^#{self.class.id_prefix}-[-0-9a-f]+$/
           raise "#{self.class.id_prefix} id : #{id} is not in correct format"
@@ -12,6 +16,10 @@ module Vcloud
         @id = id
       end
 
+      # Return the ID of a named vApp
+      #
+      # @param name [String] the name of the vApp to find
+      # @return [String] the vApp ID
       def self.get_by_name(name)
         q = Vcloud::Core::QueryRunner.new
         query_results = q.run('vApp', :filter => "name==#{name}")
@@ -26,6 +34,10 @@ module Vcloud
         end
       end
 
+      # Return the ID of the vApp which contains a particular VM
+      #
+      # @param vm_id [String] the ID of the VM to find the parent for
+      # @return [String] the vApp ID
       def self.get_by_child_vm_id(vm_id)
         raise ArgumentError, "Must supply a valid Vm id" unless vm_id =~ /^vm-[-0-9a-f]+$/
         vm_body = Vcloud::Core::Fog::ServiceInterface.new.get_vapp(vm_id)
@@ -38,6 +50,9 @@ module Vcloud
         return self.new(parent_vapp_link.fetch(:href).split('/').last)
       end
 
+      # Return the vCloud data associated with vApp
+      #
+      # @return [Hash] the complete vCloud data for vApp
       def vcloud_attributes
         Vcloud::Core::Fog::ServiceInterface.new.get_vapp(id)
       end
@@ -47,33 +62,60 @@ module Vcloud
         POWERED_OFF = 8
       end
 
+      # Return the name of vApp
+      #
+      # @return [String] the name of instance
       def name
         vcloud_attributes[:name]
       end
 
+      # Return the href of vApp
+      #
+      # @return [String] the href of instance
       def href
         vcloud_attributes[:href]
       end
 
+      # Return the ID of the vDC containing vApp
+      #
+      # @return [String] the ID of the vDC containing vApp
       def vdc_id
         link = vcloud_attributes[:Link].detect { |l| l[:rel] == Fog::RELATION::PARENT && l[:type] == Fog::ContentTypes::VDC }
         link ? link[:href].split('/').last : raise('a vapp without parent vdc found')
       end
 
+      # Return the VMs within vApp
+      #
+      # @return [Hash] the VMs contained in the vApp
       def vms
         vcloud_attributes[:Children][:Vm]
       end
 
+      # Return the networks connected to vApp
+      #
+      # @return [Hash] a hash describing the networks
       def networks
         vcloud_attributes[:'ovf:NetworkSection'][:'ovf:Network']
       end
 
+      # Find a vApp by name and vDC
+      #
+      # @param name [String] name of the vApp to find
+      # @param vdc_name [String] name of the vDC
+      # @return [String] the ID of the instance
       def self.get_by_name_and_vdc_name(name, vdc_name)
         fog_interface = Vcloud::Core::Fog::ServiceInterface.new
         attrs = fog_interface.get_vapp_by_name_and_vdc_name(name, vdc_name)
         self.new(attrs[:href].split('/').last) if attrs && attrs.key?(:href)
       end
 
+      # Instantiate a vApp
+      #
+      # @param name [String] Name to use when creating the vApp
+      # @param network_names [Array] Array of Strings with names of Networks to connect to the vApp
+      # @param template_id [String] The ID of the template to use when creating the vApp
+      # @param vdc_name [String] The name of the vDC to create vApp in
+      # @return [String] the id of the created vApp
       def self.instantiate(name, network_names, template_id, vdc_name)
         Vcloud::Core.logger.info("Instantiating new vApp #{name} in vDC '#{vdc_name}'")
         fog_interface = Vcloud::Core::Fog::ServiceInterface.new
@@ -88,6 +130,10 @@ module Vcloud
         self.new(attrs[:href].split('/').last) if attrs and attrs.key?(:href)
       end
 
+      # Update custom_fields for vApp
+      #
+      # @param custom_fields [Array] Array of Hashes describing the custom fields
+      # @return [Boolean] return true or throws error
       def update_custom_fields(custom_fields)
         return if custom_fields.nil?
         fields = custom_fields.collect do |field|
@@ -108,6 +154,9 @@ module Vcloud
         Vcloud::Core::Fog::ServiceInterface.new.put_product_sections(@id, fields)
       end
 
+      # Power on vApp
+      #
+      # @return [Boolean] Returns true if the VM is running, false otherwise
       def power_on
         raise "Cannot power on a missing vApp." unless id
         return true if running?

data/lib/vcloud/core/vapp_template.rb

@@ -4,6 +4,9 @@ module Vcloud
 
       attr_reader :id
 
+      # Return the vCloud data associated with vApp
+      #
+      # @return [Hash] the complete vCloud data for vApp
       def initialize(id)
         unless id =~ /^#{self.class.id_prefix}-[-0-9a-f]+$/
           raise "#{self.class.id_prefix} id : #{id} is not in correct format"
@@ -11,18 +14,32 @@ module Vcloud
         @id = id
       end
 
+      # Return the vCloud data associated with vAppTemplate
+      #
+      # @return [Hash] the complete vCloud data for vAppTemplate
       def vcloud_attributes
         Vcloud::Core::Fog::ServiceInterface.new.get_vapp_template(id)
       end
 
+      # Return the name of vAppTemplate
+      #
+      # @return [String] the name of instance
       def href
         vcloud_attributes[:href]
       end
 
+      # Return the name of vAppTemplate
+      #
+      # @return [String] the name of instance
       def name
         vcloud_attributes[:name]
       end
 
+      # Get a list of templates with a particular name in a catalog
+      #
+      # @param name [String] The name of the vAppTemplate to find
+      # @param catalog_name [String] The name of the catalog to search
+      # @return [Array] an array of IDs of matching templates
       def self.get_ids_by_name_and_catalog name, catalog_name
         raise "provide Catalog and vAppTemplate name" unless name && catalog_name
         q = Vcloud::Core::QueryRunner.new
@@ -33,6 +50,11 @@ module Vcloud
         end
       end
 
+      # Get a template by name and catalog
+      #
+      # @param vapp_template_name [String] The name of the vAppTemplate
+      # @param catalog_name [String] The name of the catalog containing vAppTemplate
+      # @return [String] the ID of the template
       def self.get vapp_template_name, catalog_name
         ids = self.get_ids_by_name_and_catalog(vapp_template_name, catalog_name)
         raise 'Could not find template vApp' if ids.size == 0
@@ -42,6 +64,9 @@ module Vcloud
         return self.new(ids.first)
       end
 
+      # Return the id_prefix to be used for vAppTemplates
+      #
+      # @return [String] returns 'vappTemplate' as an id_prefix
       def self.id_prefix
         'vappTemplate'
       end

data/lib/vcloud/core/vdc.rb

@@ -4,6 +4,10 @@ module Vcloud
 
       attr_reader :id
 
+      # Initialize a Vcloud::Core::Vdc
+      #
+      # @param id [String] the vDC ID
+      # @return [Vcloud::Core::Vdc]
       def initialize(id)
         unless id =~ /^[-0-9a-f]+$/
           raise "vdc id : #{id} is not in correct format"
@@ -11,6 +15,10 @@ module Vcloud
         @id = id
       end
 
+      # Get the ID of a named vDC
+      #
+      # @param name [String] The name of the vDC
+      # @return [String] The ID of the vDC
       def self.get_by_name(name)
         q = Vcloud::Core::QueryRunner.new
         query_results = q.run('orgVdc', :filter => "name==#{name}")
@@ -19,14 +27,23 @@ module Vcloud
         return self.new(query_results.first[:href].split('/').last)
       end
 
+      # Return the vCloud data associated with vDC
+      #
+      # @return [Hash] the complete vCloud data for vDC
       def vcloud_attributes
         Vcloud::Core::Fog::ServiceInterface.new.get_vdc(id)
       end
 
+      # Return the name of vDC
+      #
+      # @return [String] the name of instance
       def name
         vcloud_attributes[:name]
       end
 
+      # Return the href of vDC
+      #
+      # @return [String] the href of instance
       def href
         vcloud_attributes[:href]
       end

data/lib/vcloud/core/version.rb

@@ -1,5 +1,5 @@
 module Vcloud
   module Core
-    VERSION = '0.13.0'
+    VERSION = '0.14.0'
   end
 end

data/lib/vcloud/core/vm.rb

@@ -5,6 +5,11 @@ module Vcloud
 
       attr_reader :id
 
+      # Initialize a Vcloud::Core::Vm within a vApp
+      #
+      # @param id [String] the VM ID
+      # @param vapp [Vcloud::Core::Vapp] The vApp object to create VM in
+      # @return [Vcloud::Core::Vm]
       def initialize(id, vapp)
         unless id =~ /^#{self.class.id_prefix}-[-0-9a-f]+$/
           raise "#{self.class.id_prefix} id : #{id} is not in correct format"
@@ -13,10 +18,17 @@ module Vcloud
         @vapp = vapp
       end
 
+      # Return the vCloud data associated with VM
+      #
+      # @return [Hash] the complete vCloud data for VM
       def vcloud_attributes
         Vcloud::Core::Fog::ServiceInterface.new.get_vapp(id)
       end
 
+      # Set the amount of memory in VM which can't be nil or less than 64 (mb)
+      #
+      # @param new_memory [Integer] amount of memory for instance
+      # @return [Boolean] return true or throws an error
       def update_memory_size_in_mb(new_memory)
         return if new_memory.nil?
         return if new_memory.to_i < 64
@@ -25,33 +37,56 @@ module Vcloud
         end
       end
 
+      # Return the amount of memory allocated to VM
+      #
+      # @return [Integer] amount of memory in megabytes
       def memory
         memory_item = virtual_hardware_section.detect { |i| i[:'rasd:ResourceType'] == '4' }
         memory_item[:'rasd:VirtualQuantity']
       end
 
+      # Return the number of CPUs allocated to the VM
+      #
+      # @return [Integer] number of virtual CPUs
       def cpu
         cpu_item = virtual_hardware_section.detect { |i| i[:'rasd:ResourceType'] == '3' }
         cpu_item[:'rasd:VirtualQuantity']
       end
 
+      # Return the name of VM
+      #
+      # @return [String] the name of instance
       def name
         vcloud_attributes[:name]
       end
 
+      # Return the href of VM
+      #
+      # @return [String] the href of instance
       def href
         vcloud_attributes[:href]
       end
 
+      # Update the name of VM
+      #
+      # @param new_name [String] The new name for the VM
+      # @return [Boolean] return true or throw an error
       def update_name(new_name)
         fsi = Vcloud::Core::Fog::ServiceInterface.new
         fsi.put_vm(id, new_name) unless name == new_name
       end
 
+      # Return the name of the vApp containing VM
+      #
+      # @return [String] the name of the vApp
       def vapp_name
         @vapp.name
       end
 
+      # Update the number of CPUs in VM
+      #
+      # @param new_cpu_count [Integer] The number of virtual CPUs to allocate
+      # @return [Boolean] return true or throw an error
       def update_cpu_count(new_cpu_count)
         return if new_cpu_count.nil?
         return if new_cpu_count.to_i == 0
@@ -60,6 +95,10 @@ module Vcloud
         end
       end
 
+      # Update the metadata for VM
+      #
+      # @param metadata [Hash] hash of keys, values to set
+      # @return [Boolean] return true or throw an error
       def update_metadata(metadata)
         return if metadata.nil?
         fsi = Vcloud::Core::Fog::ServiceInterface.new
@@ -69,6 +108,10 @@ module Vcloud
         end
       end
 
+      # Attach independent disk(s) to VM
+      #
+      # @param disk_list [Array] an array of Vcloud::Core::IndependentDisk objects
+      # @return [Boolean] return true or throw an error
       def attach_independent_disks(disk_list)
         disk_list = Array(disk_list) # ensure we have an array
         disk_list.each do |disk|
@@ -76,6 +119,10 @@ module Vcloud
         end
       end
 
+      # Detach independent disk(s) from VM
+      #
+      # @param disk_list [Array] an array of Vcloud::Core::IndependentDisk objects
+      # @return [Boolean] return true or throw an error
       def detach_independent_disks(disk_list)
         disk_list = Array(disk_list) # ensure we have an array
         disk_list.each do |disk|
@@ -83,6 +130,10 @@ module Vcloud
         end
       end
 
+      # Add extra disks to VM
+      #
+      # @param extra_disks [Array] An array of hashes like [{ size: '20480' }]
+      # @return [Boolean] return true or throw an error
       def add_extra_disks(extra_disks)
         vm = Vcloud::Core::Fog::ModelInterface.new.get_vm_by_href(href)
         if extra_disks
@@ -93,6 +144,10 @@ module Vcloud
         end
       end
 
+      # Configure VM network interfaces
+      #
+      # @param networks_config [Array] An array of hashes like [{ :name => 'NetworkName' }]
+      # @return [Boolean] return true or throw an error
       def configure_network_interfaces(networks_config)
         return unless networks_config
         section = {PrimaryNetworkConnectionIndex: 0}
@@ -116,10 +171,18 @@ module Vcloud
         Vcloud::Core::Fog::ServiceInterface.new.put_network_connection_system_section_vapp(id, section)
       end
 
+      # Configure guest customisation script
+      #
+      # @param preamble [String] A script to run when the VM is created
+      # @return [Boolean] return true or throw an error
       def configure_guest_customization_section(preamble)
         Vcloud::Core::Fog::ServiceInterface.new.put_guest_customization_section(id, vapp_name, preamble)
       end
 
+      # Update the storage profile of a VM
+      #
+      # @param storage_profile [String] The name of the storage profile
+      # @return [Boolean] return true or throw an error
       def update_storage_profile storage_profile
         storage_profile_href = get_storage_profile_href_by_name(storage_profile, @vapp.name)
         Vcloud::Core::Fog::ServiceInterface.new.put_vm(id, name, {

data/spec/integration/core/query_runner_spec.rb

@@ -185,6 +185,24 @@ module Vcloud
 
         end
 
+        context "automatic pagination can be suppressed with page/pageSize options" do
+          before(:all) do
+            @first_vapp_name = ''
+          end
+
+          it "returns the first singular result" do
+            results = Vcloud::Core::QueryRunner.new.run('vApp', sortAsc: 'name', pageSize: 1)
+            expect(results).to have(1).items
+            @first_vapp_name = results.first.fetch(:name)
+          end
+
+          it "returns the next singular result which is different from the first" do
+            results = Vcloud::Core::QueryRunner.new.run('vApp', sortAsc: 'name', pageSize: 1, page: 2)
+            expect(results).to have(1).items
+            expect(results.first.fetch(:name)).not_to eq(@first_vapp_name)
+          end
+        end
+
         after(:all) do
           IntegrationHelper.delete_vapps(@test_case_vapps)
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vcloud-core
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-13 00:00:00.000000000 Z
+date: 2014-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fog
-  requirement: &4397480 !ruby/object:Gem::Requirement
+  requirement: &11276440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 1.24.0
   type: :runtime
   prerelease: false
-  version_requirements: *4397480
+  version_requirements: *11276440
 - !ruby/object:Gem::Dependency
   name: mustache
-  requirement: &4395720 !ruby/object:Gem::Requirement
+  requirement: &11275840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *4395720
+  version_requirements: *11275840
 - !ruby/object:Gem::Dependency
   name: highline
-  requirement: &4520880 !ruby/object:Gem::Requirement
+  requirement: &11275060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *4520880
+  version_requirements: *11275060
 - !ruby/object:Gem::Dependency
   name: gem_publisher
-  requirement: &4516360 !ruby/object:Gem::Requirement
+  requirement: &11274300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -54,10 +54,10 @@ dependencies:
         version: 1.2.0
   type: :development
   prerelease: false
-  version_requirements: *4516360
+  version_requirements: *11274300
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &4478040 !ruby/object:Gem::Requirement
+  requirement: &11273220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *4478040
+  version_requirements: *11273220
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &4476980 !ruby/object:Gem::Requirement
+  requirement: &11272420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *4476980
+  version_requirements: *11272420
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &4475000 !ruby/object:Gem::Requirement
+  requirement: &11270040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -87,10 +87,10 @@ dependencies:
         version: 2.14.1
   type: :development
   prerelease: false
-  version_requirements: *4475000
+  version_requirements: *11270040
 - !ruby/object:Gem::Dependency
   name: rubocop
-  requirement: &4472300 !ruby/object:Gem::Requirement
+  requirement: &11286180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -98,10 +98,10 @@ dependencies:
         version: 0.23.0
   type: :development
   prerelease: false
-  version_requirements: *4472300
+  version_requirements: *11286180
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &4470940 !ruby/object:Gem::Requirement
+  requirement: &11345780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -109,10 +109,10 @@ dependencies:
         version: 0.7.1
   type: :development
   prerelease: false
-  version_requirements: *4470940
+  version_requirements: *11345780
 - !ruby/object:Gem::Dependency
   name: vcloud-tools-tester
-  requirement: &4863720 !ruby/object:Gem::Requirement
+  requirement: &11344000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -120,7 +120,7 @@ dependencies:
         version: 0.2.0
   type: :development
   prerelease: false
-  version_requirements: *4863720
+  version_requirements: *11344000
 description: Core tools for interacting with VMware vCloud Director. Includes VCloud
   Query, a light wrapper round the vCloud Query API.
 email:
@@ -229,7 +229,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1721799035721332313
+      hash: -2644317041570452992
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.11