Pull remote changes into the local branch to complete merging 2.2.2 into 3.0 branch

Author: SLsthompson

CHANGELOG.textile

@@ -1,10 +1,11 @@
 *3.0*
 * 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 Virtual Server Image Templates (SoftLayer::ImageTemplate) - VirtualServerOrder now requires an instance of this class rather than allowing you to provide 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.
 * Virtual Server Upgrades are now handled by the VirtualServerUpgradeOrder class and not the VirtualServer class. This change was made for several reasons. Firt and foremost, it allows multiple aspects of a virtual server to be upgraded at once without having to wait on separate transactions to complete between upgrades. Secondly it opens the door for additional upgrades (for example, to disk configuration) to be added in the future.
 * Added a method to reboot servers.
 * The routine to retreive the open tickets on an account has been moved from the Ticket class. The set of open tickets is now a dynamic property of an account object.
+* The Model Layer now includes models for Server (aka. Shared) and VLAN (aka. Dedicated) firewalls in the ServerFirewall, and VLANFireall classes respectively.  There are corresponding classes for ordering firewalls (ServerFirewallOrder and VLANFirewallOrder).  To facilitate the process of locating the 'id' for a firewall, the Account class includes the find_VLAN_with_number routine which lets you look up the segments of a firewall from the VLAN nubmer.
 
 *2.2.2*
 * Fixed a bug in BareMetalServerOrder_Package.rb where the order template did not use an array for the "hardware" key.  This lead to an order template that would be accepted by verifyOrder, but rejected by placeOrder.  An internal issue to review verifyOrder has also been generated. (reported by Rohit Singh)

examples/order_bare_metal_package.rb

@@ -129,11 +129,11 @@ def tl_dr_version
   # We have a configuration for the server, we also need a location for the new server.
   # The package can give us a list of locations. Let's print out that list
   puts "\nData Centers for '#{quad_intel_package.name}':"
-  quad_intel_package.datacenter_options.each { |location| puts "\t#{location}"}
+  quad_intel_package.datacenter_options.each { |datacenter| puts "\t#{datacenter.name}"}
 
   # With all the config options in place we can now construct the product order.
   server_order = SoftLayer::BareMetalServerOrder_Package.new(quad_intel_package, client)
-  server_order.datacenter = 'sng01'
+  server_order.datacenter = SoftLayer::Datacenter.datacenter_named 'sng01', client
   server_order.hostname = 'sample'
   server_order.domain = 'softlayerapi.org'
   server_order.configuration_options = config_options

examples/order_server_firewall.rb

@@ -0,0 +1,63 @@
+#
+# Copyright (c) 2014 SoftLayer Technologies, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+require 'rubygems'
+require 'softlayer_api'
+require 'pp'
+
+# This is the id of the server you want to protect with a firewall.
+# The server can be Bare Metal or Virtual.  It should have a public
+# network interface, and it should not already have a firewall on it.
+server_id = 257696 # 12345
+
+# In this example, we assume this is a Bare Metal Server
+is_virtual_server = false
+
+# Work with the SoftLayer API begins with a client.  By setting
+# the "default" client we avoid having to specify the client repeatedly
+# in calls that follow.
+SoftLayer::Client.default_client = SoftLayer::Client.new(
+  # :username => "joecustomer"              # enter your username here
+  # :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+)
+
+# in this case we go straight to the appropriate class to find the server
+# an alternative might be to create the account for this client and
+# search the list of servers for the one with the appropriate ID.
+if is_virtual_server
+  server = SoftLayer::VirtualServer.server_with_id(server_id)
+else
+  server = SoftLayer::BareMetalServer.server_with_id(server_id)
+end
+
+# Create an instance of SoftLayer::ServerFirewallOrder
+order = SoftLayer::ServerFirewallOrder.new(server)
+
+begin
+  # this example calls order.verify which will build the order, submit it 
+  # to the network API, and will throw an exception if the order is
+  # invalid.
+  order.verify()
+  puts "Firewall order is good for #{server.fullyQualifiedDomainName}"
+rescue => exception
+  puts "Firewall order failed for #{server.fullyQualifiedDomainName} because #{exception}"
+end

lib/softlayer/APIParameterFilter.rb

@@ -43,6 +43,13 @@ def initialize(target, starting_parameters = nil)
     @parameters = starting_parameters || {}
   end
 
+  ##
+  # API Parameter filters will call through to a particular service
+  # but that service is defined by their target
+  def service_name
+    return @target.service_name
+  end
+
   ##
   # Adds an API filter that narrows the scope of a call to an object with
   # a particular ID. For example, if you want to get the ticket
@@ -173,7 +180,7 @@ def server_result_offset
   ##
   # A utility method that returns the object filter (if any) stored with this filter.
   def server_object_filter
-    self.parameters[:object_filter].to_h
+    self.parameters[:object_filter].to_h if self.parameters.has_key?(:object_filter)
   end
 
   ##

lib/softlayer/Account.rb

@@ -123,7 +123,25 @@ class Account < SoftLayer::ModelBase
     end
 
     def service
-      softlayer_client["Account"].object_with_id(self.id)
+      softlayer_client[:Account].object_with_id(self.id)
+    end
+
+    ##
+    # Searches the account's list of VLANs for the ones with the given
+    # vlan number. This may return multiple results because a VLAN can
+    # span different routers and you will get a separate segment for
+    # each router.
+    #
+    # The IDs of the different segments can be helpful for ordering
+    # firewalls.
+    #
+    def find_VLAN_with_number(vlan_number)
+      filter = SoftLayer::ObjectFilter.new() { |filter|
+        filter.accept('networkVlans.vlanNumber').when_it is vlan_number
+      }
+
+      vlan_data = self.service.object_mask("mask[id,vlanNumber,primaryRouter,networkSpace]").object_filter(filter).getNetworkVlans
+      return vlan_data
     end
 
     ##
@@ -134,7 +152,7 @@ def self.account_for_client(client = nil)
       softlayer_client = client || Client.default_client
       raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client
 
-      account_service = softlayer_client['Account']
+      account_service = softlayer_client[:Account]
       network_hash = account_service.getObject()
       new(softlayer_client, network_hash)
     end

lib/softlayer/BareMetalServer.rb

@@ -27,7 +27,7 @@ class BareMetalServer < Server
     #
     def bare_metal_instance?
       if has_sl_property?(:bareMetalInstanceFlag)
-        self["bareMetalInstanceFlag"] != 0
+        self['bareMetalInstanceFlag'] != 0
       else
         false
       end
@@ -47,19 +47,20 @@ def cancel!(reason = :unneeded, comment = '')
       if !bare_metal_instance? then
         cancellation_reasons = self.class.cancellation_reasons()
         cancel_reason = cancellation_reasons[reason] || cancellation_reasons[:unneeded]
-        softlayer_client["Ticket"].createCancelServerTicket(self.id, cancel_reason, comment, true, 'HARDWARE')
+        softlayer_client[:Ticket].createCancelServerTicket(self.id, cancel_reason, comment, true, 'HARDWARE')
       else
         # Note that reason and comment are ignored in this case, unfortunately
-        softlayer_client['Billing_Item'].object_with_id(self.billingItem['id'].to_i).cancelService()
+        softlayer_client[:Billing_Item].object_with_id(self.billingItem['id'].to_i).cancelService()
       end
     end
 
     ##
-    # Returns the SoftLayer Service used to work with this Server
+    # Returns the typical Service used to work with this Server
     # For Bare Metal Servers that is +SoftLayer_Hardware+ though in some special cases
-    # you may have to use +SoftLayer_Hardware_Server+ as a type or service.
+    # you may have to use +SoftLayer_Hardware_Server+ as a type or service.  That
+    # service object is available thorugh the hardware_server_service method
     def service
-      return softlayer_client["Hardware"].object_with_id(self.id)
+      return softlayer_client[:Hardware_Server].object_with_id(self.id)
     end
 
     ##
@@ -106,6 +107,36 @@ def self.cancellation_reasons
       }
     end
 
+    ##
+    # Returns the max port speed of the public network interfaces of the server taking into account
+    # bound interface pairs (redundant network cards).
+    def firewall_port_speed
+      network_components = self.service.object_mask("mask[id,maxSpeed,networkComponentGroup.networkComponents]").getFrontendNetworkComponents()
+
+      # Split the interfaces into grouped and ungrouped interfaces. The max speed of a group will be the sum
+      # of the individual speeds in that group.  The max speed of ungrouped interfaces is simply the max speed
+      # of that interface.
+      grouped_interfaces, ungrouped_interfaces = network_components.partition{ |interface| interface.has_key?("networkComponentGroup") }
+
+      if !grouped_interfaces.empty?
+        group_speeds = grouped_interfaces.collect do |interface|
+          interface['networkComponentGroup']['networkComponents'].inject(0) {|total_speed, component| total_speed += component['maxSpeed']}
+        end
+
+        max_group_speed = group_speeds.max
+      else
+        max_group_speed = 0
+      end
+
+      if !ungrouped_interfaces.empty?
+        max_ungrouped_speed = ungrouped_interfaces.collect { |interface| interface['maxSpeed']}.max
+      else
+        max_ungrouped_speed = 0
+      end
+
+      return [max_group_speed, max_ungrouped_speed].max
+    end
+
     ##
     # Retrive the bare metal server with the given server ID from the
     # SoftLayer API
@@ -120,7 +151,7 @@ def self.server_with_id(server_id, options = {})
       softlayer_client = options[:client] || Client.default_client
       raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client
 
-      hardware_service = softlayer_client["Hardware"]
+      hardware_service = softlayer_client[:Hardware_Server]
       hardware_service = hardware_service.object_mask(default_object_mask.to_sl_object_mask)
 
       if options.has_key?(:object_mask)
@@ -199,7 +230,7 @@ def self.find_servers(options_hash = {})
           } );
       end
 
-      account_service = softlayer_client['Account']
+      account_service = softlayer_client[:Account]
       account_service = account_service.object_filter(object_filter) unless object_filter.empty?
       account_service = account_service.object_mask(default_object_mask.to_sl_object_mask)
 

lib/softlayer/BareMetalServerOrder.rb

@@ -111,7 +111,7 @@ def verify()
       order_template = hardware_instance_template
       order_template = yield order_template if block_given?
 
-      @softlayer_client["Hardware"].generateOrderTemplate(order_template)
+      @softlayer_client[:Hardware].generateOrderTemplate(order_template)
     end
 
     ##
@@ -124,8 +124,8 @@ def place_order!()
       order_template = hardware_instance_template
       order_template = yield order_template if block_given?
 
-      server_hash = @softlayer_client["Hardware"].createObject(order_template)
-      SoftLayer::BareMetalServer.server_with_id(server_hash["id"], :client => @softlayer_client) if server_hash
+      server_hash = @softlayer_client[:Hardware].createObject(order_template)
+      SoftLayer::BareMetalServer.server_with_id(server_hash['id'], :client => @softlayer_client) if server_hash
     end
 
     protected
@@ -147,15 +147,15 @@ def hardware_instance_template
         "hourlyBillingFlag" => !!@hourly
       }
 
-      template["privateNetworkOnlyFlag"] = true if @private_network_only
+      template['privateNetworkOnlyFlag'] = true if @private_network_only
 
-      template["datacenter"] = {"name" => @datacenter.name} 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'=> ssh_key.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
+      template['primaryBackendNetworkComponent'] = { "networkVlan" => {"id" => @private_vlan_id.to_i } } if @private_vlan_id
 
       if @disks && !@disks.empty?
         template['hardDrives'] = @disks.collect do |disk|
@@ -174,36 +174,36 @@ def self.create_object_options(client = nil)
       raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client
 
       @@create_object_options ||= nil
-      @@create_object_options = softlayer_client["Hardware"].getCreateObjectOptions() if !@@create_object_options
+      @@create_object_options = softlayer_client[:Hardware].getCreateObjectOptions() if !@@create_object_options
       @@create_object_options
     end
 
     ##
     # 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.datacenter_named(datacenter_spec['template']['datacenter']['name'], client) }.uniq
+      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)
-      create_object_options(client)["processors"].collect { |processor_spec| processor_spec['template']['processorCoreAmount'] }.uniq.sort!
+      create_object_options(client)['processors'].collect { |processor_spec| processor_spec['template']['processorCoreAmount'] }.uniq.sort!
     end
 
     ##
     # Return a list of values that are valid the array given to the :disks
     def self.disk_options(client = nil)
-      create_object_options(client)["hardDrives"].collect { |disk_spec| disk_spec['template']['hardDrives'][0]['capacity'].to_i}.uniq.sort!
+      create_object_options(client)['hardDrives'].collect { |disk_spec| disk_spec['template']['hardDrives'][0]['capacity'].to_i}.uniq.sort!
     end
 
     ##
     # Returns a list of the valid :os_refrence_codes
     def self.os_reference_code_options(client = nil)
-      create_object_options(client)["operatingSystems"].collect { |os_spec| os_spec['template']['operatingSystemReferenceCode'] }.uniq.sort!
+      create_object_options(client)['operatingSystems'].collect { |os_spec| os_spec['template']['operatingSystemReferenceCode'] }.uniq.sort!
     end
 
     ##
     # Returns a list of the :max_port_speeds
     def self.max_port_speed_options(client = nil)
-      create_object_options(client)["networkComponents"].collect { |component_spec| component_spec['template']['networkComponents'][0]['maxSpeed'] }
+      create_object_options(client)['networkComponents'].collect { |component_spec| component_spec['template']['networkComponents'][0]['maxSpeed'] }
     end
 
   end # class BareMetalServerOrder

lib/softlayer/BareMetalServerOrder_Package.rb

@@ -58,7 +58,7 @@ class BareMetalServerOrder_Package < Server
 
     # An array of the ids of SSH keys to install on the server upon provisioning
     # To obtain a list of existing SSH keys, call getSshKeys on the SoftLayer_Account service:
-    #     client['Account'].getSshKeys()
+    #     client[:Account].getSshKeys()
     attr_accessor :ssh_key_ids
 
     # The URI of a script to execute on the server after it has been provisioned. This may be
@@ -88,7 +88,7 @@ def initialize(package, client = nil)
     def verify
       product_order = hardware_order
       product_order = yield product_order if block_given?
-      softlayer_client["Product_Order"].verifyOrder(product_order)
+      softlayer_client[:Product_Order].verifyOrder(product_order)
     end
 
     ##
@@ -106,7 +106,7 @@ def verify
     def place_order!
       product_order = hardware_order
       product_order = yield product_order if block_given?
-      softlayer_client["Product_Order"].placeOrder(product_order)
+      softlayer_client[:Product_Order].placeOrder(product_order)
     end
 
     protected

lib/softlayer/Client.rb

@@ -32,7 +32,7 @@ class Client
 
     # A string passsed as the value for the User-Agent header when requests are sent to SoftLayer API.
     attr_accessor :user_agent
-    
+
     # An integer value (in seconds). The number of seconds to wait for HTTP requests to the network API
     # until they timeout. This value can be nil in which case the timeout will be the default value for
     # the library handling network communication (often 30 seconds)
@@ -84,8 +84,10 @@ def initialize(options = {})
       # and the endpoint url
       @endpoint_url = settings[:endpoint_url] || API_PUBLIC_ENDPOINT
 
+      # set the user agent to the one provided, or set it to a default one
       @user_agent = settings[:user_agent] || "softlayer_api gem/#{SoftLayer::VERSION} (Ruby #{RUBY_PLATFORM}/#{RUBY_VERSION})"
-      
+
+      # and assign a time out if the settings offer one
       @network_timeout = settings[:timeout] if settings.has_key?(:timeout)
 
       raise "A SoftLayer Client requires a username" if !@username || @username.empty?

lib/softlayer/Config.rb

@@ -72,8 +72,8 @@ def Config.globals_settings
 
 		def Config.environment_settings
 			result = {}
-			result[:username] =  ENV["SL_USERNAME"] if ENV["SL_USERNAME"]
-			result[:api_key] = ENV["SL_API_KEY"] if ENV["SL_API_KEY"]
+			result[:username] =  ENV['SL_USERNAME'] if ENV['SL_USERNAME']
+			result[:api_key] = ENV['SL_API_KEY'] if ENV['SL_API_KEY']
 			result
 		end
 
@@ -89,7 +89,7 @@ def Config.file_settings(*additional_files)
 			search_path.each do |file_path|
 				if File.readable? file_path
 					config = ConfigParser.new file_path
-					softlayer_section = config["softlayer"]
+					softlayer_section = config['softlayer']
 
 					if softlayer_section
 						result[:username] = softlayer_section['username'] if softlayer_section['username']