google-ads-savon 1.0.0

data/lib/ads_savon/soap/request_builder.rb

@@ -0,0 +1,205 @@
+module GoogleAdsSavon
+  module SOAP
+
+    # = GoogleAdsSavon::SOAP::RequestBuilder
+    #
+    # GoogleAdsSavon::SOAP::RequestBuilder builds GoogleAdsSavon::SOAP::Request instances.
+    # The RequestBuilder is configured by the client that instantiates it.
+    # It uses the options set by the client to build an appropriate request.
+    class RequestBuilder
+
+      # Initialize a new +RequestBuilder+ with the given SOAP operation.
+      # The operation may be specified using a symbol or a string.
+      def initialize(operation, options = {})
+        @operation = operation
+        assign_options(options)
+      end
+
+      # Writer for the <tt>HTTPI::Request</tt> object.
+      attr_writer :http
+
+      # Writer for the <tt>GoogleAdsSavon::SOAP::XML</tt> object.
+      attr_writer :soap
+
+      # Writer for the <tt>Akami::WSSE</tt> object.
+      attr_writer :wsse
+
+      # Writer for the <tt>Wasabi::Document</tt> object.
+      attr_writer :wsdl
+
+      # Writer for the <tt>GoogleAdsSavon::Config</tt> object.
+      attr_writer :config
+
+      # Writer for the attributes of the SOAP input tag. Accepts a Hash.
+      attr_writer :attributes
+
+      # Writer for the namespace identifer of the <tt>GoogleAdsSavon::SOAP::XML</tt>
+      # object.
+      attr_writer :namespace_identifier
+
+      # Writer for the SOAP action of the <tt>GoogleAdsSavon::SOAP::XML</tt> object.
+      attr_writer :soap_action
+
+      # Reader for the operation of the request being built by the request builder.
+      attr_reader :operation
+
+      # Builds and returns a <tt>GoogleAdsSavon::SOAP::Request</tt> object. You may optionally
+      # pass a block to the method that will be run after the initial configuration of
+      # the dependencies. +self+ will be yielded to the block if the block accepts an
+      # argument.
+      def request(&post_configuration_block)
+        configure_dependencies
+
+        if post_configuration_block
+          # Only yield self to the block if our block takes an argument
+          args = [] and (args << self if post_configuration_block.arity == 1)
+          post_configuration_block.call(*args)
+        end
+
+        Request.new(config, http, soap)
+      end
+
+      # Returns the identifier for the default namespace. If an operation namespace
+      # identifier is defined for the current operation in the WSDL document, this
+      # namespace identifier is used. Otherwise, the +@namespace_identifier+ instance
+      # variable is used.
+      def namespace_identifier
+        if operation_namespace_defined_in_wsdl?
+          wsdl.operations[operation][:namespace_identifier].to_sym
+        else
+          @namespace_identifier
+        end
+      end
+
+      # Returns the namespace identifier to be used for the the SOAP input tag.
+      # If +@namespace_identifier+ is not +nil+, it will be returned. Otherwise, the
+      # default namespace identifier as returned by +namespace_identifier+ will be
+      # returned.
+      def input_namespace_identifier
+        @namespace_identifier || namespace_identifier
+      end
+
+      # Returns the default namespace to be used for the SOAP request. If a namespace
+      # is defined for the operation in the WSDL document, this namespace will be
+      # returned. Otherwise, the default WSDL document namespace will be returned.
+      def namespace
+        if operation_namespace_defined_in_wsdl?
+          wsdl.parser.namespaces[namespace_identifier.to_s]
+        else
+          wsdl.namespace
+        end
+      end
+
+      # Returns true if the operation's namespace is defined within the WSDL
+      # document.
+      def operation_namespace_defined_in_wsdl?
+        return false unless wsdl.document?
+        (operation = wsdl.operations[self.operation]) && operation[:namespace_identifier]
+      end
+
+      # Returns the SOAP action. If +@soap_action+ has been defined, this will
+      # be returned. Otherwise, if there is a WSDL document defined, the SOAP
+      # action corresponding to the operation will be returned. Failing this,
+      # the operation name will be used to form the SOAP action.
+      def soap_action
+        return @soap_action if @soap_action
+
+        if wsdl.document?
+          wsdl.soap_action(operation.to_sym)
+        else
+          Gyoku::XMLKey.create(operation).to_sym
+        end
+      end
+
+      # Returns the SOAP operation input tag. If there is a WSDL document defined,
+      # and the operation's input tag is defined in the document, this will be
+      # returned. Otherwise, the operation name will be used to form the input tag.
+      def soap_input_tag
+        if wsdl.document? && (input = wsdl.soap_input(operation.to_sym))
+          input
+        else
+          Gyoku::XMLKey.create(operation)
+        end
+      end
+
+      # Changes the body of the SOAP request to +body+.
+      def body=(body)
+        soap.body = body
+      end
+
+      # Returns the body of the SOAP request.
+      def body
+        soap.body
+      end
+
+      # Returns the attributes of the SOAP input tag. Defaults to
+      # an empty Hash.
+      def attributes
+        @attributes ||= {}
+      end
+
+      # Returns the <tt>GoogleAdsSavon::Config</tt> object for the request. Defaults
+      # to a clone of <tt>GoogleAdsSavon.config</tt>.
+      def config
+        @config ||= GoogleAdsSavon.config.clone
+      end
+
+      # Returns the <tt>HTTPI::Request</tt> object.
+      def http
+        @http ||= HTTPI::Request.new
+      end
+
+      # Returns the <tt>SOAP::XML</tt> object.
+      def soap
+        @soap ||= XML.new(config)
+      end
+
+      # Returns the <tt>Wasabi::Document</tt> object.
+      def wsdl
+        @wsdl ||= Wasabi::Document.new
+      end
+
+      # Returns the <tt>Akami::WSSE</tt> object.
+      def wsse
+        @wsse ||= Akami.wsse
+      end
+
+      private
+
+      def configure_dependencies
+        soap.endpoint = wsdl.endpoint
+        soap.element_form_default = wsdl.element_form_default
+        soap.wsse = wsse
+
+        soap.namespace = namespace
+        soap.namespace_identifier = namespace_identifier
+
+        add_wsdl_namespaces_to_soap
+        add_wsdl_types_to_soap
+
+        soap.input = [input_namespace_identifier, soap_input_tag.to_sym, attributes]
+
+        http.headers["SOAPAction"] = %{"#{soap_action}"}
+      end
+
+      def add_wsdl_namespaces_to_soap
+        wsdl.type_namespaces.each do |path, uri|
+          soap.use_namespace(path, uri)
+        end
+      end
+
+      def add_wsdl_types_to_soap
+        wsdl.type_definitions.each do |path, type|
+          soap.types[path] = type
+        end
+      end
+
+      def assign_options(options)
+        options.each do |option, value|
+          send(:"#{option}=", value) if value
+        end
+      end
+
+    end
+  end
+end

data/lib/ads_savon/soap/response.rb

@@ -0,0 +1,130 @@
+require "ads_savon/soap/xml"
+require "ads_savon/soap/fault"
+require "ads_savon/soap/invalid_response_error"
+require "ads_savon/http/error"
+
+module GoogleAdsSavon
+  module SOAP
+
+    # = GoogleAdsSavon::SOAP::Response
+    #
+    # Represents the SOAP response and contains the HTTP response.
+    class Response
+
+      # Expects an <tt>HTTPI::Response</tt> and handles errors.
+      def initialize(config, response)
+        self.config = config
+        self.http = response
+        raise_errors if config.raise_errors
+      end
+
+      attr_accessor :http, :config
+
+      # Returns whether the request was successful.
+      def success?
+        !soap_fault? && !http_error?
+      end
+
+      # Returns whether there was a SOAP fault.
+      def soap_fault?
+        soap_fault.present?
+      end
+
+      # Returns the <tt>GoogleAdsSavon::SOAP::Fault</tt>.
+      def soap_fault
+        @soap_fault ||= Fault.new http
+      end
+
+      # Returns whether there was an HTTP error.
+      def http_error?
+        http_error.present?
+      end
+
+      # Returns the <tt>GoogleAdsSavon::HTTP::Error</tt>.
+      def http_error
+        @http_error ||= HTTP::Error.new http
+      end
+
+      # Shortcut accessor for the SOAP response body Hash.
+      def [](key)
+        body[key]
+      end
+
+      # Returns the SOAP response header as a Hash.
+      def header
+        if !hash.has_key? :envelope
+          raise GoogleAdsSavon::SOAP::InvalidResponseError, "Unable to parse response body '#{to_xml}'"
+        end
+        hash[:envelope][:header]
+      end
+
+      # Returns the SOAP response body as a Hash.
+      def body
+        if !hash.has_key? :envelope
+          raise GoogleAdsSavon::SOAP::InvalidResponseError, "Unable to parse response body '#{to_xml}'"
+        end
+        hash[:envelope][:body]
+      end
+
+      alias to_hash body
+
+      # Traverses the SOAP response body Hash for a given +path+ of Hash keys and returns
+      # the value as an Array. Defaults to return an empty Array in case the path does not
+      # exist or returns nil.
+      def to_array(*path)
+        result = path.inject body do |memo, key|
+          return [] unless memo[key]
+          memo[key]
+        end
+
+        result.kind_of?(Array) ? result.compact : [result].compact
+      end
+
+      # Returns the complete SOAP response XML without normalization.
+      def hash
+        @hash ||= nori.parse(to_xml)
+      end
+
+      # Returns the SOAP response XML.
+      def to_xml
+        http.body
+      end
+
+      # Returns a <tt>Nokogiri::XML::Document</tt> for the SOAP response XML.
+      def doc
+        @doc ||= Nokogiri::XML(to_xml)
+      end
+
+      # Returns an Array of <tt>Nokogiri::XML::Node</tt> objects retrieved with the given +path+.
+      # Automatically adds all of the document's namespaces unless a +namespaces+ hash is provided.
+      def xpath(path, namespaces = nil)
+        doc.xpath(path, namespaces || xml_namespaces)
+      end
+
+      private
+
+      def raise_errors
+        raise soap_fault if soap_fault?
+        raise http_error if http_error?
+      end
+
+      def xml_namespaces
+        @xml_namespaces ||= doc.collect_namespaces
+      end
+
+      def nori
+        return @nori if @nori
+
+        nori_options = {
+          :strip_namespaces      => true,
+          :convert_tags_to       => lambda { |tag| tag.snakecase.to_sym },
+          :advanced_typecasting  => false
+        }
+
+        non_nil_nori_options = nori_options.reject { |_, value| value.nil? }
+        @nori = Nori.new(non_nil_nori_options)
+      end
+
+    end
+  end
+end

data/lib/ads_savon/soap/xml.rb

@@ -0,0 +1,252 @@
+require "builder"
+require "gyoku"
+require "rexml/document"
+require "nori"
+
+require "ads_savon/soap"
+
+module GoogleAdsSavon
+  module SOAP
+
+    # = GoogleAdsSavon::SOAP::XML
+    #
+    # Represents the SOAP request XML. Contains various global and per request/instance settings
+    # like the SOAP version, header, body and namespaces.
+    class XML
+
+      # XML Schema Type namespaces.
+      SCHEMA_TYPES = {
+        "xmlns:xsd" => "http://www.w3.org/2001/XMLSchema",
+        "xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance"
+      }
+
+      # Expects a +config+ object.
+      def initialize(config)
+        self.config = config
+      end
+
+      attr_accessor :config
+
+      # Accessor for the SOAP +input+ tag.
+      attr_accessor :input
+
+      # Accessor for the SOAP +endpoint+.
+      attr_accessor :endpoint
+
+      # Sets the SOAP +version+.
+      def version=(version)
+        raise ArgumentError, "Invalid SOAP version: #{version}" unless SOAP::VERSIONS.include? version
+        @version = version
+      end
+
+      # Returns the SOAP +version+. Defaults to <tt>GoogleAdsSavon.config.soap_version</tt>.
+      def version
+        @version ||= config.soap_version
+      end
+
+      # Sets the SOAP +header+ Hash.
+      attr_writer :header
+
+      # Returns the SOAP +header+. Defaults to an empty Hash.
+      def header
+        @header ||= config.soap_header.nil? ? {} : config.soap_header
+      end
+
+      # Sets the SOAP envelope namespace.
+      attr_writer :env_namespace
+
+      # Returns the SOAP envelope namespace. Uses the global namespace if set Defaults to :env.
+      def env_namespace
+        @env_namespace ||= config.env_namespace.nil? ? :env : config.env_namespace
+      end
+
+      # Sets the +namespaces+ Hash.
+      attr_writer :namespaces
+
+      # Returns the +namespaces+. Defaults to a Hash containing the SOAP envelope namespace.
+      def namespaces
+        @namespaces ||= begin
+          key = ["xmlns"]
+          key << env_namespace if env_namespace && env_namespace != ""
+          { key.join(":") => SOAP::NAMESPACE[version] }
+        end
+      end
+
+      def namespace_by_uri(uri)
+        namespaces.each do |candidate_identifier, candidate_uri|
+          return candidate_identifier.gsub(/^xmlns:/, '') if candidate_uri == uri
+        end
+        nil
+      end
+
+      def used_namespaces
+        @used_namespaces ||= {}
+      end
+
+      def use_namespace(path, uri)
+        @internal_namespace_count ||= 0
+
+        unless identifier = namespace_by_uri(uri)
+          identifier = "ins#{@internal_namespace_count}"
+          namespaces["xmlns:#{identifier}"] = uri
+          @internal_namespace_count += 1
+        end
+
+        used_namespaces[path] = identifier
+      end
+
+      def types
+        @types ||= {}
+      end
+
+      # Sets the default namespace identifier.
+      attr_writer :namespace_identifier
+
+      # Returns the default namespace identifier.
+      def namespace_identifier
+        @namespace_identifier ||= :wsdl
+      end
+
+      # Accessor for whether all local elements should be namespaced.
+      attr_accessor :element_form_default
+
+      # Accessor for the default namespace URI.
+      attr_accessor :namespace
+
+      # Accessor for the <tt>GoogleAdsSavon::WSSE</tt> object.
+      attr_accessor :wsse
+
+      def signature?
+        wsse.respond_to?(:signature?) && wsse.signature?
+      end
+
+      # Returns the SOAP request encoding. Defaults to "UTF-8".
+      def encoding
+        @encoding ||= "UTF-8"
+      end
+
+      # Sets the SOAP request encoding.
+      attr_writer :encoding
+
+      # Accepts a +block+ and yields a <tt>Builder::XmlMarkup</tt> object to let you create
+      # custom body XML.
+      def body
+        @body = yield builder(nil) if block_given?
+        @body
+      end
+
+      # Sets the SOAP +body+. Expected to be a Hash that can be translated to XML via `Gyoku.xml`
+      # or any other Object responding to to_s.
+      attr_writer :body
+
+      # Accepts a +block+ and yields a <tt>Builder::XmlMarkup</tt> object to let you create
+      # a completely custom XML.
+      def xml(directive_tag = :xml, attrs = {})
+        @xml = yield builder(directive_tag, attrs) if block_given?
+      end
+
+      # Accepts an XML String and lets you specify a completely custom request body.
+      attr_writer :xml
+
+      # Returns the XML for a SOAP request.
+      def to_xml(clear_cache = false)
+        if clear_cache
+          @xml = nil
+          @header_for_xml = nil
+        end
+
+        @xml ||= tag(builder, :Envelope, complete_namespaces) do |xml|
+          tag(xml, :Header) { xml << header_for_xml } unless header_for_xml.empty?
+
+          # TODO: Maybe there should be some sort of plugin architecture where
+          #       classes like WSSE::Signature can hook into this process.
+          body_attributes = (signature? ? wsse.signature.body_attributes : {})
+
+          if input.nil?
+            tag(xml, :Body, body_attributes)
+          else
+            tag(xml, :Body, body_attributes) { xml.tag!(*add_namespace_to_input) { xml << body_to_xml } }
+          end
+        end
+      end
+
+      private
+
+      # Returns a new <tt>Builder::XmlMarkup</tt> object.
+      def builder(directive_tag = :xml, attrs = { :encoding => encoding })
+        builder = Builder::XmlMarkup.new
+        builder.instruct!(directive_tag, attrs) if directive_tag
+        builder
+      end
+
+      # Expects a builder +xml+ instance, a tag +name+ and accepts optional +namespaces+
+      # and a block to create an XML tag.
+      def tag(xml, name, namespaces = {}, &block)
+        if env_namespace && env_namespace != ""
+          xml.tag! env_namespace, name, namespaces, &block
+        else
+          xml.tag! name, namespaces, &block
+        end
+      end
+
+      # Returns the complete Hash of namespaces.
+      def complete_namespaces
+        defaults = SCHEMA_TYPES.dup
+        defaults["xmlns:#{namespace_identifier}"] = namespace if namespace
+        defaults.merge namespaces
+      end
+
+      # Returns the SOAP header as an XML String.
+      def header_for_xml
+        @header_for_xml ||= (Hash === header ? Gyoku.xml(header) : header) + wsse_header
+      end
+
+      # Returns the WSSE header or an empty String in case WSSE was not set.
+      def wsse_header
+        wsse.respond_to?(:to_xml) ? wsse.to_xml : ""
+      end
+
+      # Returns the SOAP body as an XML String.
+      def body_to_xml
+        return body.to_s unless body.kind_of? Hash
+        body_to_xml = element_form_default == :qualified ? add_namespaces_to_body(body) : body
+        Gyoku.xml body_to_xml, :element_form_default => element_form_default, :namespace => namespace_identifier
+      end
+
+      def add_namespaces_to_body(hash, path = [input[1].to_s])
+        return unless hash
+        return hash.map { |value| add_namespaces_to_body(value, path) } if hash.kind_of?(Array)
+        return hash.to_s unless hash.kind_of? Hash
+
+        hash.inject({}) do |newhash, (key, value)|
+          camelcased_key = Gyoku::XMLKey.create(key)
+          newpath = path + [camelcased_key]
+
+          if used_namespaces[newpath]
+            newhash.merge(
+              "#{used_namespaces[newpath]}:#{camelcased_key}" =>
+                add_namespaces_to_body(value, types[newpath] ? [types[newpath]] : newpath)
+            )
+          else
+            add_namespaces_to_values(value, path) if key == :order!
+            newhash.merge(key => value)
+          end
+        end
+      end
+
+      def add_namespace_to_input
+        return input.compact unless used_namespaces[[input[1].to_s]]
+        [used_namespaces[[input[1].to_s]], input[1], input[2]]
+      end
+
+      def add_namespaces_to_values(values, path)
+        values.collect! { |value|
+          camelcased_value = Gyoku::XMLKey.create(value)
+          namespace_path = path + [camelcased_value.to_s]
+          namespace = used_namespaces[namespace_path]
+          "#{namespace.blank? ? '' : namespace + ":"}#{camelcased_value}"
+        }
+      end
+    end
+  end
+end