savon 0.7.9 → 0.8.0.beta.1

data/autotest/discover.rb

@@ -0,0 +1 @@
+Autotest.add_discovery { "rspec2" }

data/lib/savon.rb

@@ -1,35 +1,14 @@
-module Savon
+require "savon/version"
+require "savon/global"
+require "savon/client"
 
-  # Raised in case of an HTTP error.
-  class HTTPError < StandardError; end
+module Savon
+  extend Global
 
-  # Raised in case of a SOAP fault.
-  class SOAPFault < StandardError; end
+  # Yields this module to a given +block+. Please refer to the
+  # <tt>Savon::Global</tt> module for configuration options.
+  def self.configure
+    yield self if block_given?
+  end
 
 end
-
-# standard libs
-require "logger"
-require "net/https"
-require "base64"
-require "digest/sha1"
-require "rexml/document"
-require "stringio"
-require "zlib"
-require "cgi"
-
-# gem dependencies
-require "builder"
-require "crack/xml"
-
-# core files
-require "savon/core_ext"
-require "savon/wsse"
-require "savon/soap"
-require "savon/logger"
-require "savon/request"
-require "savon/response"
-require "savon/wsdl_stream"
-require "savon/wsdl"
-require "savon/client"
-require "savon/version"

data/lib/savon/client.rb

@@ -1,130 +1,148 @@
+require "httpi/request"
+require "savon/soap/xml"
+require "savon/soap/request"
+require "savon/soap/response"
+require "savon/wsdl/document"
+require "savon/wsse"
+
 module Savon
 
   # = Savon::Client
   #
   # Savon::Client is the main object for connecting to a SOAP service. It includes methods to access
-  # both the Savon::WSDL and Savon::Request object.
-  #
-  # == Instantiation
-  #
-  # Depending on whether you aim to use Savon with or without Savon::WSDL, you need to instantiate
-  # Savon::Client by passing in the WSDL or SOAP endpoint.
-  #
-  # Client instance with a WSDL endpoint:
-  #
-  #   client = Savon::Client.new "http://example.com/UserService?wsdl"
-  #
-  # Client instance with a SOAP endpoint (for using Savon without a WSDL):
-  #
-  #   client = Savon::Client.new "http://example.com/UserService"
-  #
-  # It is recommended to not use Savon::WSDL for production. Please take a look at the Documentation
-  # for Savon::WSDL for more information about how to disable it.
-  #
-  # == Using a proxy server
-  #
-  # You can specify the URI to a proxy server via optional hash arguments.
-  #
-  #   client = Savon::Client.new "http://example.com/UserService?wsdl", :proxy => "http://proxy.example.com"
-  #
-  # == Forcing a particular SOAP endpoint
-  #
-  # In case you don't want to use the SOAP endpoint specified in the WSDL, you can tell Savon to use
-  # another SOAP endpoint.
-  #
-  #   client = Savon::Client.new "http://example.com/UserService?wsdl", :soap_endpoint => "http://localhost/UserService"
-  #
-  # == Gzipped SOAP requests
-  #
-  # Sending gzipped SOAP requests can be specified per client instance.
-  #
-  #   client = Savon::Client.new "http://example.com/UserService?wsdl", :gzip => true
-  #
-  # == Savon::WSDL
-  #
-  # You can access Savon::WSDL via:
-  #
-  #   client.wsdl
-  #
-  # == Savon::Request
-  #
-  # You can also access Savon::Request via:
-  #
-  #   client.request
+  # both the Savon::WSDL::Document and HTTPI::Request object.
   class Client
 
-    # Expects a SOAP +endpoint+ string. Also accepts a Hash of +options+.
+    # Initializes the Savon::Client for a SOAP service. Accepts a +block+ which is evaluated in the
+    # context of this object to let you access the +wsdl+, +http+, and +wsse+ methods.
+    #
+    # == Examples
     #
-    # ==== Options:
+    #   # Using a remote WSDL
+    #   client = Savon::Client.new { wsdl.document = "http://example.com/UserService?wsdl" }
     #
-    # [proxy]  the proxy server to use
-    # [gzip]  whether to gzip SOAP requests
-    # [soap_endpoint]  force to use this SOAP endpoint
-    def initialize(endpoint, options = {})
-      soap_endpoint = options.delete(:soap_endpoint)
-      @request = Request.new endpoint, options
-      @wsdl = WSDL.new @request, soap_endpoint
+    #   # Using a local WSDL
+    #   client = Savon::Client.new { wsdl.document = "../wsdl/user_service.xml" }
+    #
+    #   # Directly accessing a SOAP endpoint
+    #   client = Savon::Client.new do
+    #     wsdl.endpoint = "http://example.com/UserService"
+    #     wsdl.namespace = "http://users.example.com"
+    #   end
+    def initialize(&block)
+      process 1, &block if block
+      wsdl.request = http
     end
 
-    # Returns the Savon::WSDL.
-    attr_reader :wsdl
+    # Returns the <tt>Savon::WSDL::Document</tt>.
+    def wsdl
+      @wsdl ||= WSDL::Document.new
+    end
 
-    # Returns the Savon::Request.
-    attr_reader :request
+    # Returns the <tt>HTTPI::Request</tt>.
+    def http
+      @http ||= HTTPI::Request.new
+    end
 
-    # Returns +true+ for available methods and SOAP actions.
-    def respond_to?(method)
-      return true if @wsdl.respond_to? method
-      super
+    # Returns the <tt>Savon::WSSE</tt> object.
+    def wsse
+      @wsse ||= WSSE.new
     end
 
-    # Same as method_missing. Workaround for SOAP actions that method_missing does not catch
-    # because the method does exist.
-    def call(method, *args, &block)
-      method_missing method, *args, &block
+    # Returns the <tt>Savon::SOAP::XML</tt> object. Please notice, that this object is only available
+    # in a block given to <tt>Savon::Client#request</tt>. A new instance of this object is created
+    # per SOAP request.
+    attr_reader :soap
+
+    # Executes a SOAP request for a given SOAP action. Accepts a +block+ which is evaluated in the
+    # context of this object to let you access the +soap+, +wsdl+, +http+ and +wsse+ methods.
+    #
+    # == Examples
+    #
+    #   # Calls a "getUser" SOAP action with the payload of "<userId>123</userId>"
+    #   client.request(:get_user) { soap.body = { :user_id => 123 } }
+    #
+    #   # Prefixes the SOAP input tag with a given namespace: "<wsdl:GetUser>...</wsdl:GetUser>"
+    #   client.request(:wsdl, "GetUser") { soap.body = { :user_id => 123 } }
+    #
+    #   # SOAP input tag with attributes: <getUser xmlns:wsdl="http://example.com">...</getUser>"
+    #   client.request(:get_user, "xmlns:wsdl" => "http://example.com")
+    def request(*args, &block)
+      raise ArgumentError, "Savon::Client#request requires at least one argument" if args.empty?
+      
+      self.soap = SOAP::XML.new
+      preconfigure extract_options(args)
+      process &block if block
+      soap.wsse = wsse
+      
+      SOAP::Request.new(http, soap).response
     end
 
   private
 
-    # Dispatches requests to SOAP actions matching a given +method+ name.
-    def method_missing(method, *args, &block) #:doc:
-      soap_action = soap_action_from method.to_s
-      super unless @wsdl.respond_to? soap_action
+    # Writer for the <tt>Savon::SOAP::XML</tt> object.
+    attr_writer :soap
 
-      setup_objects *@wsdl.operation_from(soap_action), &block
-      Response.new @request.soap(@soap)
+    # Accessor for the original self of a given block.
+    attr_accessor :original_self
+
+    # Expects an Array of +args+ and returns an Array containing the namespace (might be +nil+),
+    # the SOAP input and a Hash of attributes for the input tag (which might be empty).
+    def extract_options(args)
+      attributes = Hash === args.last ? args.pop : {}
+      namespace = args.size > 1 ? args.shift.to_sym : nil
+      input = args.first
+      
+      [namespace, input, attributes]
     end
 
-    # Sets whether to use Savon::WSDL by a given +method+ name and returns the original method name
-    # without exclamation marks.
-    def soap_action_from(method)
-      @wsdl.enabled = !method.ends_with?("!")
+    # Expects and Array of +options+ and preconfigures the system.
+    def preconfigure(options)
+      soap.endpoint = wsdl.endpoint
+      soap.namespace_identifier = options[0]
+      soap.namespace = wsdl.namespace
+      soap.body = options[2].delete :body
+      
+      set_soap_action options[1]
+      set_soap_input *options
+    end
+
+    # Expects an +input+ and sets the +SOAPAction+ HTTP headers.
+    def set_soap_action(input)
+      soap_action = wsdl.soap_action input.to_sym
+      soap_action ||= input.kind_of?(String) ? input : input.to_s.lower_camelcase
+      http.headers["SOAPAction"] = %{"#{soap_action}"}
+    end
+
+    # Expects a +namespace+, +input+ and +attributes+ and sets the SOAP input.
+    def set_soap_input(namespace, input, attributes)
+      new_input = wsdl.soap_input input.to_sym
+      new_input ||= input.kind_of?(String) ? input.to_sym : input.to_s.lower_camelcase.to_sym
+      soap.input = [namespace, new_input, attributes].compact
+    end
 
-      method.chop! if method.ends_with?("!")
-      method.to_sym
+    # Processes a given +block+. Yields objects if the block expects any arguments.
+    # Otherwise evaluates the block in the context of this object.
+    def process(offset = 0, &block)
+      block.arity > 0 ? yield_objects(offset, &block) : evaluate(&block)
     end
 
-    # Returns the SOAP endpoint.
-    def soap_endpoint
-      @wsdl.enabled? ? @wsdl.soap_endpoint : @request.endpoint
+    # Yields a number of objects to a given +block+ depending on how many arguments
+    # the block is expecting.
+    def yield_objects(offset, &block)
+      yield *[soap, wsdl, http, wsse][offset, block.arity]
     end
 
-    # Expects a SOAP operation Hash and sets up Savon::SOAP and Savon::WSSE. Yields them to a given
-    # +block+ in case one was given.
-    def setup_objects(action, input, &block)
-      @soap, @wsse = SOAP.new(action, input, soap_endpoint), WSSE.new
-      yield_objects &block if block
-      @soap.namespaces["xmlns:wsdl"] ||= @wsdl.namespace_uri if @wsdl.enabled?
-      @soap.wsse = @wsse
+    # Evaluates a given +block+ inside this object. Stores the original block binding.
+    def evaluate(&block)
+      self.original_self = eval "self", block.binding
+      instance_eval &block
     end
 
-    # Yields either Savon::SOAP or Savon::SOAP and Savon::WSSE to a given +block+, depending on
-    # the number of arguments expected by the block.
-    def yield_objects(&block)
-      case block.arity
-        when 1 then yield @soap
-        when 2 then yield @soap, @wsse
-      end
+    # Handles calls to undefined methods by delegating to the original block binding.
+    def method_missing(method, *args, &block)
+      super unless original_self
+      original_self.send method, *args, &block
     end
 
   end

data/lib/savon/core_ext/array.rb

@@ -1,31 +1,45 @@
-class Array
+require "builder"
 
-  # Translates the Array into SOAP compatible XML. See: Hash.to_soap_xml.
-  def to_soap_xml(key, escape_xml = true, attributes = {})
-    xml = Builder::XmlMarkup.new
+require "savon/core_ext/object"
+require "savon/core_ext/string"
+require "savon/core_ext/hash"
+require "savon/core_ext/datetime"
 
-    each_with_index do |item, index|
-      attrs = tag_attributes attributes, index
-      case item
-        when Hash then xml.tag!(key, attrs) { xml << item.to_soap_xml }
-        else           xml.tag!(key, attrs) { xml << (escape_xml ? item.to_soap_value : item.to_soap_value!) }
-      end
-    end
+module Savon
+  module CoreExt
+    module Array
 
-    xml.target!
-  end
+      # Translates the Array into SOAP compatible XML. See: Hash.to_soap_xml.
+      def to_soap_xml(key, escape_xml = true, attributes = {})
+        xml = Builder::XmlMarkup.new
+        
+        each_with_index do |item, index|
+          attrs = tag_attributes attributes, index
+          case item
+            when ::Hash   then xml.tag!(key, attrs) { xml << item.to_soap_xml }
+            when NilClass then xml.tag!(key, "xsi:nil" => "true")
+            else               xml.tag!(key, attrs) { xml << (escape_xml ? item.to_soap_value : item.to_soap_value!) }
+          end
+        end
+        
+        xml.target!
+      end
 
-private
+    private
 
-  # Takes a Hash of +attributes+ and the +index+ for which to return attributes
-  # for duplicate tags.
-  def tag_attributes(attributes, index)
-    return {} if attributes.empty?
+      # Takes a Hash of +attributes+ and the +index+ for which to return attributes
+      # for duplicate tags.
+      def tag_attributes(attributes, index)
+        return {} if attributes.empty?
+        
+        attributes.inject({}) do |hash, (key, value)|
+          value = value[index] if value.kind_of? ::Array
+          hash.merge key => value
+        end
+      end
 
-    attributes.inject({}) do |hash, (key, value)|
-      value = value[index] if value.kind_of? Array
-      hash.merge key => value
     end
   end
+end
 
-end
+Array.send :include, Savon::CoreExt::Array

data/lib/savon/core_ext/datetime.rb

@@ -1,10 +1,19 @@
-class DateTime
+require "date"
+require "savon/soap"
 
-  # Returns the DateTime as an xs:dateTime formatted String.
-  def to_soap_value
-    strftime Savon::SOAP::DateTimeFormat
-  end
+module Savon
+  module CoreExt
+    module DateTime
+
+      # Returns the DateTime as an xs:dateTime formatted String.
+      def to_soap_value
+        strftime Savon::SOAP::DateTimeFormat
+      end
 
-  alias_method :to_soap_value!, :to_soap_value
+      alias_method :to_soap_value!, :to_soap_value
 
+    end
+  end
 end
+
+DateTime.send :include, Savon::CoreExt::DateTime

data/lib/savon/core_ext/hash.rb

@@ -1,107 +1,135 @@
-class Hash
+require "builder"
 
-  # Returns the values from the soap:Body element or an empty Hash in case the soap:Body tag could
-  # not be found.
-  def find_soap_body
-    envelope = self[keys.first] || {}
-    body_key = envelope.keys.find { |key| /.+:Body/ =~ key } rescue nil
-    body_key ? envelope[body_key].map_soap_response : {}
-  end
-
-  # Translates the Hash into SOAP request compatible XML.
-  #
-  #   { :find_user => { :id => 123, "wsdl:Key" => "api" } }.to_soap_xml
-  #   # => "<findUser><id>123</id><wsdl:Key>api</wsdl:Key></findUser>"
-  #
-  # ==== Mapping
-  #
-  # * Hash keys specified as Symbols are converted to lowerCamelCase Strings
-  # * Hash keys specified as Strings are not converted and may contain namespaces
-  # * DateTime values are converted to xs:dateTime Strings
-  # * Objects responding to to_datetime (except Strings) are converted to xs:dateTime Strings
-  # * TrueClass and FalseClass objects are converted to "true" and "false" Strings
-  # * All other objects are expected to be converted to Strings using to_s
-  #
-  # An example:
-  #
-  #   { :magic_request => {
-  #       :perform_move => true,
-  #       "perform_at" => DateTime.new(2010, 11, 22, 11, 22, 33)
-  #     }
-  #   }.to_soap_xml
-  #
-  #   <magicRequest>
-  #     <performMove>true</performMove>
-  #     <perform_at>2012-06-11T10:42:21</perform_at>
-  #   </magicRequest>
-  #
-  # ==== Escaped XML values
-  #
-  # By default, special characters in XML String values are escaped.
-  #
-  # ==== Fixed order of XML tags
-  #
-  # In case your service requires the tags to be in a specific order (parameterOrder), you have two
-  # options. The first is to specify your body as an XML string. The second is to specify the order
-  # through an additional array stored under the +:order!+ key.
-  #
-  #   { :name => "Eve", :id => 123, :order! => [:id, :name] }.to_soap_xml
-  #   # => "<id>123</id><name>Eve</name>"
-  #
-  # ==== XML attributes
-  #
-  # If you need attributes, you could either go with an XML string or add another hash under the
-  # +:attributes!+ key.
-  #
-  #   { :person => "Eve", :attributes! => { :person => { :id => 666 } } }.to_soap_xml
-  #   # => '<person id="666">Eve</person>'
-  def to_soap_xml
-    xml = Builder::XmlMarkup.new
-    attributes = delete(:attributes!) || {}
+require "savon"
+require "savon/core_ext/object"
+require "savon/core_ext/string"
+require "savon/core_ext/symbol"
+require "savon/core_ext/array"
+require "savon/core_ext/datetime"
 
-    order.each do |key|
-      attrs = attributes[key] || {}
-      value = self[key]
-      escape_xml = key.to_s[-1, 1] != "!"
-      key = key.to_soap_key
+module Savon
+  module CoreExt
+    module Hash
 
-      case value
-        when Array then xml << value.to_soap_xml(key, escape_xml, attrs)
-        when Hash  then xml.tag!(key, attrs) { xml << value.to_soap_xml }
-        else            xml.tag!(key, attrs) { xml << (escape_xml ? value.to_soap_value : value.to_soap_value!) }
+      # Returns the values from the soap:Body element or an empty Hash in case the soap:Body tag could
+      # not be found.
+      def find_soap_body
+        envelope = self[keys.first] || {}
+        body_key = envelope.keys.find { |key| /.+:Body/ =~ key } rescue nil
+        body_key ? envelope[body_key].map_soap_response : {}
       end
-    end
 
-    xml.target!
-  end
+      # Translates the Hash into SOAP request compatible XML.
+      #
+      #   { :find_user => { :id => 123, "wsdl:Key" => "api" } }.to_soap_xml
+      #   # => "<findUser><id>123</id><wsdl:Key>api</wsdl:Key></findUser>"
+      #
+      # ==== Mapping
+      #
+      # * Hash keys specified as Symbols are converted to lowerCamelCase Strings
+      # * Hash keys specified as Strings are not converted and may contain namespaces
+      # * DateTime values are converted to xs:dateTime Strings
+      # * Objects responding to to_datetime (except Strings) are converted to xs:dateTime Strings
+      # * TrueClass and FalseClass objects are converted to "true" and "false" Strings
+      # * All other objects are expected to be converted to Strings using to_s
+      #
+      # An example:
+      #
+      #   { :magic_request => {
+      #       :perform_move => true,
+      #       "perform_at" => DateTime.new(2010, 11, 22, 11, 22, 33)
+      #     }
+      #   }.to_soap_xml
+      #
+      #   <magicRequest>
+      #     <performMove>true</performMove>
+      #     <perform_at>2012-06-11T10:42:21</perform_at>
+      #   </magicRequest>
+      #
+      # ==== Escaped XML values
+      #
+      # By default, special characters in XML String values are escaped.
+      #
+      # ==== Fixed order of XML tags
+      #
+      # In case your service requires the tags to be in a specific order (parameterOrder), you have two
+      # options. The first is to specify your body as an XML string. The second is to specify the order
+      # through an additional array stored under the +:order!+ key.
+      #
+      #   { :name => "Eve", :id => 123, :order! => [:id, :name] }.to_soap_xml
+      #   # => "<id>123</id><name>Eve</name>"
+      #
+      # ==== XML attributes
+      #
+      # If you need attributes, you could either go with an XML string or add another hash under the
+      # +:attributes!+ key.
+      #
+      #   { :person => "Eve", :attributes! => { :person => { :id => 666 } } }.to_soap_xml
+      #   # => '<person id="666">Eve</person>'
+      def to_soap_xml
+        xml = Builder::XmlMarkup.new
+        attributes = delete(:attributes!) || {}
+        
+        order.each do |key|
+          attrs = attributes[key] || {}
+          value = self[key]
+          escape_xml = key.to_s[-1, 1] != "!"
+          key = key.to_soap_key
+          
+          case value
+            when ::Array  then xml << value.to_soap_xml(key, escape_xml, attrs)
+            when ::Hash   then xml.tag!(key, attrs) { xml << value.to_soap_xml }
+            when NilClass then xml.tag!(key, "xsi:nil" => "true")
+            else               xml.tag!(key, attrs) { xml << (escape_xml ? value.to_soap_value : value.to_soap_value!) }
+          end
+        end
 
-  # Maps keys and values of a Hash created from SOAP response XML to more convenient Ruby Objects.
-  def map_soap_response
-    inject({}) do |hash, (key, value)|
-      value = case value
-        when Hash   then value["xsi:nil"] ? nil : value.map_soap_response
-        when Array  then value.map { |val| val.map_soap_response rescue val }
-        when String then value.map_soap_response
+        xml.target!
       end
 
-      hash.merge key.strip_namespace.snakecase.to_sym => value
-    end
-  end
-
-private
+      # Maps keys and values of a Hash created from SOAP response XML to more convenient Ruby Objects.
+      def map_soap_response
+        inject({}) do |hash, (key, value)|
+          value = case value
+            when ::Hash   then value["xsi:nil"] ? nil : value.map_soap_response
+            when ::Array  then value.map { |val| val.map_soap_response rescue val }
+            when ::String then value.map_soap_response
+          end
+          
+          new_key = if Savon.strip_namespaces?
+            key.strip_namespace.snakecase.to_sym
+          else
+            key.snakecase
+          end
+          
+          if hash[new_key] # key already exists, value should be added as an Array
+            hash[new_key] = [hash[new_key], value].flatten
+            result = hash
+          else
+            result = hash.merge new_key => value
+          end
+          result
+        end
+      end
 
-  # Deletes and returns an Array of keys stored under the :order! key. Defaults to return the actual
-  # keys of this Hash if no :order! key could be found. Raises an ArgumentError in case the :order!
-  # Array does not match the Hash keys.
-  def order
-    order = delete :order!
-    order = keys unless order.kind_of? Array
+    private
 
-    missing, spurious = keys - order, order - keys
-    raise ArgumentError, "Missing elements in :order! #{missing.inspect}" unless missing.empty?
-    raise ArgumentError, "Spurious elements in :order! #{spurious.inspect}" unless spurious.empty?
+      # Deletes and returns an Array of keys stored under the :order! key. Defaults to return the actual
+      # keys of this Hash if no :order! key could be found. Raises an ArgumentError in case the :order!
+      # Array does not match the Hash keys.
+      def order
+        order = delete :order!
+        order = keys unless order.kind_of? ::Array
+        
+        missing, spurious = keys - order, order - keys
+        raise ArgumentError, "Missing elements in :order! #{missing.inspect}" unless missing.empty?
+        raise ArgumentError, "Spurious elements in :order! #{spurious.inspect}" unless spurious.empty?
+        
+        order
+      end
 
-    order
+    end
   end
+end
 
-end
+Hash.send :include, Savon::CoreExt::Hash