google-ads-common 0.4.0 → 0.5.0

data/lib/ads_common/credential_handler.rb

@@ -2,7 +2,7 @@
 #
 # Authors:: api.sgomes@gmail.com (Sérgio Gomes)
 #
-# Copyright:: Copyright 2010, Google Inc. All Rights Reserved.
+# 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.
@@ -21,17 +21,13 @@
 
 module AdsCommon
   class CredentialHandler
+    attr_reader :credentials
 
     def initialize(config)
       @config = config
       load_from_config
     end
 
-    # Retrieve all credentials (optional parameter specifying API version).
-    def credentials(version = nil)
-      return @credentials
-    end
-
     # Set the credentials hash to a new one. Calculate difference, and call the
     # AuthHandler callback appropriately.
     def credentials=(new_credentials)
@@ -59,7 +55,7 @@ module AdsCommon
     # appropriately.
     def set_credential(credential, value)
       @credentials[credential] = value
-      @auth_handler.property_changed(credential, value) if auth_handler
+      @auth_handler.property_changed(credential, value) if @auth_handler
     end
 
     private

data/lib/ads_common/errors.rb

@@ -27,9 +27,25 @@ module AdsCommon
     class Error < ::StandardError
     end
 
-    # Raised if an attempt is made to authenticate via the ClientLogin API with
-    # missing or wrong information
+    # Raised if an attempt is made to authenticate with missing or wrong
+    # information.
     class AuthError < Error
+      attr_reader :error
+      attr_reader :info
+      def initialize(message = self.class.to_s, error = nil, info = nil)
+        super(message)
+        @error = error
+        @info = info
+      end
+    end
+
+    # Raised when OAuth access token is required.
+    class OAuthVerificationRequired < AuthError
+      attr_reader :oauth_url
+      def initialize(oauth_url)
+        super()
+        @oauth_url = oauth_url
+      end
     end
 
     # Raised if setting a non-existant property on an object
@@ -57,14 +73,10 @@ module AdsCommon
     # Superclass for API exceptions. Each client library should implement its
     # own subclass with extra fields.
     class ApiException < Error
-
       attr_reader :message
-
       def initialize(message = nil)
         @message = message
       end
-
     end
-
   end
 end

data/lib/ads_common/savon_headers/base_header_handler.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/ruby
+#
+# Authors:: 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 handlers of SOAP headers.
+
+module AdsCommon
+  module SavonHeaders
+    class BaseHeaderHandler
+      # Default namespace alias.
+      DEFAULT_NAMESPACE = 'wsdl'
+
+      # Initializes a header handler.
+      #
+      # Args:
+      #  - credential_handler: a header with credential data
+      #  - auth_handler: a header with auth data
+      #  - element_name: an API-specific name of header element
+      #  - namespace: default namespace to use
+      #  - version: services version
+      #
+      def initialize(credential_handler, auth_handler, element_name,
+                     namespace, version)
+        @credential_handler = credential_handler
+        @auth_handler = auth_handler
+        @element_name = element_name
+        @namespace = namespace
+        @version = version
+        Savon.configure {|config| config.raise_errors = false}
+      end
+
+      # Enriches soap object with API-specific headers like namespaces, login
+      # credentials etc.
+      #
+      # Needs to be overriden.
+      #
+      # Args:
+      #  - request: a HTTPI Request for extra configuration
+      #  - soap: a Savon soap object to fill fields in
+      #  - args: request parameters to adjust for namespaces
+      #
+      # Returns:
+      #  - Modified request and soap structures
+      #
+      def prepare_request(request, soap, args)
+        soap.namespace = @namespace
+        soap.body = args if args
+        # Sets the default namespace for the body.
+        soap.input[2] = {:xmlns => @namespace}
+      end
+
+      # Adds namespace to the given string.
+      #
+      # Args:
+      #  - str: String to prepend with a namespace
+      #
+      # Returns:
+      #  - String with a namespace
+      #
+      def prepend_namespace(str)
+        return "%s:%s" % [DEFAULT_NAMESPACE, str]
+      end
+    end
+  end
+end

data/lib/ads_common/{soap4r_logger.rb → savon_headers/httpi_request_proxy.rb}

@@ -1,6 +1,4 @@
-#!/usr/bin/ruby
-#
-# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+# Authors:: api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
@@ -17,26 +15,35 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# Wrapper class to handle Soap4r-specific logging to standard logger.
+# OAuth request proxy for HTTPI::Request.
 
-require 'logger'
+require 'oauth/request_proxy/base'
+require 'httpi/request'
 
-module AdsCommon
-  class Soap4rLogger
-    # Constructor for Soap4rLogger.
-    #
-    # Args:
-    # - logger: a ruby logger to log to.
-    # - log_level: default log_level for streams, defaults to INFO.
-    #
-    def initialize(logger, log_level = Logger::INFO)
-      @logger = logger
-      @log_level = log_level
-    end
+module OAuth
+  module RequestProxy
+    class HTTPIRequest < OAuth::RequestProxy::Base
+      proxies HTTPI::Request
+
+      # HTTP method to use.
+      def method
+        return 'POST'
+      end
+
+      # Request URL.
+      def uri
+        request.url.to_s
+      end
+
+      # Query parameters.
+      def parameters
+        options[:parameters]
+      end
 
-    # Overload << operator to perform logging.
-    def << (text)
-      @logger.add(@log_level) {text.to_s}
+      # Request body.
+      def body
+        request.body
+      end
     end
   end
 end

data/lib/ads_common/savon_headers/oauth_header_handler.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/ruby
+#
+# Authors:: 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.
+#
+# Handles SOAP headers and namespaces definition for OAuth type header.
+
+require 'oauth'
+
+require 'ads_common/savon_headers/base_header_handler'
+require 'ads_common/savon_headers/httpi_request_proxy'
+
+module AdsCommon
+  module SavonHeaders
+    class OAuthHeaderHandler < BaseHeaderHandler
+      # Enriches soap object with API-specific headers like namespaces, login
+      # credentials etc. Sets the default namespace for the body to the one
+      # specified in initializer.
+      #
+      # Args:
+      #  - request: a HTTPI Request for extra configuration
+      #  - soap: a Savon soap object to fill fields in
+      #  - args: request parameters to adjust for namespaces
+      #
+      # Returns:
+      #  - Modified soap structure
+      #
+      def prepare_request(request, soap, args)
+        super(request, soap, args)
+        generate_headers(request, soap)
+      end
+
+      private
+
+      # Generates SOAP request header with login credentials and namespace
+      # definition for OAuth authentication.
+      #
+      # Args:
+      #  - request: a HTTPI Request to generate headers for
+      #  - soap: a Savon soap object to fill fields in
+      #
+      # Returns:
+      #  - Hash containing a header with filled in credentials
+      #
+      def generate_headers(request, soap)
+        headers = @auth_handler.headers(@credential_handler.credentials)
+        request_header = headers.inject({}) do |request_header, (header, value)|
+          if header == :access_token
+            request.headers['Authorization'] =
+                generate_oauth_parameters_string(request, value, soap.endpoint)
+          else
+            request_header[prepend_namespace(header)] = value
+          end
+          request_header
+        end
+        soap.header[prepend_namespace(@element_name)] = request_header
+      end
+
+      # Generates auth string for OAuth method of authentication.
+      #
+      # Args:
+      # - request: a HTTPI::Request to sign
+      # - access_token: an initialized OAuth AccessToken
+      # - url: request URL to generate auth string for
+      #
+      # Returns:
+      # - Authentication string
+      #
+      def generate_oauth_parameters_string(request, access_token, url)
+        request.url = url
+        oauth_params = {:consumer => @auth_handler.get_oauth_consumer(),
+                        :token => access_token}
+        oauth_helper = OAuth::Client::Helper.new(request, oauth_params)
+        return oauth_helper.header
+      end
+    end
+  end
+end

data/lib/ads_common/savon_headers/simple_header_handler.rb

@@ -17,49 +17,29 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# Handles SOAP headers and namespaces definition for Savon SOAP backend.
+# Handles simple SOAP headers and namespaces definition for Savon SOAP backend.
+
+require 'ads_common/savon_headers/base_header_handler'
 
 module AdsCommon
   module SavonHeaders
-    class SimpleHeaderHandler
-
-      # Default namespace alias
-      DEFAULT_NAMESPACE = 'wsdl'
-
-      # Initializes a header handler.
-      #
-      # Args:
-      #  - credential_handler: a header with credential data.
-      #  - auth_handler: a header with auth data.
-      #  - element_name: an API-specific name of header element.
-      #  - namespace: default namespace to use.
-      #  - version: services version.
-      def initialize(credential_handler, auth_handler, element_name,
-                     namespace, version)
-        @credential_handler = credential_handler
-        @auth_handler = auth_handler
-        @element_name = element_name
-        @namespace = namespace
-        @version = version
-        Savon.configure {|config| config.raise_errors = false}
-      end
-
+    class SimpleHeaderHandler < BaseHeaderHandler
       # Enriches soap object with API-specific headers like namespaces, login
       # 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.
-      #  - args: request parameters to adjust for namespaces.
+      #  - request: a HTTPI Request for extra configuration (unused)
+      #  - soap: a Savon soap object to fill fields in
+      #  - args: request parameters to adjust for namespaces
       #
       # Returns:
-      #  - Modified soap structure.
-      def prepare_soap(soap, args)
+      #  - Modified soap structure
+      #
+      def prepare_request(request, soap, args)
+        super(request, soap, args)
         soap.header[prepend_namespace(@element_name)] =
             generate_request_header()
-        soap.namespace = @namespace
-        soap.body = args if args
-        soap.input[1] = {:xmlns => @namespace}
       end
 
       private
@@ -68,29 +48,17 @@ module AdsCommon
       # definition.
       #
       # Args:
-      #  - None.
+      #  - None
       #
       # Returns:
-      #  - Hash containing a header with filled in credentials.
+      #  - Hash containing a header with filled in credentials
+      #
       def generate_request_header()
-        request_header = {}
-        credentials = @credential_handler.credentials(@version)
-        headers = @auth_handler.headers(credentials)
-        headers.each do |header, value|
+        headers = @auth_handler.headers(@credential_handler.credentials)
+        return headers.inject({}) do |request_header, (header, value)|
           request_header[prepend_namespace(header)] = value
+          request_header
         end
-        return request_header
-      end
-
-      # Adds namespace to the given string.
-      #
-      # Args:
-      #  - str: String to prepend with a namespace.
-      #
-      # Returns:
-      #  - String with a namespace.
-      def prepend_namespace(str)
-        return "%s:%s" % [DEFAULT_NAMESPACE, str]
       end
     end
   end

data/lib/ads_common/savon_service.rb

@@ -19,18 +19,26 @@
 #
 # Base class for all generated API services based on Savon backend.
 
-gem 'savon', '~>0.9.1'
 require 'savon'
 
 module AdsCommon
   class SavonService
+    # Default namespace name.
+    DEFAULT_NAMESPACE = 'wsdl'
+
     attr_accessor :headerhandler
+    attr_reader :api
+    attr_reader :version
+    attr_reader :namespace
 
     # Creates a new service.
-    def initialize(endpoint, namespace)
+    def initialize(api, endpoint, namespace, version)
       if self.class() == AdsCommon::SavonService
         raise NoMethodError, "Tried to instantiate an abstract class"
       end
+      @api = api
+      @version = version
+      @namespace = namespace
       @headerhandler = []
       @client = Savon::Client.new do |wsdl|
         wsdl.namespace = namespace
@@ -74,34 +82,60 @@ module AdsCommon
     # - resolve xsi:type where required;
     # - convert some native types to xml.
     def validate_args(action_name, args)
-      validated_args = Hash.new
+      validated_args = {}
       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 = deep_copy(args[index])
-        validated_args[key] = (value.nil?) ? nil :
-            validate_arg(value, validated_args, key)
+        validated_args[key] = (value.nil?) ?
+             nil : validate_arg(value, validated_args, key, in_param[:type])
       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)
+    def validate_arg(arg, parent = nil, key = nil, field_type_name = nil)
+      field_type = get_full_type_signature(field_type_name)
       result = case arg
-        when Hash then validate_hash_arg(arg, parent, key)
-        when Array then arg.map {|item| validate_arg(item, parent, key)}
+        when Hash
+          validate_hash_arg(arg, parent, key, field_type)
+        when Array then arg.map do |item|
+           validate_arg(item, parent, key, field_type_name)
+          end
         when Time then time_to_xml_hash(arg)
         else arg
       end
       return result
     end
 
+    # Generates order of XML elements for SOAP request. Returns only items
+    # existing in arg.
+    def generate_order_for_args(arg, fields)
+      all_keys = fields.map {|field| field[:name]}
+      return all_keys & arg.keys
+    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)
+    def validate_hash_arg(arg, parent = nil, key = nil, field_type = nil)
+      # Non-default namespace should be used, overriding default.
+      if field_type and field_type.include?(:ns)
+        namespace = get_service_registry.get_namespace(field_type[:ns])
+        add_attribute(parent, prefix_key(key), 'xmlns', namespace)
+      end
+
+      # Handling custom xsi:type.
       xsi_type = arg.delete('xsi:type') || arg.delete(:xsi_type)
       if xsi_type
+        xsi_field_type = get_full_type_signature(xsi_type)
+        if xsi_field_type.nil?
+          raise AdsCommon::Errors::ApiException.new(
+              "Incorrect xsi:type specified: %s" % [xsi_type])
+        else
+          # TODO: make sure xsi_type is derived from field_type.
+          field_type = xsi_field_type
+        end
         if parent and key
           add_xsi_type(parent, key, xsi_type)
         else
@@ -110,24 +144,71 @@ module AdsCommon
                   [xsi_type, parent, key])
         end
       end
-      return arg.inject({}) do |result, (key, value)|
-        result[key] = (key == :attributes!) ? value :
-            validate_arg(value, result, key)
+
+      # Adding :order! key to keep correct order in SOAP elements.
+      if field_type and field_type.include?(:fields)
+        arg[:order!] =
+            generate_order_for_args(arg, field_type[:fields])
+      end
+
+      # Processing each key-value pair.
+      return arg.inject({}) do |result, (k, v)|
+        if (k == :attributes! or k == :order!)
+          result[k] = v
+        else
+          subfield = (field_type.nil?) ? nil :
+              get_field_by_name(field_type[:fields], k)
+          # Here we will give up if the field is unknown. For full validation
+          # we have to handle nil here.
+          subtype_name, subtype = if subfield and subfield.include?(:type)
+            subtype_name = subfield[:type]
+            subtype = (subtype_name.nil?) ? nil :
+                get_service_registry.get_type_signature(subtype_name)
+            [subtype_name, subtype]
+          end
+          # In case of non-default namespace, the children should be in
+          # overriden namespace but the node has to be in the default.
+          # We also have to fix order! list if we alter the key name.
+          new_key = if (subtype and subtype[:ns])
+            prefixed_key = prefix_key(k)
+            replace_item!(arg[:order!], k, prefixed_key)
+            prefixed_key
+          else
+            k
+          end
+          result[new_key] = validate_arg(v, result, k, subtype_name)
+        end
         result
       end
     end
 
+    # Replaces an item in an array with a different one into the same position.
+    def replace_item!(data, old_item, new_item)
+      data.map! {|item| (item == old_item) ? new_item : item}
+    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
+      add_attribute(parent, key, 'xsi:type', xsi_type)
+    end
+
+    # Adds Savon attribute for given node, key, name and value.
+    def add_attribute(node, key, name, value)
+      node[:attributes!] ||= {}
+      node[:attributes!][key] ||= {}
+      node[:attributes!][key][name] = value
+    end
+
+    # Prefixes default namespace.
+    def prefix_key(key)
+      return "%s:%s" % [DEFAULT_NAMESPACE, key.to_s.lower_camelcase]
     end
 
     # Executes each handler to generate SOAP headers.
     def set_headers(soap, args)
-      @headerhandler.each {|handler| handler.prepare_soap(soap, args)}
+      @headerhandler.each do |handler|
+        handler.prepare_request(@client.http, soap, args)
+      end
     end
 
     # Checks for errors in response and raises appropriate exception.
@@ -194,26 +275,22 @@ module AdsCommon
       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 = get_full_type_signature(field_definition[:type])
+      if sub_type and 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] = []
+            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
@@ -232,7 +309,8 @@ module AdsCommon
       # 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)
+          (field[:max_occurs] == :unbounded ||
+              (!field[:max_occurs].nil? and field[:max_occurs] > 1))
         result = arrayize(result)
       end
       return result
@@ -259,7 +337,7 @@ module AdsCommon
 
     # Makes sure object is an array.
     def arrayize(object)
-      return Array.new if object.nil?
+      return [] if object.nil?
       return object.is_a?(Array) ? object : [object]
     end
 
@@ -273,12 +351,12 @@ module AdsCommon
 
     # Returns all inherited fields of superclasses for given type.
     def implode_parent(data_type)
-      result = Array.new
-      if data_type and data_type[:base]
+      result = []
+      if 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]
+        result += implode_parent(parent_type)
       end
+      result += data_type[:fields]
       return result
     end
 
@@ -286,5 +364,15 @@ module AdsCommon
     def deep_copy(data)
       return Marshal.load(Marshal.dump(data))
     end
+
+    # Returns type signature with all inherited fields.
+    def get_full_type_signature(type_name)
+      result = (type_name.nil?) ? nil :
+          get_service_registry.get_type_signature(type_name)
+      if result and result[:base]
+        result[:fields] = implode_parent(result)
+      end
+      return result
+    end
   end
 end