softlayer_api 1.0.8 → 2.0.0

data/lib/softlayer/APIParameterFilter.rb

@@ -0,0 +1,131 @@
+
+module SoftLayer
+# An <tt>APIParameterFilter</tt> is an intermediary object that understands how
+# to accept the other API parameter filters and carry their values to
+# <tt>method_missing</tt> in <tt>Service</tt>. Instances of this class are created
+# internally by the <tt>Service</tt> in its handling of a method call and you
+# should not have to create instances of this class directly.
+#
+# Instead, to use an API filter, you add a filter method to the call
+# chain when you call a method through a <tt>SoftLayer::Service</tt>
+#
+# For example, given a <tt>SoftLayer::Service</tt> instance called <tt>account_service</tt>
+# you could take advantage of the API filter that identifies a particular
+# object known to that service using the <tt>object_with_id</tt> method :
+#
+#     account_service.object_with_id(91234).getSomeAttribute
+#
+# The invocation of <tt>object_with_id</tt> will cause an instance of this
+# class to be created with the service as its target.
+#
+class APIParameterFilter
+  attr_reader :target
+  attr_reader :parameters
+
+  def initialize(target, starting_parameters = nil)
+    @target = target
+    @parameters = starting_parameters || {}
+  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
+  # with an ID of 12345 from the ticket service you might use
+  #
+  # ticket_service.object_with_id(12345).getObject
+  def object_with_id(value)
+    # we create a new object in case the user wants to store off the
+    # filter chain and reuse it later
+    APIParameterFilter.new(self.target, @parameters.merge({ :server_object_id => value }))
+  end
+
+  # Use this as part of a method call chain to add an object mask to
+  # the request. The arguments to object mask should be well formed
+  # Extended Object Mask strings:
+  #
+  #   ticket_service.object_mask(
+  #     "mask[createDate, modifyDate]",
+  #     "mask(SoftLayer_Some_Type).aProperty").getObject
+  #
+  # The object_mask becomes part of the request sent to the server
+  #
+  def object_mask(*args)
+    raise ArgumentError, "object_mask expects well-formatted root object mask strings" if args.empty? || (1 == args.count && !args[0])
+    raise ArgumentError, "object_mask expects well-formatted root object mask strings" if args.find { |arg| !(arg.kind_of?(String)) }
+
+    object_mask = (@parameters[:object_mask] || []) + args
+
+    # we create a new object in case the user wants to store off the
+    # filter chain and reuse it later
+    APIParameterFilter.new(self.target, @parameters.merge({ :object_mask => object_mask }));
+  end
+
+  # Adds a result limit which helps you page through a long list of entities
+  #
+  # The offset is the index of the first item you wish to have returned
+  # The limit describes how many items you wish the call to return.
+  #
+  # For example, if you wanted to get five open tickets from the account
+  # starting with the tenth item in the open tickets list you might call
+  #
+  # account_service.result_limit(10, 5).getOpenTickets
+  def result_limit(offset, limit)
+    # we create a new object in case the user wants to store off the
+    # filter chain and reuse it later
+    APIParameterFilter.new(self.target, @parameters.merge({ :result_offset => offset, :result_limit => limit }))
+  end
+
+  # Adds an object_filter to the result.  An Object Filter allows you
+  # to specify criteria which are used to filter the results returned
+  # by the server.
+  def object_filter(filter)
+    raise ArgumentError, "Object mask expects mask properties" if filter.nil?
+
+    # we create a new object in case the user wants to store off the
+    # filter chain and reuse it later
+    APIParameterFilter.new(self.target, @parameters.merge({:object_filter => filter}));
+  end
+
+  # A utility method that returns the server object ID (if any) stored
+  # in this parameter set.
+  def server_object_id
+    self.parameters[:server_object_id]
+  end
+
+  # a utility method that returns the object mask (if any) stored
+  # in this parameter set.
+  def server_object_mask
+    self.parameters[:object_mask]
+  end
+
+  # a utility method that returns the starting index of the result limit (if any) stored
+  # in this parameter set.
+  def server_result_limit
+    self.parameters[:result_limit]
+  end
+
+  # a utility method that returns the starting index of the result limit offset (if any) stored
+  # in this parameter set.
+  def server_result_offset
+    self.parameters[:result_offset]
+  end
+
+  def server_object_filter
+    self.parameters[:object_filter]
+  end
+
+  # This allows the filters to be used at the end of a long chain of calls that ends
+  # at a service.
+  def method_missing(method_name, *args, &block)
+    puts "SoftLayer::APIParameterFilter#method_missing called #{method_name}, #{args.inspect}" if $DEBUG
+
+    if(!block && method_name.to_s.match(/[[:alnum:]]+/))
+      result = @target.call_softlayer_api_with_params(method_name, self, args)
+    else
+      result = super
+    end
+
+    result
+  end
+end
+
+end # module SoftLayer

data/lib/softlayer/Client.rb

@@ -0,0 +1,100 @@
+module SoftLayer
+  # Initialize an instance of the Client class. You pass in the service name
+  # and optionally hash arguments specifying how the client should access the
+  # SoftLayer API.
+  #
+  # The following symbols can be used as hash arguments to pass options to the constructor:
+  # - <tt>:username</tt> - a non-empty string providing the username to use for requests to the service
+  # - <tt>:api_key</tt> - a non-empty string providing the api key to use for requests to the service
+  # - <tt>:endpoint_url</tt> - a non-empty string providing the endpoint URL to use for requests to the service
+  #
+  # If any of the options above are missing then the constructor will try to use the corresponding
+  # global variable declared in the SoftLayer Module:
+  # - <tt>$SL_API_USERNAME</tt>
+  # - <tt>$SL_API_KEY</tt>
+  # - <tt>$SL_API_BASE_URL</tt>
+  #
+  class Client
+    # A username passed as authentication for each request. Cannot be emtpy or nil.
+    attr_reader :username
+
+    # An API key passed as part of the authentication of each request. Cannot be emtpy or nil.
+    attr_reader :api_key
+
+    # The base URL for requests that are passed to the server. Cannot be emtpy or nil.
+    attr_reader :endpoint_url
+
+    # A string passsed as the value for the User-Agent header when requests are sent to SoftLayer API.
+    attr_accessor :user_agent
+
+    def initialize(options = {})
+      @services = { }
+
+      settings = Config.client_settings(options)
+
+      # pick up the username from the options, the global, or assume no username
+      @username = settings[:username] || ""
+
+      # do a similar thing for the api key
+      @api_key = settings[:api_key] || ""
+
+      # and the endpoint url
+      @endpoint_url = settings[:endpoint_url] || API_PUBLIC_ENDPOINT
+
+      @user_agent = settings[:user_agent] || "softlayer_api gem/#{SoftLayer::VERSION} (Ruby #{RUBY_PLATFORM}/#{RUBY_VERSION})"
+
+      raise "A SoftLayer Client requires a username" if !@username || @username.empty?
+      raise "A SoftLayer Client requires an api_key" if !@api_key || @api_key.empty?
+      raise "A SoftLayer Clietn requires an enpoint URL" if !@endpoint_url || @endpoint_url.empty?
+    end
+
+    # return a hash of the authentication headers for the client
+    def authentication_headers
+      {
+        "authenticate" => {
+          "username" => @username,
+          "apiKey" => @api_key
+        }
+      }
+    end
+
+    # Returns a service with the given name.
+    #
+    # If a service has already been created by this client that same service
+    # will be returned each time it is called for by name. Otherwise the system
+    # will try to construct a new service object and return that.
+    #
+    #
+    # If the service has to be created then the service_options will be passed
+    # along to the creative function.  However, when returning a previously created
+    # Service, the service_options will be ignored.
+    #
+    # If the service_name provided does not start with 'SoftLayer__' that prefix
+    # will be added
+    def service_named(service_name, service_options = {})
+      raise ArgumentError,"Please provide a service name" if service_name.nil? || service_name.empty?
+
+      # strip whitespace from service_name and
+      # ensure that it start with "SoftLayer_".
+      #
+      # if it does not, then add it
+      service_name.strip!
+      if not service_name =~ /\ASoftLayer_/
+        service_name = "SoftLayer_#{service_name}"
+      end
+
+      # if we've already created this service, just return it
+      # otherwise create a new service
+      service_key = service_name.to_sym
+      if !@services.has_key?(service_key)
+        @services[service_key] = SoftLayer::Service.new(service_name, {:client => self}.merge(service_options))
+      end
+
+      @services[service_key]
+    end
+
+    def [](service_name)
+      service_named(service_name)
+    end
+  end
+end

data/lib/softlayer/Config.rb

@@ -0,0 +1,77 @@
+#
+# 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 'configparser'
+
+module SoftLayer
+	class Config
+		def Config.globals_settings
+			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
+		end
+
+		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
+		end
+
+		FILE_LOCATIONS = ['/etc/softlayer.conf', '~/.softlayer']
+
+		def Config.file_settings(*additional_files)
+			result = {}
+
+			search_path = FILE_LOCATIONS
+			search_path = search_path + additional_files if additional_files
+			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"]
+
+					if softlayer_section
+						result[:username] = softlayer_section['username'] if softlayer_section['username']
+						result[:endpoint_url] = softlayer_section['endpoint_url'] if softlayer_section['endpoint_url']
+						result[:api_key] = softlayer_section['api_key'] if softlayer_section['api_key']
+					end
+				end
+			end
+
+			result
+		end
+
+		def Config.client_settings(provided_settings = {})
+			settings = file_settings
+			settings.merge! environment_settings
+			settings.merge! globals_settings
+			settings.merge! provided_settings
+
+			settings
+		end
+	end
+end

data/lib/softlayer/ObjectFilter.rb

@@ -0,0 +1,232 @@
+#
+# 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
+  OBJECT_FILTER_OPERATORS = [
+    '*=',   # Contains (ignoring case)
+    '^=',   # Begins with (ignoring case)
+    '$=',   # Ends with (ignoring_case)
+    '_=',   # Matches (ignoring case)
+    '!=',   # Is not Equal To (case sensitive)
+    '<=',   # Less than or Equal To (case sensitive)
+    '>=',   # Greater than or Equal To (case sensitive)
+    '<',    # Less Than (case sensitive)
+    '>',    # Greater Than (case sensitive)
+    '~',    # Contains (case sensitive)
+    '!~'    # Does not Contain (case sensitive)
+  ]
+
+  # A class whose instances represent an Object Filter operation.
+  class ObjectFilterOperation
+    attr_reader :operator
+    attr_reader :value
+
+    def initialize(operator, value)
+      raise ArgumentException, "An unknown operator was given" if !OBJECT_FILTER_OPERATORS.include?(operator.strip)
+      raise ArgumentException, "Expected a value" if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+      @operator = operator.strip
+      @value = value.strip
+    end
+
+    def to_h
+      { 'operation' => "#{operator} #{value}"}
+    end
+  end
+
+  # Routines that are valid within the block provided to a call to
+  # ObjectFilter.build.
+  class ObjectFilterBlockHandler
+    # contains wihout considering case
+    def contains(value)
+      ObjectFilterOperation.new('*=', value)
+    end
+
+    # case insensitive begins with
+    def begins_with(value)
+      ObjectFilterOperation.new('^=', value)
+    end
+
+    # case insensitive ends with
+    def ends_with(value)
+      ObjectFilterOperation.new('$=', value)
+    end
+
+    # matches exactly (ignoring case)
+    def is(value)
+      ObjectFilterOperation.new('_=', value)
+    end
+
+    def is_not(value)
+      ObjectFilterOperation.new('!=', value)
+    end
+
+    def is_greater_than(value)
+      ObjectFilterOperation.new('>', value)
+    end
+
+    def is_less_than(value)
+      ObjectFilterOperation.new('<', value)
+    end
+
+    def is_greater_or_equal_to(value)
+      ObjectFilterOperation.new('>=', value)
+    end
+
+    def is_less_or_equal_to(value)
+      ObjectFilterOperation.new('<=', value)
+    end
+
+    def contains_exactly(value)
+      ObjectFilterOperation.new('~', value)
+    end
+
+    def does_not_contain(value)
+      ObjectFilterOperation.new('!~', value)
+    end
+  end
+
+  # An ObjectFilter is 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>
+  #
+  # This allows you to create object filters by chaining [] calls:
+  #     object_filter["foo"]["bar"]["baz"] = 3 yields {"foo" => { "bar" => {"baz" => 3}}}
+  #
+  class ObjectFilter < Hash
+    # The default initialize for a hash is overridden
+    # so that object filters create sub-filters when asked
+    # for missing keys.
+    def initialize
+      super do |hash, key|
+        hash[key] = ObjectFilter.new
+      end
+    end
+
+    # Builds an object filter with the given key path, a dot separated list of property keys.
+    # The filter itself can be provided as a query string (in the query parameter)
+    # or by providing a block that calls routines in the ObjectFilterBlockHandler class.
+    def self.build(key_path, query = nil, &block)
+      raise ArgumentError, "The key path to build cannot be empty" if !key_path
+
+      # Split the keypath into its constituent parts and notify the user
+      # if there are no parts
+      keys = key_path.split('.')
+      raise ArgumentError, "The key path to build cannot be empty" if keys.empty?
+
+      # This will be the result of the build
+      result = ObjectFilter.new
+
+      # chase down the key path to the last-but-one key
+      current_level = result
+      while keys.count > 1
+        current_level = current_level[keys.shift]
+      end
+
+      # if there is a block, then the query will come from
+      # 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
+        block_handler = ObjectFilterBlockHandler.new
+        query = block_handler.instance_eval(&block)
+      end
+
+      # If we have a query, we assign it's value to the last key
+      # otherwise, we build an emtpy filter at the bottom
+      if query
+        case
+        when query.kind_of?(Numeric)
+          current_level[keys.shift] = { 'operation' => query }
+        when query.kind_of?(SoftLayer::ObjectFilterOperation)
+          current_level[keys.shift] = query.to_h
+        when query.kind_of?(String)
+          current_level[keys.shift] = query_to_filter_operation(query)
+        when query.kind_of?(Hash)
+          current_level[keys.shift] = query
+        else
+          current_level[keys.shift]
+        end
+      else
+        current_level[keys.shift]
+      end
+
+      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
+    #
+    # Object Filter comparisons are done using operators. Some operators make
+    # case sensitive comparisons and some do not. The general form of an Object
+    # Filter operation is an operator follwed by the value used in the comparison.
+    # e.g.
+    #     "*= smaug"
+    #
+    # The query language also accepts some aliases using asterisks
+    # 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')
+    #
+    def self.query_to_filter_operation(query)
+      if query.kind_of? String then
+        query.strip!
+
+        begin
+          return { 'operation' => Integer(query) }
+        rescue
+        end
+
+        operator = OBJECT_FILTER_OPERATORS.find do | operator_string |
+          query[0 ... operator_string.length] == operator_string
+        end
+
+        if operator then
+          operation = "#{operator} #{query[operator.length..-1].strip}"
+        else
+          case query
+          when /\A\*(.*)\*\Z/
+            operation = "*= #{$1}"
+          when /\A\*(.*)/
+            operation = "$= #{$1}"
+          when /\A(.*)\*\Z/
+            operation = "^= #{$1}"
+          else
+            operation = "_= #{query}"
+          end #case
+        end #if
+      else
+        operation = query.to_i
+      end # query is string
+
+      { 'operation' => operation }
+    end # query_to_filter_operation
+
+  end # ObjectFilter
+end # SoftLayer