Propogate the DataCenter and ImageTemplate models so they are used consistently in the API. Made notes in the changelog about the changes.

Author: SLsthompson

CHANGELOG.textile

@@ -1,7 +1,8 @@
 *3.0*
 * Added a method to reboot servers.
-* Added a model for Virtual Server Image Templates
-* Substantially rewrote the ObjectFilter class.
+* Substantially rewrote the ObjectFilter class.  ObjectFilters used to be hashes which made it easy to manipulate their content incorrectly. The new implementation has a strict interface that makes it harder to manipulate filters incorrectly.
+* Added a model for Virtual Server Image Templates (SoftLayer::ImageTemplate) - VirtualServerOrder now requires an instance of this class rather than allowing you to provide just the global_id of an image
+* Added a model for data centers (SoftLayer::Datacenter). Bare Metal, Bare Metal Package, and Virtual server orders now use an instance of Datacenter to identify where their servers will be provisioned. The routines in those classes which used to provide lists of valid data center names now return data center objects.
 
 *2.1.1*
 * Virtual server upgrades no longer raise exceptions

doc_src/Contribution Guide.md

@@ -8,7 +8,7 @@ Any requests for enhancements, new features, or bug reports should be entered in
 
 # Development Environment
 
-As a Ruby project, your first step will be to install the [Ruby Programming Language](https://www.ruby-lang.org/en/). Many Unix-derived environments, including Mac OS X, have a version or Ruby installed by default, however, the default version may be out-of-date. Please visit the main Ruby language [site](https://www.ruby-lang.org/en/) for instructions on installing an up-to-date build of Ruby for your computing environment. 
+As a Ruby project, your first step will be to install the [Ruby Programming Language](https://www.ruby-lang.org/en/). Many Unix-derived environments, including Mac OS X, have a version or Ruby installed by default, however, the default version may be out-of-date. Please visit the main Ruby language [site](https://www.ruby-lang.org/en/) for instructions on installing an up-to-date build of Ruby for your computing environment.
 
 The Gem supports multiple versions of Ruby, and we recommend using Ruby 2.0 or later. The [Ruby Version Manager (rvm)](https://rvm.io) is an invaluable tool to help keep track of multiple versions of Ruby. The Gem no longer supports Ruby 1.8.7.  Support for Ruby 1.9 will continue for a time, but the Core Ruby team is already withdrawing their support for that version.
 
@@ -93,7 +93,7 @@ The basic directory structure for the source tree is as follows
 	  softlayer   # Folder containing most of the gem's actual source code
 	log			  # RVM will create a log folder when running commands across multiple ruby versions.
 	pkg			  # Created when the gem is built, contains built versions of the gem
-	spec		  # Source directory for the RSpec testing specifications 
+	spec		  # Source directory for the RSpec testing specifications
 	  fixtures    # Files used by the unit tests to mock responses from the SoftLayer network API
 
 Most of the source files that implement the gem are found in `lib/softlayer`.  If you wish to add new functionality, or edit existing functionality, you will probably edit the class files in this directory. Unit tests using Rspec are found in the spec folder and should generally follow the naming convention of <Class>_spec.rb

lib/softlayer/BareMetalServerOrder.rb

@@ -32,8 +32,7 @@ class BareMetalServerOrder
     # a Bare Metal Instance
     #++
 
-    # String, short name of the data center that will house the new Bare Metal Instance (e.g. "dal05" or "sea01")
-    # Corresponds to +datacenter.name+ in the documentation for +createObject+.
+    # An instance of SoftLayer::Datacenter. The server will be provisioned in this data center
     attr_accessor :datacenter
 
     # String, The hostname to assign to the new server
@@ -152,7 +151,7 @@ def hardware_instance_template
 
       template["privateNetworkOnlyFlag"] = true if @private_network_only
 
-      template["datacenter"] = {"name" => @datacenter} if @datacenter
+      template["datacenter"] = {"name" => @datacenter.name} if @datacenter
       template['userData'] = [{'value' => @user_metadata}] if @user_metadata
       template['networkComponents'] = [{'maxSpeed'=> @max_port_speed}] if @max_port_speed
       template['postInstallScriptUri'] = @provision_script_URI.to_s if @provision_script_URI
@@ -184,7 +183,7 @@ def self.create_object_options(client = nil)
     ##
     # Return a list of values that are valid for the :datacenter attribute
     def self.datacenter_options(client = nil)
-      create_object_options(client)["datacenters"].collect { |datacenter_spec| datacenter_spec['template']['datacenter']["name"] }.uniq.sort!
+      create_object_options(client)["datacenters"].collect { |datacenter_spec| Datacenter.datacenter_named(datacenter_spec['template']['datacenter']['name'], client) }.uniq
     end
 
     def self.core_options(client = nil)

lib/softlayer/BareMetalServerOrder_Package.rb

@@ -28,13 +28,14 @@ module SoftLayer
   class BareMetalServerOrder_Package < Server
     # The following properties are required in a server order.
 
-    # The product package identifying the base configuration for the server.
-    # a list of Bare Metal Server product packages is returned by
+    # The product package object (an instance of SoftLayer::ProductPackage) identifying the base 
+    # configuration for the server. A list of Bare Metal Server product packages is returned by
     # SoftLayer::ProductPackage.bare_metal_server_packages
     attr_reader :package
 
-    # String, short name of the data center that will house the new virtual server (e.g. "dal05" or "sea01")
-    # A list of valid data centers can be found in ProductPackage#datacenter_options
+    # An instance of SoftLayer::Datacenter. The server will be provisioned in this data center.
+    # The set of datacenters available is determined by the package and may be obtained from
+    # the SoftLayer::ProductPackage object using the #datacenter_options method.
     attr_accessor :datacenter
 
     # The hostname of the server being created (i.e. 'sldn' is the hostname of sldn.softlayer.com).
@@ -125,8 +126,7 @@ def hardware_order
         }
       }
 
-      product_order['location'] = @package.location_id_for_datacenter_name(@datacenter.downcase) if @datacenter
-
+      product_order['location'] = @datacenter.id if @datacenter
       product_order['sshKeys'] = [{ 'sshKeyIds' => @ssh_key_ids }] if @ssh_key_ids
       product_order['provisionScripts'] = [@provision_script_URI.to_s] if @provision_script_URI
 
@@ -142,7 +142,5 @@ def hardware_order
 
       product_order
     end
-
   end # BareMetalServerOrder_Package
-
 end # SoftLayer

lib/softlayer/Datacenter.rb

@@ -8,8 +8,8 @@ module SoftLayer
   ##
   # A Data Center in the SoftLayer network
   #
-  # This class corresponds to the +SoftLayer_Location+ data type:
-  # 
+  # This class corresponds to the SoftLayer_Location++ data type:
+  #
   # http://sldn.softlayer.com/reference/datatypes/SoftLayer_Location
   #
   # Although in this context it is used to represent a data center and

lib/softlayer/ImageTemplate.rb

@@ -54,7 +54,7 @@ def flex_image?
     ##
     # Changes the notes on an template to be the given strings
     def notes=(new_notes)
-      # it is not a typo that this sets the "note" property.  The 
+      # it is not a typo that this sets the "note" property.  The
       # property in the network api is "note", the model exposes it as
       # 'notes' for self-consistency
       self.service.editObject({ "note" => new_notes.to_s})
@@ -67,11 +67,11 @@ def tags
     end
 
     ##
-    # Sets the tags on the template.  Note: a pre-existing tag will be 
+    # Sets the tags on the template.  Note: a pre-existing tag will be
     # removed from the template if it does not appear in the array given.
     # The list of tags must be comprehensive.
     def tags=(tags_array)
-      as_strings = tags_array.collect { |tag| tag.to_s }      
+      as_strings = tags_array.collect { |tag| tag.to_s }
       self.service.setTags(as_strings.join(','))
     end
 
@@ -83,7 +83,7 @@ def datacenters
 
     ##
     # Accepts an array of datacenters (instances of SoftLayer::Datacenter) where this
-    # image should be made available. The call will kick off one or more transactions 
+    # image should be made available. The call will kick off one or more transactions
     # to make the image available in the given datacenters. These transactions can take
     # some time to complete.
     #
@@ -99,10 +99,10 @@ def datacenters=(datacenters_array)
 
       self.service.setAvailableLocations(datacenter_data.compact)
     end
-    
+
     ##
     # Returns an array of the datacenters that this image can be stored in.
-    # This is the set of datacenters that you may choose from, when putting 
+    # This is the set of datacenters that you may choose from, when putting
     # together a list you will send to the datacenters= setter.
     #
     def available_datacenters
@@ -118,7 +118,7 @@ def shared_with_accounts
       accounts_data = self.service.getAccountReferences
       accounts_data.collect { |account_data| account_data["accountId"] }
     end
-    
+
     ##
     # Change the set of accounts that this image is shared with.
     # The parameter is an array of account ID's.
@@ -136,7 +136,7 @@ def shared_with_accounts= (account_id_list)
       # with the account that owns it, however, this leads to a rather odd state
       # where the image has allocated resources (that the account may be charged for)
       # but no way to delete those resources. For that reason this model
-      # always includes the account ID that owns the image in the list of 
+      # always includes the account ID that owns the image in the list of
       # accounts the image will be shared with.
       my_account_id = self['accountId']
       accounts_to_add.push(my_account_id) if !already_sharing_with.include?(my_account_id) && !accounts_to_add.include?(my_account_id)
@@ -158,9 +158,9 @@ def shared_with_accounts= (account_id_list)
     def delete!
       self.service.deleteObject
     end
-    
+
     ##
-    # Repeatedly poll the netwokr API until transactions related to this image 
+    # Repeatedly poll the netwokr API until transactions related to this image
     # template are finished
     #
     # A template is not 'ready' until all the transactions on the template
@@ -179,7 +179,7 @@ def wait_until_ready(max_trials, seconds_between_tries = 2)
         parent_ready = !(has_sl_property? :transactionId) || (self[:transactionId] == "")
         children_ready = (nil == self["children"].find { |child| child["transactionId"] != "" })
 
-        ready = parent_ready && children_ready        
+        ready = parent_ready && children_ready
         yield ready if block_given?
 
         num_trials = num_trials + 1
@@ -188,12 +188,12 @@ def wait_until_ready(max_trials, seconds_between_tries = 2)
 
       ready
     end
-    
+
     # ModelBase protocol methods
     def service
       softlayer_client['Virtual_Guest_Block_Device_Template_Group'].object_with_id(self.id)
     end
-    
+
     def softlayer_properties(object_mask = nil)
       self.service.object_mask(self.class.default_object_mask).getObject
     end
@@ -342,7 +342,7 @@ def self.find_public_templates(options_hash = {})
     # If no client can be found the routine will raise an error.
     #
     # The options may include the following keys
-    # * <b>+:object_mask+</b> (string) - A object mask of properties, in addition to the default properties, that you wish to retrieve for the server
+    # * <b>+:object_mask+</b> (string) - A object mask of properties, in addition to the default properties, that you wish to retrieve for the template
     def self.template_with_id(id, options_hash = {})
       softlayer_client = options_hash[:client] || Client.default_client
       raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client
@@ -358,10 +358,27 @@ def self.template_with_id(id, options_hash = {})
       new(softlayer_client, template_data)
     end
 
+    ##
+    # Retrieve the image template with the given global ID
+    #
+    # The options parameter should contain:
+    #
+    # <b>+:client+</b> - The client used to connect to the API
+    #
+    # If no client is given, then the routine will try to use Client.default_client
+    # If no client can be found the routine will raise an error.
+    #
+    # The options may include the following keys
+    # * <b>+:object_mask+</b> (string) - A object mask of properties, in addition to the default properties, that you wish to retrieve for the template
+    def self.template_with_global_id(global_id, options_hash = {})
+      templates = find_public_templates(options_hash.merge(:global_id => global_id))
+      templates.empty? ? nil : templates[0]
+    end
+
     protected
 
     def self.default_object_mask
       return "mask[id,accountId,name,note,globalIdentifier,datacenters,blockDevices,tagReferences,publicFlag,flexImageFlag,transactionId,children.transactionId]"
     end
-  end
+  end  
 end

lib/softlayer/ModelBase.rb

@@ -116,7 +116,7 @@ def to_ary()
     #
     def softlayer_properties(object_mask = nil)
       raise "Abstract method softlayer_properties in ModelBase was called"
-    end 
+    end
 
     ##
     # The softlayer_hash stores the low-level information about an

lib/softlayer/ProductPackage.rb

@@ -45,7 +45,7 @@ class ProductPackage < ModelBase
 
     ##
     # The list of locations where this product package is available.
-    sl_attr :availableLocations
+    sl_attr :available_locations, 'availableLocations'
 
     ##
     # The set of product categories needed to make an order for this product package.
@@ -105,15 +105,7 @@ def category(category_code)
     end
 
     def datacenter_options
-      availableLocations.collect { |location_data| location_data["location"]["name"] }
-    end
-
-    ##
-    # Given a datacenter name that was returned by datacenter_options, use information
-    # in the package to retrieve a location id.
-    def location_id_for_datacenter_name(datacenter_name)
-      location_data = availableLocations.find { |location_data| location_data["location"]["name"]  == datacenter_name }
-      location_data["locationId"]
+      available_locations.collect { |location_data| Datacenter::datacenter_named(location_data["location"]["name"], self.softlayer_client) }.compact
     end
 
     def service

lib/softlayer/VirtualServer.rb

@@ -131,7 +131,7 @@ def upgrade_max_port_speed!(network_speed_in_Mbps)
     #
     # The routine returns the instance of SoftLayer::ImageTemplate that is
     # created.  That image template will probably not be available immediately, however.
-    # You may use the wait_until_ready routine of SoftLayer::ImageTemplate to 
+    # You may use the wait_until_ready routine of SoftLayer::ImageTemplate to
     # wait on it.
     #
     def capture_image(image_name, include_attached_storage = false, image_notes = nil)
@@ -141,7 +141,7 @@ def capture_image(image_name, include_attached_storage = false, image_notes = ni
       disks = self.blockDevices.select(&disk_filter)
 
       self.service.createArchiveTransaction(image_name, disks, notes ? notes : "") if disks && !disks.empty?
-      
+
       image_templates = SoftLayer::ImageTemplate.find_private_templates(:name => image_name)
       image_templates[0] if !image_templates.empty?
     end

lib/softlayer/VirtualServerOrder.rb

@@ -24,9 +24,7 @@ class VirtualServerOrder
     # a virtual server
     #++
 
-    # String, short name of the data center that will house the new virtual server (e.g. "dal05" or "sea01")
-    # Corresponds to +datacenter.name+ in the documentation for createObject.  If not provided, the server will
-    # be provisioned in the first available data center.
+    # An instance of SoftLayer::Datacenter.  The server will be provisioned in that Datacenter.
     attr_accessor :datacenter
 
     # String, The hostname to assign to the new server
@@ -44,17 +42,18 @@ class VirtualServerOrder
     attr_accessor :memory
 
     #--
-    # These two options are mutually exclusive, but one or the other must be provided.
-    # If you provide both, the image_global_id will be added to the order and the os_reference_code will be ignored
+    # These two options are mutually exclusive, but one of them must be provided.
+    # If you provide both, the image_template will be added to the order and the 
+    # os_reference_code will be ignored
     #++
 
     # String, An OS reference code for the operating system to install on the virtual server
     # Corresponds to +operatingSystemReferenceCode+ in the +createObject+ documentation
     attr_accessor :os_reference_code
 
-    # String, The globalIdentifier of a disk image to put on the newly created server
-    # Corresponds to +blockDeviceTemplateGroup.globalIdentifier+ in the +createObject+ documentation
-    attr_accessor :image_global_id
+    # An instance of the SoftLayer::ImageTemplate class.  Represents the image template that should
+    # be installed on the server.
+    attr_accessor :image_template
 
     #--
     # Optional attributes
@@ -159,16 +158,16 @@ def virtual_guest_template
       template["dedicatedAccountHostOnlyFlag"] = true if @dedicated_host_only
       template["privateNetworkOnlyFlag"] = true if @private_network_only
 
-      template["datacenter"] = {"name" => @datacenter} if @datacenter
+      template["datacenter"] = {"name" => @datacenter.name} if @datacenter
       template['userData'] = [{'value' => @user_metadata}] if @user_metadata
       template['networkComponents'] = [{'maxSpeed'=> @max_port_speed}] if @max_port_speed
       template['postInstallScriptUri'] = @provision_script_URI.to_s if @provision_script_URI
       template['sshKeys'] = @ssh_key_ids.collect { |ssh_key_id| {'id'=> ssh_key_id.to_i } } if @ssh_key_ids
       template['primaryNetworkComponent'] = { "networkVlan" => { "id" => @public_vlan_id.to_i } } if @public_vlan_id
       template["primaryBackendNetworkComponent"] = { "networkVlan" => {"id" => @private_vlan_id.to_i } } if @private_vlan_id
 
-      if @image_global_id
-          template["blockDeviceTemplateGroup"] = {"globalIdentifier" => @image_global_id}
+      if @image_template
+          template["blockDeviceTemplateGroup"] = {"globalIdentifier" => @image_template.global_id}
       elsif @os_reference_code
           template["operatingSystemReferenceCode"] = @os_reference_code
       end
@@ -213,7 +212,7 @@ def self.create_object_options(client = nil)
     ##
     # Return a list of values that are valid for the :datacenter attribute
     def self.datacenter_options(client = nil)
-      create_object_options(client)["datacenters"].collect { |datacenter_spec| datacenter_spec['template']['datacenter']["name"] }.uniq.sort!
+      create_object_options(client)["datacenters"].collect { |datacenter_spec| Datacenter.datacenter_named(datacenter_spec['template']['datacenter']['name'], client) }.uniq
     end
 
     ##