softlayer_api 2.0.1 → 2.1.0

data/lib/softlayer/Config.rb

@@ -28,7 +28,7 @@ module SoftLayer
 			result = {}
 			result[:username] =  $SL_API_USERNAME if $SL_API_USERNAME
 			result[:api_key] = $SL_API_KEY if $SL_API_KEY
-			result[:endpoint_url] = $SL_API_BASE_URL ? $SL_API_BASE_URL : API_PUBLIC_ENDPOINT
+			result[:endpoint_url] = $SL_API_BASE_URL || API_PUBLIC_ENDPOINT
 			result
 		end
 
@@ -39,7 +39,7 @@ module SoftLayer
 			result
 		end
 
-		FILE_LOCATIONS = ['/etc/softlayer.conf', '~/.softlayer']
+		FILE_LOCATIONS = ['/etc/softlayer.conf', '~/.softlayer', './.softlayer']
 
 		def Config.file_settings(*additional_files)
 			result = {}
@@ -49,7 +49,6 @@ module SoftLayer
 			search_path = search_path.map { |file_path| File.expand_path(file_path) }
 
 			search_path.each do |file_path|
-
 				if File.readable? file_path
 					config = ConfigParser.new file_path
 					softlayer_section = config["softlayer"]

data/lib/softlayer/DynamicAttribute.rb

@@ -0,0 +1,170 @@
+#
+# 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 module is inteneded to be used by classes in the SoftLayer
+  # object model. It creates a small DSL for creating attributes
+  # that update themselves dynamically (usually by making requests
+  # to the SoftLayer API)
+  #
+  # +sl_dynamic_attr+ is an implementation of a memoization scheme
+  # The module creates a getter which is implemented in terms of a
+  # predicate (identifying whether or not the attribute needs to be updated) and
+  # an update routine
+  #
+  # When the getter is called, it checks the predicate routine to see if
+  # the attribute needs to be updated. If it doesn't, then the getter simply
+  # returns the cached value for the attribute. If the attribute does need
+  # to be updated, the getter calls the update routine to get a new value
+  # and caches that value off before returning it to the caller.
+  #
+  # Declaring a attribute adds three methods to a class and
+  # a corresponding instance variable in instances of the class
+  # All three are based on the name of the attribute:
+  #
+  # * The getter simply has the same name as the attribute
+  # * The predicate routine is called +should_update_<attribute name>?+
+  # * The updating routine is called +update_<attribute name>!+
+  #
+  # The getter can also be called with a boolean argument. If that
+  # argument is true, the getter will force the attribute to be updated
+  # without consulting the +should_update?+ predicate
+  #
+  # When a attribute is defined, the definition takes a block.
+  # Inside the block there is a small DSL that allows you to
+  # set the behavior of the +should_update?+ predicate and the +update_!+
+  # routine.
+  #
+  # A attribute definition might look something like this:
+  #
+  #    sl_dynamic_attr :lollipop do |lollipop|
+  #      lollipop.should_update? do
+  #        self.lollipop_supply_is_low?
+  #      end
+  #
+  #      lollipop.to_update do
+  #        candy_store.buy_lollipops(bakers_dozen)
+  #      end
+  #    end
+  #
+  module DynamicAttribute
+
+    # The DynamicAttributeDefinition inner class is to collect and
+    # store information about how and when a sl_dynamic_attr
+    # should be updated. This class is an implementation detail
+    # of dynamic attributes and is not intended to be useful
+    # outside of that context.
+    class DynamicAttributeDefinition
+      # the name of the attribute this definition is for
+      attr_reader :attribute_name
+
+      # The block to call in order to update the attribute. The
+      # return value of this block should be the new value of the
+      # attribute.
+      attr_reader :update_block
+
+      # The block to call to see if the attribute needs to be updated.
+      attr_reader :should_update_block
+
+      def initialize(attribute_name)
+        raise ArgumentError if attribute_name.nil?
+        raise ArgumentError if attribute_name.to_s.empty?
+
+        @attribute_name = attribute_name;
+        @update_block = Proc.new { nil; };
+        @should_update_block = Proc.new { true; }
+      end
+
+      # This method is used to provide behavior for the
+      # should_update_ predicate for the attribute
+      def should_update? (&block)
+        @should_update_block = block
+      end
+
+      # This method is used to provide the behavior for
+      # the update_! method for the attribute.
+      def to_update (&block)
+        @update_block = block
+      end
+    end
+
+    module ClassMethods
+      # sl_dynamic_attr declares a new dynamic softlayer attribute and accepts
+      # a block in which the should_update? and to_update methods for the
+      # attribute are established.
+      def sl_dynamic_attr (attribute_name, &block)
+        attribute_definition = DynamicAttributeDefinition.new(attribute_name)
+
+        # allow the block to update the attribute definition
+        yield attribute_definition if block_given?
+
+        # store off the attribute definition where we can find it later
+        @attribute_definitions ||= {};
+        @attribute_definitions[attribute_name] = attribute_definition;
+
+        # define a method called "update_<attribute_name>!" which calls the update block
+        # stored in the attribute definition
+        update_symbol = "update_#{attribute_name}!".to_sym
+        define_method(update_symbol, &attribute_definition.update_block)
+
+        # define a method called "should_update_<attribute_name>?" which calls the
+        # should update block stored in the attribute definition
+        should_update_symbol = "should_update_#{attribute_name}?".to_sym
+        define_method(should_update_symbol, &attribute_definition.should_update_block)
+
+        # define an instance method of the class this is being
+        # called on which will get the value of the attribute.
+        #
+        # The getter will take one argument "force_update" which
+        # is treated as boolean value. If true, then the getter will
+        # force the attribute to update (by using its "to_update") block.
+        #
+        # If the force variable is false, or not given, then the
+        # getter will call the "should update" block to find out if the
+        # attribute needs to be updated.
+        #
+        getter_name = attribute_name.to_sym
+        value_instance_variable = "@#{attribute_name}".to_sym
+
+        define_method(getter_name) do |*args|
+          force_update = args[0] || false
+
+          if force_update || __send__(should_update_symbol)
+            instance_variable_set(value_instance_variable, __send__(update_symbol))
+          end
+
+          instance_variable_get(value_instance_variable)
+        end
+      end
+
+      def sl_dynamic_attr_definition(attribute_name)
+        @attribute_definitions[attribute_name]
+      end
+    end
+
+    def self.included(included_in)
+      included_in.extend(ClassMethods)
+    end
+  end
+end

data/lib/softlayer/ModelBase.rb

@@ -0,0 +1,141 @@
+#
+# 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
+  ##
+  # The SoftLayer Gem defines an Object Hierarchy representing entities in
+  # an account's SoftLayer environment. This class is the base object class
+  # for objects in that hierarchy
+  #
+  # The SoftLayer API represents entities as a hash of properties. This class
+  # stores that hash and allows the use of subscripting to access those properties
+  # directly.
+  #
+  # The class also has a model for making network requests that will refresh
+  # the stored hash so that it reflects the most up-to-date information about
+  # an entity from the server. Subclasses should override softlayer_properties
+  # to retrieve information from the server. Client code should call
+  # refresh_details to ask an object to update itself.
+  #
+  class ModelBase
+    # The client environment that this model object belongs to
+    attr_reader :softlayer_client
+
+    ##
+    # :attr_reader: id
+    # The unique identifier of this object within its API service
+
+    # Construct a new model object in the environment of the given client and
+    # with the given hash of network data (presumably returned by the SoftLayer API)
+    def initialize(softlayer_client, network_hash)
+      raise ArgumentError, "A hash is required" if nil == network_hash
+      raise ArgumentError, "Model objects must be created in the context of a client" if nil == softlayer_client
+
+      @softlayer_client = softlayer_client
+      @softlayer_hash = network_hash
+
+      raise ArgumentError, "The hash used to construct a softlayer model object must have an id" unless has_sl_property?(:id)
+      raise ArgumentError, "id must be non-nil and non-empty" unless self[:id]
+    end
+
+    ##
+    # The service method of a Model object should return a SoftLayer Service
+    # that best represents the modeled object.  For example, a Ticket models
+    # a particular entity in the SoftLayer_Ticket service.  The particular
+    # entity is identified by its id so the Ticket class would return
+    #
+    #     softlayer_client["Ticket"].object_with_id
+    #
+    # which is a service which would allow calls to the ticket service
+    # through that particular object.
+    def service
+      raise "Abstract method service in ModelBase was called"
+    end
+
+    ##
+    # Asks a model object to reload itself from the SoftLayer API.
+    #
+    # Subclasses should not override this method, rather they should
+    # implement softlayer_properties to actually make the API request
+    # and return the new hash.
+    #
+    def refresh_details(object_mask = nil)
+      @softlayer_hash = self.softlayer_properties(object_mask)
+    end
+
+    ##
+    # Subclasses should implement this method as part of enabling the
+    # refresh_details fuctionality The implementation should make a request
+    # to the SoftLayer API and retrieve an up-to-date SoftLayer hash
+    # representation of this object. That hash should be the return value
+    # of this routine.
+    #
+    def softlayer_properties(object_mask = nil)
+      raise "Abstract method softlayer_properties in ModelBase was called"
+    end
+
+    ##
+    # Returns the value of of the given property as stored in the
+    # softlayer_hash. This gives you access to the low-level, raw
+    # properties that underly this model object.  The need for this
+    # is not uncommon, but using this method should still be done
+    # with deliberation.
+    def [](softlayer_property)
+      self.softlayer_hash[softlayer_property.to_s]
+    end
+
+    ##
+    # Returns true if the given property can be found in the softlayer hash
+    def has_sl_property?(softlayer_property)
+      softlayer_hash && softlayer_hash.has_key?(softlayer_property.to_s)
+    end
+
+    ##
+    # allows subclasses to define attributes as sl_attr
+    # sl_attr are attributes that draw their value from the
+    # low-level hash representation of the object.
+    def self.sl_attr(attribute_symbol, hash_key = nil)
+      raise "The sl_attr expects a symbol for the attribute to define" unless attribute_symbol.kind_of?(Symbol)
+      raise "The hash key used to define an attribute cannot be empty" if hash_key && hash_key.empty?
+
+      define_method(attribute_symbol.to_sym) { self[hash_key ? hash_key : attribute_symbol.to_s]}
+    end
+
+    sl_attr :id
+
+    # When printing to the console using puts, ruby will call the
+    # to_ary method trying to convert an object into an array of lines
+    # for stdio. We override to_ary to return nil for model objects
+    # so they may be printed
+    def to_ary()
+      return nil;
+    end
+
+    protected
+
+    ##
+    # The softlayer_hash stores the low-level information about an
+    # object as it was retrieved from the SoftLayer API.
+    attr_reader :softlayer_hash
+
+  end # class ModelBase
+end # module SoftLayer

data/lib/softlayer/ObjectFilter.rb

@@ -35,9 +35,13 @@ module SoftLayer
     '!~'    # Does not Contain (case sensitive)
   ]
 
-  # A class whose instances represent an Object Filter operation.
+  # A class whose instances represent an Object Filter operator and the value it is applied to.
   class ObjectFilterOperation
+
+    # The operator, should be a member of the SoftLayer::OBJECT_FILTER_OPERATORS array
     attr_reader :operator
+
+    # The operand of the operator
     attr_reader :value
 
     def initialize(operator, value)
@@ -49,71 +53,105 @@ module SoftLayer
     end
 
     def to_h
-      { 'operation' => "#{operator} #{value}"}
+      result = ObjectFilter.new
+      result['operation'] = "#{operator} #{value}"
+
+      result
     end
   end
 
-  # Routines that are valid within the block provided to a call to
-  # ObjectFilter.build.
+  # This class defines the routines that are valid within the block provided to a call to
+  # ObjectFilter.build. This allows you to create object filters like:
+  #
+  # object_filter = SoftLayer::ObjectFilter.build("hardware.memory") { is_greater_than(2) }
+  #
   class ObjectFilterBlockHandler
-    # contains wihout considering case
+    # Matches when the value is found within the field
+    # the search is not case sensitive
     def contains(value)
       ObjectFilterOperation.new('*=', value)
     end
 
-    # case insensitive begins with
+    # Matches when the value is found at the beginning of the
+    # field. This search is not case sensitive
     def begins_with(value)
       ObjectFilterOperation.new('^=', value)
     end
 
-    # case insensitive ends with
+    # Matches when the value is found at the end of the
+    # field. This search is not case sensitive
     def ends_with(value)
       ObjectFilterOperation.new('$=', value)
     end
 
-    # matches exactly (ignoring case)
+    # Matches when the value in the field is exactly equal to the
+    # given value. This is a case-sensitive match
     def is(value)
       ObjectFilterOperation.new('_=', value)
     end
 
+    # Matches is the value in the field does not exactly equal
+    # the value passed in.
     def is_not(value)
       ObjectFilterOperation.new('!=', value)
     end
 
+    # Matches when the value in the field is greater than the given value
     def is_greater_than(value)
       ObjectFilterOperation.new('>', value)
     end
 
+    # Matches when the value in the field is less than the given value
     def is_less_than(value)
       ObjectFilterOperation.new('<', value)
     end
 
+    # Matches when the value in the field is greater than or equal to the given value
     def is_greater_or_equal_to(value)
       ObjectFilterOperation.new('>=', value)
     end
 
+    # Matches when the value in the field is less than or equal to the given value
     def is_less_or_equal_to(value)
       ObjectFilterOperation.new('<=', value)
     end
 
+    # Matches when the value is found within the field
+    # the search _is_ case sensitive
     def contains_exactly(value)
       ObjectFilterOperation.new('~', value)
     end
 
+    # Matches when the value is not found within the field
+    # the search _is_ case sensitive
     def does_not_contain(value)
       ObjectFilterOperation.new('!~', value)
     end
   end
 
-  # An ObjectFilter is a hash that, when asked to provide
+  #
+  # An ObjectFilter is a tool that, when passed to the SoftLayer API
+  # allows the API server to filter, or limit the result set for a call.
+  #
+  # Constructing ObjectFilters is an art that is currently somewhat
+  # arcane. This class tries to simplify filtering for the fundamental
+  # cases, while still allowing for more complex ObjectFilters to be
+  # created.
+  #
+  # The ObjectFilter class is implemented as a hash that, when asked to provide
   # an value for an unknown key, will create a sub element
-  # at that key that is itself an object filter.  So if you
-  # start with an empty object filter and ask for <tt>object_filter["foo"]</tt>
-  # then foo will be +added+ to the object and the value of that
-  # key will be an Object Filter <tt>{ "foo" => {} }</tt>
+  # at that key which is, itself, an object filter. This allows you to build
+  # up object filters by chaining [] dereference operations.
+  #
+  # Starting empty object filter when you ask for +object_filter["foo"]+
+  # either the value at that hash location will be returned, or a new +foo+ key
+  # will be *added* to the object.  The value of that key will be an +ObjectFilter+
+  # and that +ObjectFilter+ will be returned.
   #
-  # This allows you to create object filters by chaining [] calls:
-  #     object_filter["foo"]["bar"]["baz"] = 3 yields {"foo" => { "bar" => {"baz" => 3}}}
+  # By way of an example of chaining together +[]+ calls:
+  #   object_filter["foo"]["bar"]["baz"] = 3
+  # yields an object filter like this:
+  #   {"foo" => { "bar" => {"baz" => 3}}}
   #
   class ObjectFilter < Hash
     # The default initialize for a hash is overridden
@@ -146,7 +184,7 @@ module SoftLayer
       end
 
       # if there is a block, then the query will come from
-      # calling the block.  We warn in debug mode if you override a
+      # calling the block. We warn in debug mode if you override a
       # query that was passed directly with the value from a block.
       if block
         $stderr.puts "The query from the block passed to ObjectFilter:build will override the query passed as a parameter" if $DEBUG && query
@@ -154,7 +192,7 @@ module SoftLayer
         query = block_handler.instance_eval(&block)
       end
 
-      # If we have a query, we assign it's value to the last key
+      # If we have a query, we assign its value to the last key
       # otherwise, we build an emtpy filter at the bottom
       if query
         case
@@ -176,9 +214,9 @@ module SoftLayer
       result
     end
 
-    # This method tries to simplify creating a correct object filter structure
-    # by allowing the caller to provide a string in a simple query language.
-    # It then translates that string into an Object Filter operation structure
+    # This method simplifies creating correct object filter structures
+    # by defining a simple query language. It translates strings in that
+    # language into an Object Filter operations
     #
     # Object Filter comparisons are done using operators. Some operators make
     # case sensitive comparisons and some do not. The general form of an Object
@@ -187,13 +225,15 @@ module SoftLayer
     #     "*= smaug"
     #
     # The query language also accepts some aliases using asterisks
-    # in a regular-expression-like way.  Those aliases look like:
+    # in a regular-expression-like way. Those aliases look like:
     #
     #   'value'   Exact value match (translates to '_= value')
     #   'value*'  Begins with value (translates to '^= value')
     #   '*value'  Ends with value (translates to '$= value')
     #   '*value*' Contains value (translates to '*= value')
     #
+    # This method corresponds to the +query_filter+ method in the SoftLayer-Python
+    # API.
     def self.query_to_filter_operation(query)
       if query.kind_of? String then
         query.strip!