softlayer_api 2.0.1 → 2.1.0

data/lib/softlayer/ProductPackage.rb

@@ -0,0 +1,196 @@
+#
+# 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.
+#
+
+module SoftLayer
+  ##
+  # Each SoftLayer ProductPackage provides information about ordering a product
+  # or service from SoftLayer.
+  #
+  # === Product Item Categories
+  # A important companion to Product Packages are ProductItemCategories.
+  # Each ProductItemCategory represents a set of options that you may choose from when
+  # configuring an attribute of the product or service you are ordering.
+  #
+  # ProductItemCategories are identified by +categoryCode+. Examples of category codes
+  # include 'os', 'ram', and 'port_speed'.
+  #
+  # For example, in a package for ordering a server, the 'os' ProductItemCategory contains
+  # the available choices for operating systems that may be provisioned on the server.
+  #
+  # When you construct an order based on that package, you will make one selection from
+  # the 'os' category and put it into the order.
+  #
+  # === Package Configuration
+  # A package also has a Configuration. A Configuration specifies which
+  # Categories are valid in an order and, more importantly, which Categories
+  # are **required** in any order that uses the ProductPackage.
+  #
+  # When constructing an order, you **must** provide an option for each of the Categories
+  # that the Configuration marks as required (and you must supply a value even if the
+  # Category only has one choice)
+  #
+  class ProductPackage < ModelBase
+    include ::SoftLayer::DynamicAttribute
+
+    ##
+    # A friendly, readable name for the package
+    sl_attr :name
+
+    ##
+    # The list of locations where this product package is available.
+    sl_attr :availableLocations
+
+    ##
+    # The set of product categories needed to make an order for this product package.
+    #
+    sl_dynamic_attr :configuration do |resource|
+      resource.should_update? do
+        # only retrieved once per instance
+        @configuration == nil
+      end
+
+      resource.to_update do
+        #
+        # We call +SoftLayer_Product_Package+ to get the configuration for this package.
+        #
+        # Unfortunately, even though this call includes +SoftLayer_Product_Item_Category+ entities, it does not have the context
+        # needed to find the active price items for that category.
+        #
+        # Instead, we make a second call, this time to +SoftLayer_Product_Package::getCategories+. That method incorporates a complex
+        # filtering mechanism on the server side to give us a list of the categories, groups, and prices that are valid for the current
+        # account at the current time. We construct the ProductItemCategory objects from the results we get back.
+        #
+        configuration_data = softlayer_client['Product_Package'].object_with_id(self.id).object_mask("mask[isRequired,itemCategory.categoryCode]").getConfiguration()
+
+        # We sort of invert the information and create a map from category codes to a boolean representing
+        # whether or not they are required.
+        required_by_category_code = configuration_data.inject({}) do |required_by_category_code, config_category|
+          required_by_category_code[config_category['itemCategory']['categoryCode']] = (config_category['isRequired'] != 0)
+          required_by_category_code
+        end
+
+        # This call to getCategories is the one that does lots of fancy back-end filtering for us
+        categories_data = softlayer_client['Product_Package'].object_with_id(self.id).getCategories()
+
+        # Run though the categories and for each one that's in our config, create a SoftLayer::ProductItemCategory object.
+        # Conveniently the +keys+ of the required_by_category_code gives us a list of the category codes in the configuration
+        config_categories = required_by_category_code.keys
+        categories_data.collect do |category_data|
+          if config_categories.include? category_data['categoryCode']
+            SoftLayer::ProductItemCategory.new(softlayer_client, category_data, required_by_category_code[category_data['categoryCode']])
+          else
+            nil
+          end
+        end.compact
+      end
+    end
+
+    ##
+    # Returns an array of the required categories in this package
+    def required_categories
+      configuration.select { |category| category.required? }
+    end
+
+    ##
+    # Returns the product category with the given category code (or nil if one cannot be found)
+    def category(category_code)
+      configuration.find { |category| category.categoryCode == 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"]
+    end
+
+    def service
+      softlayer_client['Product_Package'].object_with_id(self.id)
+    end
+
+    ##
+    # Requests a list (array) of ProductPackages whose key names match the
+    # one passed in.
+    #
+    def self.packages_with_key_name(key_name, 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
+      
+      filter = SoftLayer::ObjectFilter.build('type.keyName') { is(key_name) }
+      filtered_service = softlayer_client['Product_Package'].object_filter(filter).object_mask(self.default_object_mask('mask'))
+      packages_data = filtered_service.getAllObjects
+      packages_data.collect { |package_data| ProductPackage.new(softlayer_client, package_data) }
+    end
+
+    ##
+    # Requests a list (array) of ProductPackages whose key names match the
+    # one passed in.
+    #
+    def self.package_with_id(package_id, 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
+      
+      package_data = softlayer_client['Product_Package'].object_with_id(package_id).object_mask(self.default_object_mask('mask')).getObject
+      ProductPackage.new(softlayer_client, package_data)
+    end
+
+    ##
+    # Returns the ProductPackage of the package used to order virtual servers
+    # At the time of this writing, the code assumes this package is unique
+    #
+    # 'VIRTUAL_SERVER_INSTANCE' is a "well known" constant for this purpose
+    def self.virtual_server_package(client = nil)
+      packages_with_key_name('VIRTUAL_SERVER_INSTANCE', client).first
+    end
+
+    ##
+    # Returns the ProductPackage of the package used to order Bare Metal Servers
+    # with simplified configuration options.
+    #
+    # At the time of this writing, the code assumes this package is unique
+    #
+    # 'BARE_METAL_CORE' is a "well known" constant for this purpose
+    def self.bare_metal_instance_package(client = nil)
+      packages_with_key_name('BARE_METAL_CORE', client).first
+    end
+
+    ##
+    # Returns an array of ProductPackages, each of which can be used
+    # as the foundation to order a bare metal server.
+    #
+    # 'BARE_METAL_CPU' is a "well known" constant for this purpose
+    def self.bare_metal_server_packages(client = nil)
+      packages_with_key_name('BARE_METAL_CPU', client)
+    end
+
+    protected
+
+    def self.default_object_mask(root)
+      "#{root}[id,name,description,availableLocations.location]"
+    end
+  end
+end # SoftLayer

data/lib/softlayer/Server.rb

@@ -0,0 +1,245 @@
+#
+# 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.
+#
+
+module SoftLayer
+  # Server is the base class for VirtualServer and BareMetalServer.
+  # It implements some functionality common to both those classes.
+  #
+  # Server is an abstract class and you should not create them
+  # directly.
+  #
+  # While VirtualServer and BareMetalServer each have analogs
+  # in the SoftLayer API, those analogs do not share a direct
+  # ancestry.  As a result there is no SoftLayer API analog
+  # to this class.
+  class Server  < SoftLayer::ModelBase
+
+    ##
+    # :attr_reader:
+    # The host name SoftLayer has stored for the server
+    sl_attr :hostname
+
+    ##
+    # :attr_reader:
+    # The domain name SoftLayer has stored for the server
+    sl_attr :domain
+
+    ##
+    # :attr_reader:
+    # A convenience attribute that combines the hostname and domain name
+    sl_attr :fullyQualifiedDomainName
+
+    ##
+    # :attr_reader:
+    # The data center where the server is located
+    sl_attr :datacenter
+
+    ##
+    # :attr_reader:
+    # The IP address of the primary public interface for the server
+    sl_attr :primary_public_ip, "primaryIpAddress"
+
+    ##
+    # :attr_reader:
+    # The IP address of the primary private interface for the server
+    sl_attr :primary_private_ip, "primaryBackendIpAddress"
+
+    ##
+    # :attr_reader:
+    # Notes about these server (for use by the customer)
+    sl_attr :notes
+
+    ##
+    # Construct a server from the given client using the network data found in +network_hash+
+    #
+    # Most users should not have to call this method directly. Instead you should access the
+    # servers property of an Account object, or use methods like BareMetalServer#find_servers
+    # or VirtualServer#find_servers
+    #
+    def initialize(softlayer_client, network_hash)
+      if self.class == Server
+        raise RuntimeError, "The Server class is an abstract base class and should not be instantiated directly"
+      else
+        super
+      end
+    end
+
+    ##
+    # Make an API request to SoftLayer and return the latest properties hash
+    # for this object.
+    def softlayer_properties(object_mask = nil)
+      my_service = self.service
+
+      if(object_mask)
+        my_service = my_service.object_mask(object_mask)
+      else
+        my_service = my_service.object_mask(self.class.default_object_mask.to_sl_object_mask)
+      end
+
+      my_service.getObject()
+    end
+
+    ##
+    # Change the notes of the server
+    # raises ArgumentError if you pass nil as the notes
+    def notes=(new_notes)
+      raise ArgumentError.new("The new notes cannot be nil") unless new_notes
+
+      edit_template = {
+        "notes" => new_notes
+      }
+
+      self.service.editObject(edit_template)
+      self.refresh_details()
+    end
+
+    ##
+    # Change the user metadata for the server.
+    #
+    def user_metadata=(new_metadata)
+      raise ArgumentError.new("Cannot set user metadata to nil") unless new_metadata
+      self.service.setUserMetadata([new_metadata])
+      self.refresh_details()
+    end
+
+    ##
+    # Change the hostname of this server
+    # Raises an ArgumentError if the new hostname is nil or empty
+    #
+    def set_hostname!(new_hostname)
+      raise ArgumentError.new("The new hostname cannot be nil") unless new_hostname
+      raise ArgumentError.new("The new hostname cannot be empty") if new_hostname.empty?
+
+      edit_template = {
+        "hostname" => new_hostname
+      }
+
+      self.service.editObject(edit_template)
+      self.refresh_details()
+    end
+
+    ##
+    # Change the domain of this server
+    #
+    # Raises an ArgumentError if the new domain is nil or empty
+    # no further validation is done on the domain name
+    #
+    def set_domain!(new_domain)
+      raise ArgumentError.new("The new hostname cannot be nil") unless new_domain
+      raise ArgumentError.new("The new hostname cannot be empty") if new_domain.empty?
+
+      edit_template = {
+        "domain" => new_domain
+      }
+
+      self.service.editObject(edit_template)
+      self.refresh_details()
+    end
+
+    ##
+    # Change the current port speed of the server
+    #
+    # +new_speed+ is expressed Mbps and should be 0, 10, 100, or 1000.
+    # Ports have a maximum speed that will limit the actual speed set
+    # on the port.
+    #
+    # Set +public+ to +false+ in order to change the speed of the
+    # primary private network interface.
+    #
+    def change_port_speed(new_speed, public = true)
+      if public
+        self.service.setPublicNetworkInterfaceSpeed(new_speed)
+      else
+        self.service.setPrivateNetworkInterfaceSpeed(new_speed)
+      end
+
+      self.refresh_details()
+      self
+    end
+
+    ##
+    # Begins an OS reload on this server.
+    #
+    # The OS reload can wipe out the data on your server so this method uses a
+    # confirmation mechanism built into the underlying SoftLayer API. If you
+    # call this method once without a token, it will not actually start the
+    # reload. Instead it will return a token to you. That token is good for
+    # 10 minutes. If you call this method again and pass that token **then**
+    # the OS reload will actually begin.
+    #
+    # If you wish to force the OS Reload and bypass the token safety mechanism
+    # pass the token 'FORCE' as the first parameter. If you do so
+    # the reload will proceed immediately.
+    #
+    def reload_os!(token = '', provisioning_script_uri = nil, ssh_keys = nil)
+      configuration = {}
+
+      configuration['customProvisionScriptUri'] = provisioning_script_uri if provisioning_script_uri
+      configuration['sshKeyIds'] = ssh_keys if ssh_keys
+
+      self.service.reloadOperatingSystem(token, configuration)
+    end
+
+    def to_s
+      result = super
+      if respond_to?(:hostname) then
+        result.sub!('>', ", #{hostname}>")
+      end
+      result
+    end
+
+    protected
+
+    # returns the default object mask for all servers
+    # structured as a hash so that the classes BareMetalServer
+    # and VirtualServer can use hash construction techniques to
+    # specialize the mask for their use.
+    def self.default_object_mask
+      { "mask" => [
+          'id',
+          'globalIdentifier',
+          'notes',
+          'hostname',
+          'domain',
+          'fullyQualifiedDomainName',
+          'datacenter',
+          'primaryIpAddress',
+          'primaryBackendIpAddress',
+          { 'operatingSystem' => {
+              'softwareLicense.softwareDescription' => ['manufacturer', 'name', 'version','referenceCode'],
+              'passwords' => ['username','password']
+            }
+          },
+          'privateNetworkOnlyFlag',
+          'userData',
+          'networkComponents.primarySubnet[id, netmask, broadcastAddress, networkIdentifier, gateway]',
+          'billingItem[id,recurringFee]',
+          'hourlyBillingFlag',
+          'tagReferences[id,tag[name,id]]',
+          'networkVlans[id,vlanNumber,networkSpace]',
+          'postInstallScriptUri'
+        ]
+      }
+    end
+
+  end # class Server
+end # module SoftLayer

data/lib/softlayer/Service.rb

@@ -1,4 +1,3 @@
-#
 # Copyright (c) 2014 SoftLayer Technologies, Inc. All rights reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -51,7 +50,6 @@ class XMLRPC::Client
 end
 
 module SoftLayer
-
   # = SoftLayer API Service
   #
   # Instances of this class are the runtime representation of
@@ -87,7 +85,7 @@ module SoftLayer
     attr_reader :service_name
     attr_reader :client
 
-    def initialize(service_name, options = {})
+    def initialize (service_name, options = {})
       raise ArgumentError,"Please provide a service name" if service_name.nil? || service_name.empty?
 
       # remember the service name
@@ -137,6 +135,13 @@ using either client.service_named('<service_name_here>') or client['<service_nam
       @client.service_named(service_name)
     end
 
+    # Added here so that the interface of this class matches that
+    # of APIParameterFilter.  In APIParameterFilter the target is
+    # a service.  In a service, the target is itself.
+    def target
+      return self
+    end
+
     # Use this as part of a method call chain to identify a particular
     # object as the target of the request. The parameter is the SoftLayer
     # object identifier you are interested in. For example, this call
@@ -165,7 +170,7 @@ using either client.service_named('<service_name_here>') or client['<service_nam
     # Use this as part of a method call chain to reduce the number
     # of results returned from the server. For example, if the server has a list
     # of 100 entities and you only want 5 of them, you can get the first five
-    # by using result_limit(0,5).  Then for the next 5 you would use
+    # by using result_limit(0,5). Then for the next 5 you would use
     # result_limit(5,5), then result_limit(10,5) etc.
     def result_limit(offset, limit)
       proxy = APIParameterFilter.new(self)
@@ -234,11 +239,9 @@ using either client.service_named('<service_name_here>') or client['<service_nam
       end
 
       # Object masks go into the headers too.
-      if parameters && parameters.server_object_mask && parameters.server_object_mask.count != 0
+      if parameters && parameters.server_object_mask
         object_mask = parameters.server_object_mask
-        object_mask_string = object_mask.count == 1 ? object_mask[0] : "[#{object_mask.join(',')}]"
-
-        additional_headers.merge!("SoftLayer_ObjectMask" => { "mask" => object_mask_string }) unless object_mask_string.empty?
+        additional_headers.merge!("SoftLayer_ObjectMask" => { "mask" => object_mask }) unless object_mask.empty?
       end
 
       # Result limits go into the headers
@@ -284,7 +287,7 @@ using either client.service_named('<service_name_here>') or client['<service_nam
     # If this is not defined for Service, then when you print a service object
     # the code will try to convert it to an array and end up calling method_missing
     #
-    # We define this here to prevent odd calls to the Softlayer API
+    # We define this here to prevent odd calls to the SoftLayer API
     def to_ary
       nil
     end