softlayer_api 2.0.1 → 2.1.0

data/lib/softlayer/ObjectMaskParser.rb

@@ -0,0 +1,157 @@
+#
+# 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 "softlayer/ObjectMaskTokenizer"
+require "softlayer/ObjectMaskProperty"
+
+module SoftLayer
+  class ObjectMaskParserError < RuntimeError
+  end
+
+  #
+  # A parser that can examine and validate SoftLayer Object Mask strings
+  #
+  # The Object Mask Parser parses Object Mask Strings into ObjectMaskProperty
+  # structures.
+  #
+  # The Object Mask parser allows the Gem to merge Object Mask Strings
+  # to avoid errors from the SoftLayer API server about duplicate properties being
+  # provided when the same property is provided in different Object Masks
+  #
+  class ObjectMaskParser
+    attr_reader :stack
+
+    def initialize()
+      @stack = []
+    end
+
+    def parse(mask_string)
+      @tokenizer = ObjectMaskTokenizer.new(mask_string)
+
+      token = @tokenizer.current_token
+      if token.type == :identifier
+        property = parse_property(@tokenizer)
+      elsif token.type == :property_set_start
+        property_set = parse_property_set(@tokenizer)
+      else
+        raise ObjectMaskParserError, "A valid Object mask is a 'mask' or 'filterMask' root property, or a property set containing root properties" + ObjectMaskToken.error_for_unexpected_token(token)
+      end
+
+      recognize_token(@tokenizer, :eos, "Extraneous text after object mask: ")
+
+      if property && (property.name != "mask" && propertyName != "filterMask")
+        raise ObjectMaskParserError, "Object Mask must begin with a 'mask' or 'filterMask' root property"
+      end
+
+      if property_set && property_set.find { |subproperty| subproperty.name != 'mask' && subproperty.name != 'filterMask' }
+        raise ObjectMaskParserError, "A root property set must contain only 'mask' or 'filterMask' root properties"
+      end
+
+      property || property_set
+    end
+
+    def parse_property_set(tokenizer)
+      token = recognize_token(tokenizer, :property_set_start, "Expected '[': ")
+      property_sequence = parse_property_sequence(tokenizer)
+      token = recognize_token(tokenizer, :property_set_end, "Expected ']': ")
+      property_sequence
+    end
+
+    def parse_property_sequence(tokenizer)
+      first_property = parse_property(tokenizer)
+
+      other_children = []
+      token = tokenizer.current_token
+      if(token.type.equal?(:property_set_separator))
+        # skip the separator
+        tokenizer.next_token
+
+        # find another property
+        other_children = parse_property_sequence(tokenizer)
+      end
+
+      return other_children.unshift(first_property)
+    end
+
+    def parse_property (tokenizer)
+      property_name = nil
+      property_type = nil
+      property_children = nil
+
+      property_name = parse_property_name(tokenizer)
+
+      # look for a property type
+      property_type = nil
+      token = tokenizer.current_token
+      if(token.type.equal?(:property_type_start))
+        property_type = parse_property_type(tokenizer)
+      end
+
+      token = tokenizer.current_token
+      if(token.type.equal?(:property_child_separator))
+        property_children = [ parse_property_child(tokenizer) ]
+      elsif (token.type.equal?(:property_set_start))
+        property_children = parse_property_set(tokenizer)
+      end
+
+      new_property = ObjectMaskProperty.new(property_name, property_type)
+      new_property.add_children(property_children) if property_children
+
+      return new_property
+    end
+
+    def parse_property_child(tokenizer)
+      token = recognize_token(tokenizer, :property_child_separator, "Expected a '.': ")
+      parse_property(tokenizer)
+    end
+
+    def parse_property_name(tokenizer)
+      token = recognize_token(tokenizer, :identifier, "Expected a valid property type: ") { |token| token.valid_property_name? }
+      return token.value
+    end
+
+    def parse_property_type(tokenizer)
+      token = recognize_token(tokenizer, :property_type_start, "Expected '(': ")
+      property_type = parse_property_type_name(tokenizer)
+      token = recognize_token(tokenizer, :property_type_end, "Expected ')': ")
+      return property_type
+    end
+
+    def parse_property_type_name(tokenizer)
+      token = recognize_token(tokenizer, :identifier, "Expected a valid property type: ") { |token| token.valid_property_type? }
+      return token.value
+    end
+
+    def recognize_token(tokenizer, expected_type, error_string, &predicate)
+      token = tokenizer.current_token
+      if token.type.equal?(expected_type) && (!predicate || predicate.call(token))
+        tokenizer.next_token
+      else
+        raise ObjectMaskParserError, error_string + ObjectMaskToken.error_for_unexpected_token(token)
+        token = nil;
+      end
+
+      return token
+    end
+
+  end
+end # Module SoftLaye

data/lib/softlayer/ObjectMaskProperty.rb

@@ -0,0 +1,83 @@
+#
+# 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
+  #
+  # A class representing a SoftLayer Object's property as represented
+  # in an Object Mask.
+  #
+  # The Object Mask Parser parses Object Mask Strings into ObjectMaskProperty
+  # structures.
+  #
+  # Another useful property ObjectMaskProperty structures is that they can
+  # can merge with compatible structures to create a new structure which
+  # incorporates the properties of both, but in a streamlined construct
+  #
+  class ObjectMaskProperty
+    attr_reader :name, :type
+    attr_reader :children
+
+    def initialize(name, type = nil)
+      @name = name
+      @type = type
+      @children = []
+    end
+
+    def to_s
+      full_name = @name
+
+      if @type && !@type.empty?
+        full_name += "(#{@type})"
+      end
+
+      if @children.count == 1
+        full_name + ".#{@children[0].to_s}"
+      elsif @children.count > 1
+        full_name + "[#{@children.collect { |child| child.to_s }.join(',')}]"
+      else
+        full_name
+      end
+    end
+
+    def can_merge_with? (other_property)
+      (self.name == other_property.name) && (self.type == other_property.type)
+    end
+
+    def add_child(new_child)
+      mergeable_child = @children.find { |existing_child| existing_child.can_merge_with? new_child }
+      if mergeable_child
+        mergeable_child.merge new_child
+      else
+        @children.push new_child
+      end
+    end
+
+    def add_children(new_children)
+      new_children.each { |new_child| add_child(new_child) }
+    end
+
+    # DANGER: assumes you've already checked can_merge_with? before calling this routine!
+    def merge(other_property)
+      add_children other_property.children
+    end
+  end
+end # module softlayer

data/lib/softlayer/ObjectMaskToken.rb

@@ -0,0 +1,107 @@
+#
+# 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
+  #
+  # This class is an implementation detail of the Object Mask Parser
+  # It represents a single semantic token as parsed out of an
+  # Object Mask String
+  #
+  # The class also generates error messages that the parser can use
+  # when it encounters an unexpected token
+  #
+  class ObjectMaskToken
+    attr_reader :type
+    attr_reader :value
+
+    KnownTokenTypes = [
+      :invalid_token,
+      :eos,             # end of string
+      :identifier,
+      :property_set_start,
+      :property_set_separator,
+      :property_set_end,
+      :property_type_start,
+      :property_type_end,
+      :property_child_separator,
+    ]
+
+    def initialize(token_type, token_value = nil)
+      @type = token_type
+      @value = token_value
+    end
+
+    def inspect
+      "<#{@type.inspect}, #{@value.inspect}>"
+    end
+
+    def eql?(other_token)
+      @type.eql?(other_token.type) && @value.eql?(other_token.value)
+    end
+
+    def invalid?
+      return @type = :invalid_token
+    end
+
+    def end_of_string?
+      return @type == :eos
+    end
+
+    def mask_root_marker?
+      return @type == :identifier && (@value == "mask" || @value == "filterMask")
+    end
+
+    def valid_property_name?
+      return @type == :identifier && @value.match(/\A[a-z][a-z0-9]*\z/i)
+    end
+
+    def valid_property_type?
+      return @type == :identifier && @value.match(/\A[a-z][a-z0-9]*(_[a-z][a-z0-9]*)*\z/i)
+    end
+
+    def self.error_for_unexpected_token(token)
+      case token.type
+       when :invalid_token
+         "Unrecognized token '#{token.value}'"
+       when :eos
+         "Unexpected end of string"
+       when :identifier
+         "Unexpected identifier '#{token.value}'"
+       when :property_set_start
+         "Unexpected '['"
+       when :property_set_separator
+         "Unexpected ','"
+       when :property_set_end
+         "Unexpected ']'"
+       when :property_type_start
+         "Unexpected '('"
+       when :property_type_end
+         "Unexpected ')'"
+       when :property_child_separator
+         "Unexpected '.'"
+       else
+         "Unexpected value (invalid token type)"
+     end
+    end
+  end
+
+end # module SoftLayer

data/lib/softlayer/ObjectMaskTokenizer.rb

@@ -0,0 +1,88 @@
+#
+# 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 'softlayer/ObjectMaskToken'
+require 'strscan'
+
+module SoftLayer
+  #
+  # This class is an implementation detail of the ObjectMaskParser
+  #
+  # It takes an Object Mask String and breaks it down
+  # into ObjectMaskToken instances.
+  #
+  class ObjectMaskTokenizer
+    ObjectMask_Token_Specs = [
+      [/\[/, :property_set_start],
+      [/\,/, :property_set_separator],
+      [/\]/, :property_set_end],
+      [/\(/, :property_type_start],
+      [/\)/, :property_type_end],
+      [/\./, :property_child_separator],
+      [/[a-z][a-z0-9_]*/i, :identifier]
+    ]
+
+    def initialize(mask_string)
+      @mask_string = mask_string.clone
+      @scanner = StringScanner.new(@mask_string)
+      @current_token = nil
+    end
+
+    def more_tokens?
+      return @current_token == nil || !@current_token.end_of_string?
+    end
+
+    def current_token
+      @current_token = next_token if !@current_token
+      @current_token
+    end
+
+    def next_token
+      # if we're at the end of the string, we keep returning the
+      # EOS token
+      if more_tokens? then
+
+        if !@scanner.eos?
+          # skip whitespace
+          @scanner.skip(/\s+/)
+
+          # search through the token specs to find which (if any) matches
+          token_spec = ObjectMask_Token_Specs.find() do |token_spec|
+            @scanner.check(token_spec[0])
+          end
+
+          # if a good token spec was found, set the current token to the one found
+          if token_spec
+            @current_token = ObjectMaskToken.new(token_spec.last, @scanner.scan(token_spec[0]))
+          else
+            @current_token = ObjectMaskToken.new(:invalid_token, @scanner.rest)
+            @scanner.terminate
+          end
+        else
+          @current_token = ObjectMaskToken.new(:eos)
+        end
+      end
+
+      @current_token
+    end
+  end
+end # module SoftLayer

data/lib/softlayer/ProductItemCategory.rb

@@ -0,0 +1,137 @@
+#
+# 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
+  # This struct represents a configuration option that can be included in
+  # a product order.  Strictly speaking the only information required for
+  # the product order is the price_id, the rest of the information is provided
+  # to make the object friendly to humans who may be searching for the
+  # meaning of a given price_id.
+  ProductConfigurationOption = Struct.new(:price_id, :description, :capacity, :units, :setupFee, :laborFee, :oneTimeFee, :recurringFee, :hourlyRecurringFee) do
+
+    # Is it evil, or just incongruous to give methods to a struct?
+
+    # returns true if the configurtion option has no fees associated with it.
+    def free?
+      self.setupFee == 0 && self.laborFee == 0 && self.oneTimeFee == 0 && self.recurringFee == 0 && self.hourlyRecurringFee == 0
+    end
+  end
+
+  # The goal of this class is to make it easy for scripts (and scripters) to
+  # discover what product configuration options exist that can be added to a
+  # product order.
+  #
+  # Instances of this class are created by and discovered in the context
+  # of a ProductPackage object. There should not be a need to create instances
+  # of this class directly.
+  #
+  # This class rougly represents entities in the +SoftLayer_Product_Item_Category+
+  # service.
+  class ProductItemCategory < ModelBase
+    include ::SoftLayer::DynamicAttribute
+    
+    ##
+    # :attr_reader:
+    # The categoryCode is a primary identifier for a particular
+    # category.  It is a string like 'os' or 'ram'
+    sl_attr :categoryCode
+    
+    ##
+    # :attr_reader:
+    # The name of a category is a friendly, readable string
+    sl_attr :name
+
+    sl_dynamic_attr :configuration_options do |config_opts|
+      config_opts.should_update? do
+        # only retrieved once per instance
+        @configuration_options == nil
+      end
+
+      config_opts.to_update do
+        # This method assumes that the group and price item data was sent in
+        # as part of the +network_hash+ used to initialize this object (as is done)
+        # by the ProductPackage class. That class, in turn, gets its information
+        # from SoftLayer_Product_Package::getCategories which does some complex
+        # work on the back end to ensure the prices returned are correct.
+        #
+        # If this object was created in any other way, the configuration
+        # options might be incorrect. So Caveat Emptor.
+        #
+        # Options are divided into groups (for convenience in the
+        # web UI), but this code collapses the groups.
+        self['groups'].collect do |group|
+          group['prices'].sort{|lhs,rhs| lhs['sort'] <=> rhs['sort']}.collect do |price_item|
+            ProductConfigurationOption.new(
+              price_item['id'],
+              price_item['item']['description'],
+              price_item['item']['capacity'],
+              price_item['item']['units'],
+              price_item['setupFee'] ? price_item['setupFee'].to_f : 0.0,
+              price_item['laborFee'] ? price_item['laborFee'].to_f : 0.0,
+              price_item['oneTimeFee'] ? price_item['oneTimeFee'].to_f : 0.0,
+              price_item['recurringFee'] ? price_item['recurringFee'].to_f : 0.0,
+              price_item['hourlyRecurringFee'] ? price_item['hourlyRecurringFee'].to_f : 0.0
+              )
+          end
+        end.flatten # flatten out the individual group arrays.
+      end
+    end
+
+    def service
+      softlayer_client["SoftLayer_Product_Item_Category"].object_with_id(self.id)
+    end
+
+    ##
+    # If the category has a single option (regardless of fees) this method will return
+    # that option.  If the category has more than one option, this method will
+    # return the first that it finds with no fees associated with it.
+    #
+    # If there are multiple options with no fees, it simply returns the first it finds
+    #
+    # Note that the option found may NOT be the same default option that is given
+    # in the web-based ordering system.
+    #
+    # If there are multiple options, and all of them have associated fees, then this method
+    # **will** return nil.
+    #
+    def default_option
+      if configuration_options.count == 1
+        configuration_options.first
+      else
+        configuration_options.find { |option| option.free? }
+      end
+    end
+
+    # The ProductItemCategory class augments the base initialization by accepting
+    # a boolean variable, +is_required+, which (when true) indicates that this category
+    # is required for orders against the package that created it.
+    def initialize(softlayer_client, network_hash, is_required)
+      super(softlayer_client, network_hash)
+      @is_required = is_required
+    end
+
+    # Returns true if this category is required in its package
+    def required?()
+      return @is_required
+    end
+  end
+end