google-ads-common 0.2.0

data/lib/ads_common/build/savon_abstract_generator.rb

@@ -0,0 +1,59 @@
+#!/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.
+#
+# Code template generator base class
+
+require 'savon'
+require 'erb'
+
+module AdsCommon
+  module Build
+    class SavonAbstractGenerator
+      def initialize(args)
+        if self.class() == AdsCommon::Build::SavonAbstractGenerator
+          raise NoMethodError, "Tried to instantiate an abstract class"
+        end
+        @require_path = args[:require_path]
+        @service_name = args[:service_name]
+        @module_name  = args[:module_name]
+        @namespace = args[:namespace]
+        @generator_stamp = "Code generated by AdsCommon library %s on %s." %
+            [AdsCommon::ApiConfig::ADS_COMMON_VERSION,
+             Time.now.strftime("%Y-%m-%d %H:%M:%S")]
+        prepare_modules_string()
+      end
+
+      def generate_code()
+        code = ERB.new(get_code_template(), 0, '%<>')
+        code.result(binding)
+      end
+
+      def get_code_template()
+        raise NotImplementedError
+      end
+
+      def prepare_modules_string()
+        modules_count = @module_name.scan(/::/).length
+        @modules_open_string = 'module ' + @module_name.gsub(/::/, '; module ')
+        @modules_close_string = 'end; ' * modules_count
+        @modules_close_string += 'end'
+      end
+    end
+  end
+end

data/lib/ads_common/build/savon_generator.rb

@@ -0,0 +1,136 @@
+#!/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.
+#
+# Generates the wrappers for API services. Only used during the
+# 'rake generate' step of library setup.
+
+gem 'savon', '~>0.8.5'
+require 'savon'
+
+require 'ads_common/build/savon_service_generator'
+require 'ads_common/build/savon_registry'
+require 'ads_common/build/savon_registry_generator'
+require 'ads_common/errors'
+
+module AdsCommon
+  module Build
+
+    # Contains the methods that handle wrapper code generation.
+    class SavonGenerator
+
+      # Create a new generator for given WSDL
+      #
+      # Args:
+      #   wsdl_url local or remote URL to pull WSDL data
+      #   code_path local path to store generated files
+      #   service_name a service name to generate stubs from
+      #   module_name a fully-qualified module name
+      def initialize(wsdl_url, code_path, service_name, module_name)
+        @wsdl_url = wsdl_url
+        @code_path = code_path
+        @service_name = service_name
+        @generator_args = {
+            :service_name => service_name,
+            :module_name  => module_name,
+            :require_path => @code_path.sub(/^lib\//, '')
+        }
+      end
+
+      #
+      # Pull, parse and generate wrapper for WSDL on given URL
+      #
+      # Args:
+      #   none, instance variables are used.
+      #
+      # Returns:
+      #   none
+      def process_wsdl()
+        client = Savon::Client.new {|wsdl| wsdl.document = @wsdl_url }
+        begin
+          @generator_args[:namespace] = client.wsdl.namespace
+          do_process_wsdl_client(client)
+        rescue AdsCommon::Errors::Error => e
+          error_msg = "An unrecoverable error occured during code generation"
+          error_msg += " for service [%s]: %s" % [@wsdl_url, e]
+          # TODO log properly
+          raise AdsCommon::Errors::BuildError, error_msg
+        end
+      end
+
+      private
+
+      # Generate code for given Savon client
+      def do_process_wsdl_client(client)
+        service_file_name = @service_name.to_s.snakecase
+
+        wsdl = client.wsdl
+        check_service(wsdl)
+
+        wrapper_file_name = "%s/%s.rb" % [@code_path, service_file_name]
+        write_wrapper(wsdl, wrapper_file_name)
+
+        registry_file_name = "%s/%s_registry.rb" %
+            [@code_path, service_file_name]
+        write_registry(wsdl, registry_file_name)
+      end
+
+      def check_service(wsdl)
+        if wsdl.endpoint.nil? || wsdl.namespace.nil?
+          raise AdsCommon::Errors::BuildError,
+              'WSDL could not be retrieved or parsed.'
+        end
+      end
+
+      # Generates wrapper file
+      def write_wrapper(wsdl, file_name)
+        wrapper_file = create_new_file(file_name)
+        generator = SavonServiceGenerator.new(@generator_args)
+        generator.add_actions(wsdl.soap_actions.dup)
+        wrapper_file.write(generator.generate_code())
+        wrapper_file.close
+      end
+
+      # Generates registry file
+      def write_registry(wsdl, file_name)
+        registry_file = create_new_file(file_name)
+        generator = SavonRegistryGenerator.new(@generator_args)
+        registry = SavonRegistry.new(wsdl)
+        generator.add_exceptions(registry.soap_exceptions.dup)
+        generator.add_methods(registry.soap_methods.dup)
+        generator.add_types(registry.soap_types.dup)
+        registry_file.write(generator.generate_code())
+        registry_file.close
+      end
+
+      # Creates a new file on specified path, overwriting existing one if it
+      # exists
+      def create_new_file(file_name)
+        puts "Creating %s..." % [file_name]
+        make_dir_for_path(file_name)
+        new_file = File.new(file_name, File::WRONLY|File::TRUNC|File::CREAT)
+      end
+
+      # Creates a directory for the file path specified if not exists
+      def make_dir_for_path(path)
+        dir_name = File.dirname(path)
+        Dir.mkdir(dir_name) if !File.directory?(dir_name)
+      end
+    end
+  end
+end

data/lib/ads_common/build/savon_registry.rb

@@ -0,0 +1,236 @@
+#!/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.
+#
+# Registry object for Savon backend. Used on generation step as parsed
+# representation of WSDL for API stubs generation.
+
+require 'savon'
+require 'rexml/document'
+
+module AdsCommon
+  module Build
+    STANDARD_TYPES = ['long', 'boolean', 'int', 'string', 'double']
+
+    # Contains the methods that extracts WSDL data.
+    class SavonRegistry
+      attr_reader :soap_exceptions
+      attr_reader :soap_methods
+      attr_reader :soap_types
+
+      # Initializes the instance.
+      # Args:
+      #   wsdl - string containing wsdl to parse.
+      def initialize(wsdl)
+        do_process_wsdl(wsdl)
+      end
+
+      private
+
+      # Generate code for given Savon client.
+      def do_process_wsdl(wsdl)
+        doc = REXML::Document.new(wsdl.to_xml)
+        @raw_types = []
+        @soap_exceptions = extract_exceptions(doc)
+        sort_exceptions()
+        @soap_methods = extract_methods(doc)
+        @soap_types = extract_types(doc)
+      end
+
+      # Extracts exceptions list with basic properties from ComplexTypes list.
+      def extract_exceptions(doc)
+        exceptions = []
+        ctypes = get_complex_types(doc)
+        raw_exceptions = exceptions_from_ctypes(ctypes)
+        raw_exceptions.each do |raw_exception|
+          exceptions << {:name => raw_exception.attributes['name'],
+              :doc => get_element_doc(raw_exception),
+              :base => get_element_base(raw_exception),
+              :fields => get_element_fields(raw_exception)}
+        end
+        return exceptions
+      end
+
+      # Extracts ComplexTypes from XML into an array.
+      def get_complex_types(doc)
+        complex_types = []
+        REXML::XPath.each(doc, '//schema/complexType') do |ctype|
+          complex_types << ctype
+        end
+        return complex_types
+      end
+
+      # Helper function to find Exceptions (by name) from all types.
+      def exceptions_from_ctypes(ctypes)
+        exceptions = []
+        ctypes.each do |ctype|
+          if ctype.attributes['name'].match('.+Exception$')
+            exceptions << ctype
+          end
+        end
+        return exceptions
+      end
+
+      # Extracts methods and parameters from XML.
+      def extract_methods(doc)
+        methods = []
+        iface = REXML::XPath.first(doc, 'descendant::wsdl:portType')
+        REXML::XPath.each(iface, 'descendant::wsdl:operation') do |operation|
+          methods << {:name => operation.attributes['name'].to_s.snakecase,
+              :input => extract_input_parameters(operation, doc),
+              :output => extract_output_parameters(operation, doc)}
+          # This could be used to include documentation from wsdl.
+          #    :doc => get_element_doc(operation, 'wsdl')}
+        end
+        return methods
+      end
+
+      # Extracts input parameters of given method as an array.
+      def extract_input_parameters(op_node, doc)
+        result = []
+        op_name = op_node.attributes['name'].to_s
+        doc.each_element_with_attribute('name', op_name, 0,
+            '//schema/element') do |method_node|
+          seq_node = REXML::XPath.first(method_node, 'complexType/sequence')
+          result = get_element_fields(seq_node)
+          process_method_field_types(result)
+        end
+        return result
+      end
+
+      # Extracts output parameter name and fields.
+      def extract_output_parameters(op_node, doc)
+        output_element = REXML::XPath.first(op_node, 'descendant::wsdl:output')
+        output_name = (output_element.nil?) ? nil :
+            output_element.attribute('name').to_s
+        output_fields = []
+        doc.each_element_with_attribute('name', output_name, 0,
+            '//schema/element') do |response_node|
+          seq_node = REXML::XPath.first(response_node, 'complexType/sequence')
+          output_fields = get_element_fields(seq_node)
+          process_method_field_types(output_fields)
+        end
+        result = {:name => output_name.snakecase, :fields => output_fields}
+        return result
+      end
+
+      # Checks all fields are of standard type or included in raw_types.
+      def process_method_field_types(fields)
+        fields.each do |field|
+          field_type = field[:type]
+          next if STANDARD_TYPES.include?(field_type)
+          @raw_types << field_type unless @raw_types.include?(field_type)
+        end
+      end
+
+      # Gets element base defined as an attribute in sibling.
+      def get_element_base(root)
+        base_element = REXML::XPath.first(root, 'complexContent/extension')
+        base = (base_element.nil?) ? nil :
+            base_element.attribute('base').to_s.gsub(/^.+:/, '')
+        return base
+      end
+
+      # Gets element documentation text.
+      def get_element_doc(root, namespace = nil)
+        key = 'documentation'
+        key = "%s:%s" % [namespace, key] if namespace
+        doc_element = REXML::XPath.first(root, "descendant::%s" % key)
+        doc = (doc_element.nil?) ? '' :
+            REXML::Text.unnormalize(doc_element.get_text.to_s)
+        return doc
+      end
+
+      # Gets subfields defined as elements under given root.
+      def get_element_fields(root)
+        fields = []
+        REXML::XPath.each(root, 'descendant::element') do |element|
+          fields << {:name => element.attribute('name').to_s.snakecase,
+              :type => element.attribute('type').to_s.gsub(/^.+:/, ''),
+              :min_occurs => attribute_to_int(element.attribute('minOccurs')),
+              :max_occurs => attribute_to_int(element.attribute('maxOccurs'))}
+        end
+        return fields
+      end
+
+      # Extracts definition of all types. If a non standard undefined type is
+      # found it process it recursively.
+      # Special case for extensions - types with a base class.
+      def extract_types(doc)
+        types = []
+        @raw_types.each do |raw_type|
+          doc.each_element_with_attribute('name', raw_type, 0,
+              '//schema/complexType') do |type_node|
+            type = {:name => raw_type, :fields => []}
+            ext_node = REXML::XPath.first(type_node, 'complexContent/extension')
+            if ext_node
+              base_type = ext_node.attribute('base').to_s.gsub(/^.+:/, '')
+              type[:base] = base_type
+              @raw_types << base_type unless @raw_types.include?(base_type)
+              seq_node = REXML::XPath.first(ext_node, 'sequence')
+              fields = get_element_fields(seq_node)
+              process_method_field_types(fields)
+              type[:fields] += fields
+            end
+            seq_node = REXML::XPath.first(type_node, 'sequence')
+            if seq_node
+              fields = get_element_fields(seq_node)
+              process_method_field_types(fields)
+              type[:fields] += fields
+            end
+            types << type
+          end
+        end
+        return types
+      end
+
+      # Simple converter for int values.
+      def attribute_to_int(attribute)
+        return attribute.value.eql?('unbounded') ? nil : attribute.value.to_i
+      end
+
+      # Reorders exceptions so that base ones always come before derived.
+      def sort_exceptions()
+        @ordered_exceptions = []
+        @soap_exceptions.each {|exception| do_include_exception(exception)}
+        @soap_exceptions = @ordered_exceptions
+      end
+
+      # Includes exception into ordered_exceptions if not already there and
+      # makes sure its base is already included.
+      def do_include_exception(exception)
+        return if find_exception(exception, @ordered_exceptions)
+        if exception[:base].nil?
+          @ordered_exceptions.push(exception)
+        else
+          base = find_exception(exception[:base], @soap_exceptions)
+          do_include_exception(base)
+          @ordered_exceptions.push(exception)
+        end
+      end
+
+      # Finds object (exception) by name attribute in a list.
+      def find_exception(exception, list)
+        list.each do |e|
+          return e if (e.eql?(exception) || e[:name].eql?(exception))
+        end
+        return nil
+      end
+    end
+  end
+end

data/lib/ads_common/build/savon_registry_generator.rb

@@ -0,0 +1,139 @@
+#!/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.
+#
+# Code template for registry generation for Savon backend
+
+require 'savon'
+require 'ads_common/build/savon_abstract_generator'
+require 'pp'
+
+module AdsCommon
+  module Build
+    class SavonRegistryGenerator < SavonAbstractGenerator
+      REGISTRY_TEMPLATE = %q{<% %>
+      #!/usr/bin/ruby
+      # This is auto-generated code, changes will be overwritten.
+      # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+      # License:: Licensed under the Apache License,Version 2.0 (the "License").
+      #
+      # <%= @generator_stamp %>
+
+      require 'savon'
+
+      <%= @modules_open_string %>
+
+        class <%= @service_name %>Registry
+          <%= @service_name.upcase %>_METHODS = <%= format_signature(@methods) %>
+          <%= @service_name.upcase %>_TYPES = <%= format_signature(@types) %>
+
+          def self.get_method_signature(method_name)
+            return <%= @service_name.upcase %>_METHODS[method_name.to_sym]
+          end
+
+          def self.get_type_signature(type_name)
+            return <%= @service_name.upcase %>_TYPES[type_name.to_sym]
+          end
+        end
+        <% @exceptions.each do |exception| %>
+          <% array_fields = [] %>
+
+          <% doc_lines = format_doc(exception[:doc]) %>
+          <% doc_lines.each do |doc_line| %>
+        # <%= doc_line %>
+          <% end %>
+          <% base_text = (exception[:base].nil?) ? @default_exception_base : exception[:base] %>
+        class <%= exception[:name] %> < <%= base_text  %>
+          <% exception[:fields].each do |field| %>
+          attr_reader :<%= field[:name] %>  # <%= field[:type] %>
+            <% array_fields << field[:name] if field[:max_occurs].nil? || (field[:max_occurs] > 1) %>
+          <% end %>
+          <% if !(array_fields.empty?) %>
+          def initialize(exception_fault)
+            @array_fields = [] if !defined?(@array_fields)
+            <% array_fields.each do |field| %>
+            @array_fields << '<%= field.to_s %>'
+            <% end %>
+            super(exception_fault)
+          end
+          <% end %>
+        end
+      <% end %>
+      <%= @modules_close_string %>
+
+      }.gsub(/^      /, '')
+
+      def initialize(args)
+        super(args)
+        @exceptions = []
+        @methods = []
+        @types = []
+        @default_exception_base = "%s::Errors::ApiException" %
+            @module_name.split('::').first
+      end
+
+      def get_code_template()
+        REGISTRY_TEMPLATE
+      end
+
+      def add_exceptions(exceptions)
+        @exceptions += exceptions
+      end
+
+      def add_methods(methods)
+        @methods += methods
+      end
+
+      def add_types(types)
+        @types += types
+      end
+
+      private
+
+      # Multi-line documentation formatter. Used to format text extracted from
+      # XML into stripped multi-line text.
+      def format_doc(doc)
+        res = []
+        doc.split(/\n/).each do |line|
+          line = line.strip();
+          res << line if !(line.empty?)
+        end
+        return res
+      end
+
+      # Prepares a hash string based on array of hashes passed.
+      def format_signature(objects_array)
+        objects_hash = get_hash_for_names_array(objects_array)
+        return PP.singleline_pp(objects_hash, '')
+      end
+
+      # Converts an array of hashes to a hash based on ":name" fields:
+      # [{:name => 'foo', :data => 'bar'}] => {:foo => {:data => 'bar'}}
+      def get_hash_for_names_array(input)
+        output = {}
+        input.each do |e|
+          key = e[:name].to_sym
+          value = e.dup
+          value.delete(:name)
+          output[key] = value
+        end
+        return output
+      end
+    end
+  end
+end