savon 0.6.0 → 0.7.0

data/CHANGELOG

@@ -0,0 +1,112 @@
+== 0.7.0 (2010-01-09)
+  This version comes with several changes to the public API!
+  Pay attention to the following list and read the updated Wiki: http://wiki.github.com/rubiii/savon
+
+  * Changed how Savon::WSDL can be disabled. Instead of disabling the WSDL globally/per request via two
+    different methods, you now simply append an exclamation mark (!) to your SOAP call: client.get_all_users!
+    Make sure you know what you're doing because when the WSDL is disabled, Savon does not know about which
+    SOAP actions are valid and just dispatches everything.
+  * The Net::HTTP object used by Savon::Request to retrieve WSDL documents and execute SOAP calls is now public.
+    While this makes the library even more flexible, it also comes with two major changes:
+    * SSL client authentication needs to be defined directly on the Net::HTTP object:
+      client.request.http.client_cert = ...
+      I added a shortcut method for setting all options through a Hash similar to the previous implementation:
+      client.request.http.ssl_client_auth :client_cert => ...
+    * Open and read timeouts also need to be set on the Net::HTTP object:
+      client.request.http.open_timeout = 30
+      client.request.http.read_timeout = 30
+    * Please refer to the Net::HTTP documentation for more details:
+      http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html
+  * Thanks to JulianMorrison, Savon now supports HTTP basic authentication:
+    client.request.http.basic_auth "username", "password"
+  * Julian also added a way to explicitly specify the order of Hash keys and values, so you should now be able
+    to work with services requiring a specific order of input parameters while still using Hash input.
+    For example: client.find_user { |soap| soap.body = { :name => "Lucy", :id => 666, :@inorder => [:id, :name] } }
+  * Savon::Response#to_hash now returns the content inside of "soap:Body" instead of trying to go one level
+    deeper and return it's content. The previous implementation only worked when the "soap:Body" element
+    contained a single child. See: http://github.com/rubiii/savon/issues#issue/17
+  * Added Savon::SOAP#namespace as a shortcut for setting the "xmlns:wsdl" namespace.
+    Usage example: soap.namespace = "http://example.com"
+
+== 0.6.8 (2010-01-01)
+  * Improved specifications for various kinds of WSDL documents.
+  * Added support for SOAP endpoints which are different than the WSDL endpoint of a service.
+  * Changed how SOAP actions and inputs are retrieved from the WSDL documents. This might break a few existing
+    implementations, but makes Savon work well with even more services. If this change breaks your implementation,
+    please take a look at the +action+ and +input+ methods of the Savon::SOAP object.
+    One specific problem I know of is working with the createsend WSDL and its namespaced actions.
+    To make it work, call the SOAP action without namespace and specify the input manually:
+    client.get_api_key { |soap| soap.input = "User.GetApiKey" }
+
+== 0.6.7 (2009-12-18)
+  * Implemented support for a proxy server. The proxy URI can be set through an optional Hash of options passed
+    to instantiating Savon::Client (Dave Woodward <dave@futuremint.com>)
+  * Implemented support for SSL client authentication. Settings can be set through an optional Hash of arguments
+    passed to instantiating Savon::Client (colonhyphenp)
+  * Patch for issue #10 (Problem with operation tags without a namespace).
+
+== 0.6.6 (2009-12-14)
+  * Default to use the name of the SOAP action (the method called in a client) in lowerCamelCase for SOAP action
+    and input when Savon::WSDL is disabled. You still need to specify soap.action and maybe soap.input in case
+    your SOAP actions are named any different.
+
+== 0.6.5 (2009-12-13)
+  * Added an open_timeout method to Savon::Request.
+
+== 0.6.4 (2009-12-13)
+  * Refactored specs to be less unit-like.
+  * Added a getter for the Savon::Request to Savon::Client and a read_timeout setter for HTTP requests.
+  * wsdl.soap_actions now returns an Array of SOAP actions. For the previous "mapping" please use wsdl.operations.
+  * Replaced WSDL document with stream parsing.
+
+    Benchmarks (1000 SOAP calls):
+
+           user        system     total       real
+    0.6.4  72.180000   8.280000   80.460000   (750.799011)
+    0.6.3  192.900000  19.630000  212.530000  (914.031865)
+
+== 0.6.3 (2009-12-11)
+  * Removing 2 ruby deprecation warnings for parenthesized arguments. (Dave Woodward <dave@futuremint.com>)
+  * Added global and per request options for disabling Savon::WSDL.
+
+    Benchmarks (1000 SOAP calls):
+
+                   user        system     total       real
+    WSDL           192.900000  19.630000  212.530000  (914.031865)
+    disabled WSDL  5.680000    1.340000   7.020000    (298.265318)
+
+  * Improved XPath expressions for parsing the WSDL document.
+
+    Benchmarks (1000 SOAP calls):
+
+           user        system     total       real
+    0.6.3  192.900000  19.630000  212.530000  (914.031865)
+    0.6.2  574.720000  78.380000  653.100000  (1387.778539)
+
+== 0.6.2 (2009-12-06)
+  * Added support for changing the name of the SOAP input node.
+  * Added a CHANGELOG.
+
+== 0.6.1 (2009-12-06)
+  * Fixed a problem with WSSE credentials, where every request contained a WSSE authentication header.
+
+== 0.6.0 (2009-12-06)
+  * method_missing now yields the SOAP and WSSE objects to a given block.
+  * The response_process (which previously was a block passed to method_missing) was replaced by Savon::Response.
+  * Improved SOAP action handling (another problem that came up with issue #1).
+
+== 0.5.3 (2009-11-30)
+  * Patch for issue #2 (NoMethodError: undefined method `invalid!' for Savon::WSDL)
+
+== 0.5.2 (2009-11-30)
+  * Patch for issue #1 (Calls fail if api methods have periods in them)
+
+== 0.5.1 (2009-11-29)
+  * Optimized default response process.
+  * Added WSSE settings via defaults.
+  * Added SOAP fault and HTTP error handling.
+  * Improved documentation
+  * Added specs
+
+== 0.5.0 (2009-11-29)
+  * Complete rewrite.

data/README.textile

@@ -1,68 +1,75 @@
-h2. Savon
+h1. Savon
 
-p. Savon can be installed as a gem via:
+h4. Heavy metal Ruby SOAP client library
 
-bc. $ gem install savon
-
-h4. Dependencies
-
-bc. builder >= 2.1.2
-crack >= 0.1.4
+p. "RDoc":http://rdoc.info/projects/rubiii/savon | "Wiki":http://wiki.github.com/rubiii/savon | "ToDo":http://rubiii.tadalist.com/lists/1459816/public | "Metrics":http://getcaliper.com/caliper/project?repo=git://github.com/rubiii/savon.git
 
 h2. Warning
 
-p. To use this heavy metal library, you should be familiar with SOAP, WSDL and tools like soapUI.
+p. Savon 0.7.0 comes with several changes to the public API. Pay attention to the CHANGELOG and the updated Wiki.
 
-h2. Instantiate Savon::Client
+h2. Installation
 
-p. Instantiate a new instance of Savon::Client, passing in the WSDL of your service.
+bc. $ gem install savon
 
-bc. proxy = Savon::Client.new "http://example.com/UserService?wsdl"
+p. Savon expects you to be familiar with SOAP, WSDL and tools like soapUI.
 
-h2. The WSDL
+h2. Instantiate a client
 
-p. You can find out about the SOAP actions available on the webservice by using the WSDL object.
+p. Instantiate Savon::Client, passing in the WSDL of your service.
 
-bc. proxy.wsdl.soap_actions
-=> [:get_all_users, :get_user_by_id, :user_magic]
+bc. client = Savon::Client.new "http://example.com/UserService?wsdl"
 
-p. Find out more about the "WSDL":http://wiki.github.com/rubiii/savon/wsdl object.
+p. More information: "Client":http://wiki.github.com/rubiii/savon/client
 
 h2. Calling a SOAP action
 
-p. Now, assuming your service applies to the default "Options":http://wiki.github.com/rubiii/savon/options, you can just call any available SOAP action.
+p. Assuming your service applies to the defaults, you can now call any available SOAP action.
 
-bc. response = proxy.get_all_users
+bc. response = client.get_all_users
 
 p. Savon lets you call SOAP actions using snake_case, because even though they will propably be written in lowerCamelCase or CamelCase, it just feels much more natural.
 
-h2. Parameters
+h2. The WSDL object
 
-p. Specifying parameters for the SOAP service, can be done by simply passing a Hash to the SOAP action.
+p. Savon::WSDL represents the WSDL of your service, including information like the namespace URI and available SOAP actions.
 
-bc. response = proxy.get_user_by_id :id => 666
+bc. client.wsdl.soap_actions
+=> [:get_all_users, :get_user_by_id, :user_magic]
 
-p. Learn more about [[Parameters]].
+p. More information: "WSDL":http://wiki.github.com/rubiii/savon/wsdl
 
-h2. The response
+h2. The SOAP object
 
-p. By default, the SOAP response is translated into a Hash. Take a look at the "Options":http://wiki.github.com/rubiii/savon/options for more information.
+p. Savon::SOAP represents the SOAP request. Pass a block to your SOAP call and the SOAP object is passed to it as the first argument. The object allows setting the SOAP version, header, body and namespaces per request.
 
-bc. proxy.get_user_by_id :id => 666
-=> { :user_response => { :id => "666", :username => "gorilla" } }
+bc. response = client.get_user_by_id { |soap| soap.body = { :id => 666 } }
 
-h2. HTTP errors and SOAP faults
+p. More information: "SOAP":http://wiki.github.com/rubiii/savon/soap
 
-p. Savon raises a Savon::SOAPFault in case of a SOAP fault and a Savon::HTTPError in case of an HTTP error. More information about "Errors":http://wiki.github.com/rubiii/savon/errors.
+h2. The WSSE object
 
-h2. Logging
+p. Savon::WSSE represents WSSE authentication. Pass a block to your SOAP call and the WSSE object is passed to it as the second argument. The object allows setting the WSSE username, password and whether to use digest authentication.
+
+bc. response = client.get_user_by_id do |soap, wsse|
+  wsse.username = "gorilla"
+  wsse.password = "secret"
+  soap.body = { :id => 666 }
+end
+
+p. More information: "WSSE":http://wiki.github.com/rubiii/savon/wsse
 
-p. By default Savon logs each request and response to STDOUT. Specifying your own logger is as easy as it gets:
+h2. The Response object
 
-bc. Savon::Request.logger = RAILS_DEFAULT_LOGGER
+p. Savon::Response represents the HTTP and SOAP response. It contains and raises errors in case of an HTTP error or SOAP fault (unless disabled). Also you can get the response as XML (for parsing it with an XML library) or translated into a Hash.
+More information: "Response":http://wiki.github.com/rubiii/savon/response
 
-Read more about "Logging":http://wiki.github.com/rubiii/savon/logging.
+h2. HTTP errors and SOAP faults
+
+p. Savon raises a Savon::SOAPFault in case of a SOAP fault and a Savon::HTTPError in case of an HTTP error.
+More information: "Errors":http://wiki.github.com/rubiii/savon/errors
 
-h2. RDoc and Wiki
+h2. Logging
 
-p. Further information: "Wiki":http://wiki.github.com/rubiii/savon and "RDoc":http://rdoc.info/projects/rubiii/savon
+p. Savon logs each request and response to STDOUT. But there are a couple of options to change the default behavior.
+More information: "Logging":http://wiki.github.com/rubiii/savon/logging

data/Rakefile

@@ -1,50 +1,45 @@
-require "rubygems"
 require "rake"
 require "spec/rake/spectask"
+require "spec/rake/verify_rcov"
 require "rake/rdoctask"
 
-task :default => :spec
+task :default => :spec_verify
 
 Spec::Rake::SpecTask.new do |spec|
-  spec.spec_files = FileList["spec/**/*_spec.rb"]
+  spec.spec_files = FileList["spec/{savon}/**/*_spec.rb"]
   spec.spec_opts << "--color"
-  spec.libs << "lib"
+  spec.libs += ["lib", "spec"]
   spec.rcov = true
   spec.rcov_dir = "rcov"
 end
 
+RCov::VerifyTask.new(:spec_verify => :spec) do |verify|
+  verify.threshold = 100.0
+  verify.index_html = "rcov/index.html"
+end
+
+desc "Run integration specs using WEBrick"
+task :spec_integration do
+  pid = fork { exec "ruby spec/integration/server.rb" }
+  sleep 10 # wait until the server is actually ready
+  begin
+    task(:run_integration_spec).invoke
+  ensure
+    Process.kill "TERM", pid
+    Process.wait pid
+  end
+end
+
+desc "" # make this task invisible for "rake -T"
+Spec::Rake::SpecTask.new(:run_integration_spec) do |spec|
+  spec.spec_files = FileList["spec/{integration}/**/*_spec.rb"]
+  spec.spec_opts << "--color"
+  spec.libs += ["lib", "spec"]
+end
+
 Rake::RDocTask.new do |rdoc|
   rdoc.title = "Savon"
   rdoc.rdoc_dir = "rdoc"
   rdoc.rdoc_files.include("lib/**/*.rb")
   rdoc.options = ["--line-numbers", "--inline-source"]
 end
-
-begin
-  require "jeweler"
-  Jeweler::Tasks.new do |spec|
-    spec.name = "savon"
-    spec.author = "Daniel Harrington"
-    spec.email = "me@rubiii.com"
-    spec.homepage = "http://github.com/rubiii/savon"
-    spec.summary = "Heavy metal Ruby SOAP client library"
-    spec.description = spec.summary
-
-    spec.files = FileList["[A-Z]*", "{lib,spec}/**/*.{rb,xml}"]
-
-    spec.rdoc_options += [
-      "--title", "Savon",
-      "--line-numbers",
-      "--inline-source"
-    ]
-
-    spec.add_runtime_dependency("builder", ">= 2.1.2")
-    spec.add_runtime_dependency("crack", ">= 0.1.4")
-
-    spec.add_development_dependency("rspec", ">= 1.2.8")
-    spec.add_development_dependency("mocha", ">= 0.9.7")
-    spec.add_development_dependency("fakeweb", ">= 1.2.7")
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
-end

data/lib/savon/client.rb

@@ -6,15 +6,19 @@ module Savon
   # with SOAP services and XML.
   class Client
 
-    # Expects a SOAP +endpoint+ String.
-    def initialize(endpoint)
-      @request = Request.new endpoint
+    # Expects a SOAP +endpoint+ String. Also accepts an optional Hash of
+    # +options+ for specifying a proxy server and SSL client authentication.
+    def initialize(endpoint, options = {})
+      @request = Request.new endpoint, options
       @wsdl = WSDL.new @request
     end
 
     # Returns the Savon::WSDL.
     attr_reader :wsdl
 
+    # Returns the Savon::Request.
+    attr_reader :request
+
     # Returns +true+ for available methods and SOAP actions.
     def respond_to?(method)
       return true if @wsdl.respond_to? method
@@ -25,37 +29,56 @@ module Savon
 
     # Dispatches requests to SOAP actions matching a given +method+ name.
     def method_missing(method, *args, &block) #:doc:
-      super unless @wsdl.respond_to? method
+      soap_call = soap_call_from method.to_s
+      super if @wsdl.enabled? && !@wsdl.respond_to?(soap_call)
+
+      setup_objects operation_from(soap_call), &block
+      Response.new @request.soap(@soap)
+    end
+
+    # Sets whether to use Savon::WSDL by a given +method+ name and
+    # removes exclamation marks from the given +method+ name.
+    def soap_call_from(method)
+      if method[-1, 1] == "!"
+        @wsdl.enabled = false
+        method[0, method.length-1].to_sym
+      else
+        @wsdl.enabled = true
+        method.to_sym
+      end
+    end
+
+    # Returns a SOAP operation Hash containing the SOAP action and input
+    # for a given +soap_call+.
+    def operation_from(soap_call)
+      return @wsdl.operations[soap_call] if @wsdl.enabled?
+      { :action => soap_call.to_soap_key, :input => soap_call.to_soap_key }
+    end
 
-      setup method, &block
-      dispatch method
+    # Returns the SOAP endpoint.
+    def soap_endpoint
+      @wsdl.enabled? ? @wsdl.soap_endpoint : @request.endpoint
     end
 
-    # Expects a SOAP action and sets up Savon::SOAP and Savon::WSSE.
+    # 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(soap_action, &block)
-      @soap = SOAP.new @wsdl.soap_actions[soap_action]
-      @wsse = WSSE.new
+    def setup_objects(operation, &block)
+      @soap, @wsse = SOAP.new, WSSE.new
+      @soap.action, @soap.input, @soap.endpoint = operation[:action], operation[:input], soap_endpoint
 
-      yield_parameters &block if block
+      yield_objects &block if block
 
-      @soap.namespaces["xmlns:wsdl"] = @wsdl.namespace_uri
+      @soap.namespaces["xmlns:wsdl"] ||= @wsdl.namespace_uri if @wsdl.enabled?
       @soap.wsse = @wsse
     end
 
     # Yields Savon::SOAP and Savon::WSSE to a given +block+.
-    def yield_parameters(&block)
+    def yield_objects(&block)
       case block.arity
         when 1 then yield @soap
         when 2 then yield @soap, @wsse
       end
     end
 
-    # Dispatches a given +soap_action+ and returns a Savon::Response instance.
-    def dispatch(soap_action)
-      response = @request.soap @soap
-      Response.new response
-    end
-
   end
 end

data/lib/savon/core_ext/hash.rb

@@ -1,29 +1,34 @@
 class Hash
 
-  # Expects an Array of Regexp Objects of which every Regexp recursively
-  # matches a key to be accessed. Returns the value of the last Regexp filter
-  # found in the Hash or an empty Hash in case the path of Regexp filters
-  # did not match the Hash structure.
-  def find_regexp(regexp)
-    regexp = [regexp] unless regexp.kind_of? Array
-    result = dup
+  # Error message for missing :@inorder elements.
+  InOrderMissing = "Missing elements in :@inorder %s"
 
-    regexp.each do |pattern|
-      result_key = result.keys.find { |key| key.to_s.match pattern }
-      result = result[result_key] ? result[result_key] : {}
-    end
-    result
+  # Error message for spurious :@inorder elements.
+  InOrderSpurious = "Spurious elements in :@inorder %s"
+
+  # Returns the values from the 'soap:Body' element or an empty Hash
+  # in case the node could not be found.
+  def find_soap_body
+    envelope = self[self.keys.first] || {}
+    body_key = envelope.keys.find { |key| /.+:Body/ =~ key } rescue nil
+    body_key ? envelope[body_key].map_soap_response : {}
   end
 
   # Returns the Hash translated into SOAP request compatible XML.
   #
-  # === Example
+  # To control the order of output, add a key of :@inorder with
+  # the value being an Array listing keys in order.
+  #
+  # === Examples
   #
   #   { :find_user => { :id => 666 } }.to_soap_xml
   #   => "<findUser><id>666</id></findUser>"
+  #
+  #   { :find_user => { :name => "Lucy", :id => 666, :@inorder => [:id, :name] } }.to_soap_xml
+  #   => "<findUser><id>666</id><name>Lucy</name></findUser>"
   def to_soap_xml
     @soap_xml = Builder::XmlMarkup.new
-    each { |key, value| nested_data_to_soap_xml key, value }
+    inorder(self).each { |key| nested_data_to_soap_xml key, self[key] }
     @soap_xml.target!
   end
 
@@ -34,12 +39,9 @@ class Hash
       key = key.strip_namespace.snakecase.to_sym
 
       value = case value
-        when Hash
-          value["xsi:nil"] ? nil : value.map_soap_response
-        when Array
-          value.map { |a_value| a_value.map_soap_response rescue a_value }
-        when String
-          value.map_soap_response
+        when Hash   then value["xsi:nil"] ? nil : value.map_soap_response
+        when Array  then value.map { |a_value| a_value.map_soap_response rescue a_value }
+        when String then value.map_soap_response
       end
       hash.merge key => value
     end
@@ -52,14 +54,25 @@ private
   def nested_data_to_soap_xml(key, value)
     case value
       when Array
-        value.map { |sitem| nested_data_to_soap_xml key, sitem }
+        value.map { |subitem| nested_data_to_soap_xml key, subitem }
       when Hash
         @soap_xml.tag!(key.to_soap_key) do
-          value.each { |subkey, subvalue| nested_data_to_soap_xml subkey, subvalue }
+          inorder(value).each { |subkey| nested_data_to_soap_xml subkey, value[subkey] }
         end
       else
         @soap_xml.tag!(key.to_soap_key) { @soap_xml << value.to_soap_value }
     end
   end
 
+  # Takes a +hash+, removes the :@inorder marker and returns its keys.
+  # Raises an error in case an :@inorder Array does not match the Hash keys.
+  def inorder(hash)
+    inorder = hash.delete :@inorder
+    hash_keys = hash.keys
+    inorder = hash_keys unless inorder.kind_of? Array
+    raise InOrderMissing % (hash_keys - inorder).inspect unless (hash_keys - inorder).empty?
+    raise InOrderSpurious % (inorder - hash_keys).inspect unless (inorder - hash_keys).empty?
+    inorder
+  end
+
 end

data/lib/savon/core_ext/net_http.rb

@@ -0,0 +1,20 @@
+module Net
+  class HTTP
+
+    # Sets the endpoint +address+ and +port+.
+    def endpoint(address, port)
+      @address, @port = address, port
+    end
+
+    # Convenience method for setting SSL client authentication
+    # through a Hash of +options+.
+    def ssl_client_auth(options)
+      self.use_ssl = true
+      self.cert = options[:cert] if options[:cert]
+      self.key = options[:key] if options[:key]
+      self.ca_file = options[:ca_file] if options[:ca_file]
+      self.verify_mode = options[:verify_mode] if options[:verify_mode]
+    end
+
+  end
+end

data/lib/savon/core_ext/object.rb

@@ -1,5 +1,12 @@
 class Object
 
+  # Returns +true+ if the Object is false, empty, or a whitespace string.
+  # For example, "", false, nil, [], and {} are blank.
+  # Implementation from ActiveSupport.
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end unless defined? blank?
+
   # Returns the Object as a SOAP request compliant key.
   def to_soap_key
     to_s

data/lib/savon/core_ext/string.rb

@@ -33,7 +33,7 @@ class String
 
   # Translates SOAP response values to more convenient Ruby Objects.
   def map_soap_response
-    return DateTime.parse self if Savon::SOAPDateTimeRegexp === self
+    return DateTime.parse( self ) if Savon::SOAPDateTimeRegexp === self
     return true if self.strip.downcase == "true"
     return false if self.strip.downcase == "false"
     self

data/lib/savon/core_ext.rb

@@ -1,3 +1,3 @@
-%w(object string symbol datetime hash uri).each do |file|
-  require "savon/core_ext/#{file}"
+%w(object string symbol datetime hash uri net_http).each do |file|
+  require File.dirname(__FILE__) + "/core_ext/#{file}"
 end