google-ads-common 0.2.0 → 0.2.1

data/lib/ads_common/build/savon_registry_generator.rb

@@ -34,8 +34,6 @@ module AdsCommon
       #
       # <%= @generator_stamp %>
 
-      require 'savon'
-
       <%= @modules_open_string %>
 
         class <%= @service_name %>Registry
@@ -73,7 +71,7 @@ module AdsCommon
           end
           <% end %>
         end
-      <% end %>
+        <% end %>
       <%= @modules_close_string %>
 
       }.gsub(/^      /, '')

data/lib/ads_common/build/savon_service_generator.rb

@@ -33,80 +33,31 @@ module AdsCommon
       #
       # <%= @generator_stamp %>
 
-      require 'savon'
+      require 'ads_common/savon_service'
       require '<%= @require_path %>/<%= @service_name.to_s.snakecase %>_registry'
 
       <%= @modules_open_string %>
 
-        class <%= @service_name %>
-          attr_accessor :headerhandler, :wiredump_dev, :options
+        class <%= @service_name %> < AdsCommon::SavonService
           def initialize(endpoint)
-            @headerhandler = []
-            @wiredump_dev = nil
-            @options = {}
-            @client = Savon::Client.new do |wsdl|
-              wsdl.namespace = '<%= @namespace %>'
-              wsdl.endpoint = endpoint
-            end
+            namespace = '<%= @namespace %>'
+            super(endpoint, namespace)
           end
-
           <% @actions.each do |action| %>
-          def <%= action %>(args = nil)
-            validate_args(:<%= action %>, args)
-            response = @client.request(:<%= action %>) {|soap|
-              set_headers(soap, args)
-            }
-            handle_errors(response)
-            return extract_result(response, '<%= action %>')
-          end
-          <% end %>
-          private
-
-          def validate_args(action_symbol, args = nil)
-            true
-          end
-
-          def set_headers(soap, args)
-            @headerhandler.each { |handler| handler.prepare_soap(soap, args) }
-          end
 
-          # Extracts the finest results possible for the given result. Returns
-          # the response itself in worst case (contents unknown).
-          def extract_result(response, action_name)
-            method = <%= @service_name %>Registry::get_method_signature(action_name)
-            action = method[:output][:name].to_sym
-            result = response.to_hash
-            result = result[action] if result.include?(action)
-            result = result[:rval] if result.include?(:rval)
-            return result
+          def <%= action %>(*args)
+            return execute_action('<%= action %>', args)
           end
+          <% end %>
 
-          # Checks for errors in response and raises appropriate exception
-          def handle_errors(response)
-            if response.soap_fault?
-              exception = exception_for_soap_fault(response)
-              raise exception
-            end
+          private
 
-            if response.http_error?
-              raise AdsCommon::Errors::HttpError,
-                  "HTTP Error occurred: %s" % response.http_error
-            end
+          def get_service_registry()
+            return <%= @service_name %>Registry
           end
 
-          # Finds an exception object for a given response
-          def exception_for_soap_fault(response)
-            begin
-              exception_fault =
-                  response.to_hash[:fault][:detail][:api_exception_fault]
-              exception_name = exception_fault[:application_exception_type]
-              exception_class = <%= @module_name %>::const_get(exception_name)
-              return exception_class.new(exception_fault)
-            rescue Exception => e
-              return AdsCommon::Errors::ApiException.new(
-                  "Failed to resolve exception (%s)\n  SOAP fault: %s" %
-                  [e.message, response.soap_fault])
-            end
+          def get_module()
+            return <%= @module_name %>
           end
         end
       <%= @modules_close_string %>

data/lib/ads_common/build/soap4r_generator.rb

@@ -268,7 +268,7 @@ module AdsCommon
               object.each do |entry, value|
                 entry = entry.to_s
                 unless entry == 'xsi_type'
-                  if @api.config.read('service.use_ruby_names')
+                  if @api.config.read('service.use_ruby_names', true)
                     entry = camel_case(entry)
                   end
                   if value.is_a? Hash
@@ -319,7 +319,7 @@ module AdsCommon
                   if object.respond_to? property and !property.include?('_Type')
                     value = object.send(property)
                     property_name = nil
-                    if @api.config.read('service.use_ruby_names')
+                    if @api.config.read('service.use_ruby_names', true)
                       property_name = underscore(property).to_sym
                     else
                       property_name = property.to_sym

data/lib/ads_common/config.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 #
-# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+# Authors:: api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2010, Google Inc. All Rights Reserved.
 #
@@ -29,26 +29,21 @@ module AdsCommon
     # Initialized the Config object with either the contents of a provided file
     # or a provided hash.
     def initialize(param = nil)
-      @config = {}
-      if param and param.is_a? String
-        load(param)
-      elsif param and param.is_a? Hash
-        set_all(param)
+      @config = Hash.new
+      case param
+        when String: load(param)
+        when Hash: set_all(param)
       end
     end
 
     # Reads a property or category from the loaded configuration.
     # They can be indexed using a dot-based notation (e.g. "category.property"
     # to access "property" under "category").
-    def read(property_path = nil)
-      current_level = @config
-      if property_path
-        property_path.split('.').each do |item|
-          return nil if !current_level or !(current_level.is_a?(Hash))
-          current_level = current_level[item.to_sym]
-        end
-      end
-      return current_level
+    #
+    # Returns the specified default if no value found.
+    def read(property_path, default_value = nil)
+      result = find_value(@config, property_path)
+      return (result.nil?) ? default_value : result
     end
 
     # Writes a new value to a property or category in memory (creating it if
@@ -56,18 +51,13 @@ module AdsCommon
     # They can be indexed using a dot-based notation (e.g. "category.property"
     # to access "property" under "category").
     def set(property_path, value)
-      @config = {} if !@config
-      current_level = @config
       if property_path
-        segments = property_path.split('.')
-        segments[0,-2].each do |item|
-          return nil if !current_level or !(current_level.is_a?(Hash))
-          current_level = current_level[item.to_sym]
-        end
-        if current_level and current_level.is_a?(Hash)
-          current_level[segments.last] = value
-          return value
+        last_node = @config
+        last_name = property_path.split('.').inject(nil) do |last_name, section|
+          last_node = last_node[last_name.to_sym] ||= {} unless last_name.nil?
+          section
         end
+        last_node[last_name.to_sym] = value
       end
       return nil
     end
@@ -77,46 +67,41 @@ module AdsCommon
       @config = process_hash_keys(properties)
     end
 
+    private
+
     # Auxiliary method to recurse through a hash and convert all the keys to
     # symbols.
     def process_hash_keys(hash)
-      new_hash = {}
-      hash.each do |key, value|
-        if value.is_a? Hash
-          new_hash[key.to_sym] = process_hash_keys(value)
-        else
-          new_hash[key.to_sym] = value
-        end
+      return hash.inject({}) do |result, pair|
+        key, value = pair
+        result[key.to_sym] = value.is_a?(Hash) ?
+            process_hash_keys(value) : value
+        result
       end
-      return new_hash
     end
 
-    # Reads a configuration file and returns a Ruby structure with the complete
-    # set of keys and values.
-    #
+    # Finds a value for string of format 'level1.level2.name' in a given hash.
+    def find_value(data, path)
+      return (path.nil? or data.nil?) ? nil :
+          path.split('.').inject(data) do |node, section|
+            break if node.nil?
+            key = section.to_sym
+            (node.is_a?(Hash) and node.include?(key)) ? node[key] : nil
+          end
+    end
+
+    # Reads a configuration file into instance variable as a Ruby structure with
+    # the complete set of keys and values.
     #
     # Args:
     # - filename: config file to be read (*String*)
     #
-    # Returns:
-    # - Ruby objects for the stored YAML
-    #
     # Raises:
-    # - <b>Errno::EACCES</b> if the file does not exist.
+    # - <b>Errno::ENOENT</b> if the file does not exist.
     #
     def load(filename)
-      unless File.exist?(filename)
-        raise(Errno::EACCES, "File #{filename} does not exist")
-      end
-      file = nil
-      begin
-        file = File.open(filename)
-        @config = YAML::load(file)
-      ensure
-        file.close if file
-      end
-      return @config
+      @config = YAML::load_file(filename)
+      return nil
     end
   end
-
 end

data/lib/ads_common/savon_headers/simple_header_handler.rb

@@ -45,7 +45,8 @@ module AdsCommon
       end
 
       # Enriches soap object with API-specific headers like namespaces, login
-      # credentials etc.
+      # credentials etc. Sets the default namespace for the body to the one
+      # specified in initializer.
       #
       # Args:
       #  - soap: a Savon soap object to fill fields in.
@@ -57,9 +58,8 @@ module AdsCommon
         soap.header[prepend_namespace(@element_name)] =
             generate_request_header()
         soap.namespace = @namespace
-        if (!args.nil?)
-          soap.body = prepare_args(args)
-        end
+        soap.body = args if args
+        soap.input[1] = {:xmlns => @namespace}
       end
 
       private
@@ -82,66 +82,15 @@ module AdsCommon
         return request_header
       end
 
-      # Modifies request parameters to include namespace reference. For Hash
-      # and Array data types dives deeper into structure.
-      #
-      # Args:
-      #  - args: subtree of request parameters.
-      #
-      # Returns:
-      #  - subtree with modified parameters including namespaces.
-      def prepare_args(args)
-        res = case args
-            when Hash
-              prepare_hash_args(args)
-            when Array
-              prepare_array_args(args)
-            else
-              args
-            end
-        return res
-      end
-
-      # Crawls hash for all the request parameters and adds namespace
-      # reference for the keys.
-      #
-      # Args:
-      #  - args: Hash element of subtree of request parameters.
-      #
-      # Returns:
-      #  - Modified Hash with all keys updated and all values crawled.
-      def prepare_hash_args(args)
-        res = {}
-        args.each do |key, value|
-          res[prepend_namespace(key)] = prepare_args(value)
-        end
-        return res
-      end
-
-      # Crawls array and process each of its elements to include namespace.
-      #
-      # Args:
-      #  - args: Array element of subtree of request parameters.
-      #
-      # Returns:
-      #  - Modified Array with every element crawled.
-      def prepare_array_args(args)
-        res = []
-        args.each do |item|
-          res << prepare_args(item)
-        end
-        return res
-      end
-
-      # Adds namespace to the request parameter name.
+      # Adds namespace to the given string.
       #
       # Args:
-      #  - str: String to prepend with a namespace
+      #  - str: String to prepend with a namespace.
       #
       # Returns:
       #  - String with a namespace.
       def prepend_namespace(str)
-        return "%s:%s" % [DEFAULT_NAMESPACE, str.to_s]
+        return "%s:%s" % [DEFAULT_NAMESPACE, str]
       end
     end
   end

data/lib/ads_common/savon_service.rb

@@ -0,0 +1,266 @@
+#!/usr/bin/ruby
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# Base class for all generated API services based on Savon backend.
+
+gem 'savon', '~>0.9.1'
+require 'savon'
+
+module AdsCommon
+  class SavonService
+    attr_accessor :headerhandler, :wiredump_dev, :options
+
+    # Creates a new service.
+    def initialize(endpoint, namespace)
+      if self.class() == AdsCommon::SavonService
+        raise NoMethodError, "Tried to instantiate an abstract class"
+      end
+      @headerhandler = []
+      @wiredump_dev = nil
+      @options = {}
+      @client = Savon::Client.new do |wsdl|
+        wsdl.namespace = namespace
+        wsdl.endpoint = endpoint
+      end
+    end
+
+    private
+
+    # Returns ServiceRegistry for the current service. Has to be overriden.
+    def get_service_registry()
+      raise NoMethodError, "This methods needs to be overriden"
+    end
+
+    # Returns Module for the current service. Has to be overriden.
+    def get_module()
+      raise NoMethodError, "This methods needs to be overriden"
+    end
+
+    # Executes SOAP action specified as a string with given arguments.
+    def execute_action(action_name, args)
+      args = validate_args(action_name, args)
+      response = @client.request(action_name.to_sym) do |soap|
+        set_headers(soap, args)
+      end
+      handle_errors(response)
+      return extract_result(response, action_name)
+    end
+
+    # Validates input parameters to:
+    # - add parameter names;
+    # - resolve xsi:type where required;
+    # - convert some native types to xml.
+    def validate_args(action_name, *args)
+      validated_args = Hash.new
+      in_params = get_service_registry.get_method_signature(action_name)[:input]
+      in_params.each_with_index do |in_param, index|
+        key = in_param[:name]
+        value = args[index]
+        validated_args[key] = (value.nil?) ? nil :
+            validate_arg(value, validated_args, key)
+      end
+      return validated_args
+    end
+
+    # Validates method argument. Runs recursively if hash or array encountered.
+    # Also handles some types that need special conversions.
+    def validate_arg(arg, parent = nil, key = nil)
+      result = case arg
+        when Hash: validate_hash_arg(arg, parent, key)
+        when Array: arg.map {|item| validate_arg(item, parent, key)}
+        when Time: time_to_xml_hash(arg)
+        else arg
+      end
+      return result
+    end
+
+    # Validates hash argument recursively. Keeps tracking of correct place
+    # for xsi:type and adds is when required.
+    def validate_hash_arg(arg, parent = nil, key = nil)
+      xsi_type = arg.delete('xsi:type') || arg.delete(:xsi_type)
+      if xsi_type
+        if parent and key
+          add_xsi_type(parent, key, xsi_type)
+        else
+          raise AdsCommon::Errors::ApiException.new(
+              "Can't find correct position for xsi:type (%s) [%s], [%s]" %
+                  [xsi_type, parent, key])
+        end
+      end
+      return arg.inject({}) do |result, (key, value)|
+        result[key] = (key == :attributes!) ? value :
+            validate_arg(value, result, key)
+        result
+      end
+    end
+
+    # Adds ":attributes!" record for Savon to specify xsi:type.
+    def add_xsi_type(parent, key, xsi_type)
+      parent[:attributes!] ||= {}
+      parent[:attributes!][key] ||= {}
+      parent[:attributes!][key]["xsi:type"] ||= []
+      parent[:attributes!][key]["xsi:type"] << xsi_type
+    end
+
+    # Executes each handler to generate SOAP headers.
+    def set_headers(soap, args)
+      @headerhandler.each {|handler| handler.prepare_soap(soap, args)}
+    end
+
+    # Checks for errors in response and raises appropriate exception.
+    def handle_errors(response)
+      if response.soap_fault?
+        exception = exception_for_soap_fault(response)
+        raise exception
+      end
+      if response.http_error?
+        raise AdsCommon::Errors::HttpError,
+            "HTTP Error occurred: %s" % response.http_error
+      end
+    end
+
+    # Finds an exception object for a given response.
+    def exception_for_soap_fault(response)
+      begin
+        fault = response[:fault]
+        if fault[:detail] and fault[:detail][:api_exception_fault]
+          exception_fault = fault[:detail][:api_exception_fault]
+          exception_name = exception_fault[:application_exception_type]
+          exception_class = get_module().const_get(exception_name)
+          return exception_class.new(exception_fault)
+        elsif fault[:faultstring]
+          fault_message = fault[:faultstring]
+          return AdsCommon::Errors::ApiException.new(
+              "Unknown exception with error: %s" % fault_message)
+        else
+          raise ArgumentError.new(fault.to_s)
+        end
+      rescue Exception => e
+        return AdsCommon::Errors::ApiException.new(
+            "Failed to resolve exception (%s), SOAP fault: %s" %
+            [e.message, response.soap_fault])
+      end
+    end
+
+    # Extracts the finest results possible for the given result. Returns the
+    # response itself in worst case (contents unknown).
+    def extract_result(response, action_name)
+      method = get_service_registry.get_method_signature(action_name)
+      action = method[:output][:name].to_sym
+      result = response.to_hash
+      result = result[action] if result.include?(action)
+      return normalize_output(result, method)
+    end
+
+    # Normalizes output starting with root node "rval".
+    def normalize_output(output_data, method_definition)
+      fields_list = method_definition[:output][:fields]
+      result = normalize_output_field(output_data, fields_list, :rval)
+      return result[:rval]
+    end
+
+    # Normalizes one field of a given data recursively.
+    # Args:
+    #  - output_data: XML data to normalize
+    #  - fields_list: expected list of fields from signature
+    #  - field_name: specifies field name to normalize
+    def normalize_output_field(output_data, fields_list, field_name)
+      return nil if output_data.nil?
+      field_definition = get_field_by_name(fields_list, field_name)
+      field_sym = field_name.to_sym
+      output_data[field_sym] = normalize_type(output_data[field_sym],
+          field_definition)
+
+      sub_type = get_service_registry.get_type_signature(
+          field_definition[:type])
+      if sub_type
+        sub_type[:fields] += implode_parent(sub_type)
+        if sub_type[:fields]
+          # go recursive
+          sub_type[:fields].each do |sub_type_field|
+            if output_data[field_sym].is_a?(Array)
+              items_list = output_data[field_sym]
+              output_data[field_sym] = Array.new
+              items_list.each do |item|
+                output_data[field_sym] <<
+                    normalize_output_field(item, sub_type_field,
+                                           sub_type_field[:name])
+              end
+            else
+              output_data[field_sym] =
+                  normalize_output_field(output_data[field_sym], sub_type_field,
+                                         sub_type_field[:name])
+            end
+          end
+        end
+      end
+      return output_data
+    end
+
+    # Converts XML input string into a native format.
+    def normalize_type(data, field)
+      type_name = field[:type]
+      result = case type_name
+        when 'long', 'int': Integer(data)
+        when 'double': Float(data)
+        when 'boolean': data.kind_of?(String) ? data.casecmp('true') == 0 : data
+        else data
+      end
+      # If field signature allows an array, forcing array structure even for one
+      # item.
+      if !field[:min_occurs].nil? and
+          (field[:max_occurs].nil? or field[:max_occurs] > 1)
+        result = arrayize(result)
+      end
+      return result
+    end
+
+    # Finds a field in a list by its name.
+    def get_field_by_name(fields_list, name)
+      fields_array = arrayize(fields_list)
+      index = fields_array.find_index {|field| field[:name].eql?(name)}
+      return (index.nil?) ? nil : fields_array.at(index)
+    end
+
+    # Makes sure object is an array.
+    def arrayize(object)
+      return Array.new if object.nil?
+      return object.is_a?(Array) ? object : [object]
+    end
+
+    # Converts Time to a hash for XML marshalling.
+    def time_to_xml_hash(time)
+      return {
+          :hour => time.hour, :minute => time.min, :second => time.sec,
+          :date => {:year => time.year, :month => time.month, :day => time.day}
+      }
+    end
+
+    # Returns all inherited fields of superclasses for given type.
+    def implode_parent(data_type)
+      result = Array.new
+      if data_type and data_type[:base]
+        parent_type = get_service_registry.get_type_signature(data_type[:base])
+        result += parent_type[:fields] if parent_type[:fields]
+        result += implode_parent(parent_type) if parent_type[:base]
+      end
+      return result
+    end
+  end
+end