savon 0.7.4 → 0.7.5

data/CHANGELOG

@@ -1,3 +1,8 @@
+== 0.7.5 (2010-02-19)
+  * Fix for issue #34 (soap_actions returns empty for wsdl12).
+  * Fix for issue #36 (Custom WSDL actions broken).
+  * Added feature requested in issue #35 (Setting an attribute on an element?).
+
 == 0.7.4 (2010-02-02)
   * Fix for issue #33 (undefined method 'start_with?').
 
@@ -137,3 +142,4 @@
 
 == 0.5.0 (2009-11-29)
   * Complete rewrite.
+

data/README.rdoc

@@ -0,0 +1,62 @@
+= Savon
+
+==== Heavy metal Ruby SOAP client library
+
+{RDoc}[http://rdoc.info/projects/rubiii/savon] | {Wiki}[http://wiki.github.com/rubiii/savon] | {Metrics}[http://getcaliper.com/caliper/project?repo=git://github.com/rubiii/savon.git]
+
+== Installation
+
+  $ gem install savon
+
+Savon expects you to be familiar with SOAP, WSDL and tools like soapUI.
+
+== Instantiate a client
+
+Instantiate Savon::Client, passing in the WSDL of your service.
+
+  client = Savon::Client.new "http://example.com/UserService?wsdl"
+
+== Calling a SOAP action
+
+Assuming your service applies to the defaults, you can now call any available SOAP action.
+
+  response = client.get_all_users
+
+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.
+
+== The WSDL object
+
+Savon::WSDL represents the WSDL of your service, including information like the namespace URI and available SOAP actions.
+
+  client.wsdl.soap_actions
+  => [:get_all_users, :get_user_by_id, :user_magic]
+
+== The SOAP object
+
+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.
+
+  response = client.get_user_by_id { |soap| soap.body = { :id => 666 } }
+
+== The WSSE object
+
+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.
+
+  response = client.get_user_by_id do |soap, wsse|
+    wsse.username = "gorilla"
+    wsse.password = "secret"
+    soap.body = { :id => 666 }
+  end
+
+== The Response object
+
+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.
+
+== HTTP errors and SOAP faults
+
+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]
+
+== Logging
+
+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,16 +1,14 @@
 require "rake"
 require "spec/rake/spectask"
 require "spec/rake/verify_rcov"
-require "rake/rdoctask"
 
-task :default => :spec_verify
+task :default => :spec
 
 Spec::Rake::SpecTask.new do |spec|
   spec.spec_files = FileList["spec/{savon}/**/*_spec.rb"]
   spec.spec_opts << "--color"
   spec.libs += ["lib", "spec"]
   spec.rcov = true
-  spec.rcov_dir = "rcov"
 end
 
 RCov::VerifyTask.new(:spec_verify => :spec) do |verify|
@@ -30,16 +28,22 @@ task :spec_integration do
   end
 end
 
-desc "" # make this task invisible for "rake -T"
+desc "" # make this task invisible
 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"]
+begin
+  require "hanna/rdoctask"
+
+  Rake::RDocTask.new do |rdoc|
+    rdoc.title = "Savon - Heavy metal Ruby SOAP client library"
+    rdoc.rdoc_dir = "doc"
+    rdoc.rdoc_files.include("**/*.rdoc").include("lib/**/*.rb")
+    rdoc.options << "--line-numbers"
+  end
+rescue LoadError
+  puts "'gem install hanna' for documentation"
 end

data/lib/savon.rb

@@ -1,14 +1,5 @@
 module Savon
 
-  # Supported SOAP versions.
-  SOAPVersions = [1, 2]
-
-  # SOAP xs:dateTime format.
-  SOAPDateTimeFormat = "%Y-%m-%dT%H:%M:%SZ"
-
-  # SOAP xs:dateTime Regexp.
-  SOAPDateTimeRegexp = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/
-
   # Raised in case of an HTTP error.
   class HTTPError < StandardError; end
 
@@ -18,13 +9,22 @@ module Savon
 end
 
 # standard libs
-stdlibs = %w(logger net/https openssl base64 digest/sha1 rexml/document)
-stdlibs.each { |stdlib| require stdlib }
+require "logger"
+require "net/https"
+require "base64"
+require "digest/sha1"
+require "rexml/document"
 
-# gems
-gems = %w(builder crack/xml)
-gems.each { |gem| require gem }
+# gem dependencies
+require "builder"
+require "crack/xml"
 
 # core files
-files = %w(core_ext wsse soap request response wsdl_stream wsdl client)
-files.each { |file| require "savon/#{file}" }
+require "savon/core_ext"
+require "savon/wsse"
+require "savon/soap"
+require "savon/request"
+require "savon/response"
+require "savon/wsdl_stream"
+require "savon/wsdl"
+require "savon/client"

data/lib/savon/client.rb

@@ -29,30 +29,20 @@ module Savon
 
     # Dispatches requests to SOAP actions matching a given +method+ name.
     def method_missing(method, *args, &block) #:doc:
-      soap_call = soap_call_from method.to_s
-      super if @wsdl.enabled? && !@wsdl.respond_to?(soap_call)
+      soap_action = soap_action_from method.to_s
+      super unless @wsdl.respond_to? soap_action
 
-      setup_objects operation_from(soap_call), &block
+      setup_objects @wsdl.operation_from(soap_action), &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
+    def soap_action_from(method)
+      @wsdl.enabled = !method.ends_with?("!")
 
-    # 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 }
+      method.chop! if method.ends_with?("!")
+      method.to_sym
     end
 
     # Returns the SOAP endpoint.
@@ -63,11 +53,8 @@ module Savon
     # 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(operation, &block)
-      @soap, @wsse = SOAP.new, WSSE.new
-      @soap.action, @soap.input, @soap.endpoint = operation[:action], operation[:input], soap_endpoint
-
+      @soap, @wsse = SOAP.new(operation, soap_endpoint), WSSE.new
       yield_objects &block if block
-
       @soap.namespaces["xmlns:wsdl"] ||= @wsdl.namespace_uri if @wsdl.enabled?
       @soap.wsse = @wsse
     end

data/lib/savon/core_ext.rb

@@ -1,2 +1,8 @@
-files = %w(object string symbol datetime hash uri net_http)
-files.each { |file| require "savon/core_ext/#{file}" }
+require "savon/core_ext/object"
+require "savon/core_ext/string"
+require "savon/core_ext/symbol"
+require "savon/core_ext/datetime"
+require "savon/core_ext/array"
+require "savon/core_ext/hash"
+require "savon/core_ext/uri"
+require "savon/core_ext/net_http"

data/lib/savon/core_ext/array.rb

@@ -0,0 +1,17 @@
+class Array
+
+  # Translates the Array into SOAP request compatible XML. See: Hash#to_soap_xml.
+  def to_soap_xml(key)
+    xml = Builder::XmlMarkup.new
+
+    each do |item|
+      case item
+        when Array, Hash then xml.tag!(key) { xml << item.to_soap_xml }
+        else                  xml.tag!(key) { xml << item.to_soap_value }
+      end
+    end
+
+    xml.target!
+  end
+
+end

data/lib/savon/core_ext/datetime.rb

@@ -2,7 +2,7 @@ class DateTime
 
   # Returns the DateTime as an xs:dateTime formatted String.
   def to_soap_value
-    strftime Savon::SOAPDateTimeFormat
+    strftime Savon::SOAP::DateTimeFormat
   end
 
 end

data/lib/savon/core_ext/hash.rb

@@ -1,78 +1,81 @@
 class Hash
 
-  # Error message for missing :@inorder elements.
-  InOrderMissing = "Missing elements in :@inorder %s"
-
-  # 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.
+  # 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[self.keys.first] || {}
+    envelope = 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.
+  # Translates the Hash into SOAP request compatible XML.
+  #
+  # === Example:
+  #
+  #   { :find_user => { :id => 123, "wsdl:Key" => "api" } }.to_soap_xml
+  #   # => "<findUser><id>123</id><wsdl:Key>api</wsdl:Key></findUser>"
   #
-  # To control the order of output, add a key of :@inorder with
-  # the value being an Array listing keys in order.
+  # Comes with a way to control the order of XML tags in case you're foced to do so (parameterOrder).
+  # Specify an optional Array under the :order! key reflecting the order of your keys.
+  # An ArgumentError is raised unless the Array contains the exact same/all keys of your Hash.
   #
-  # === Examples
+  # === Example:
   #
-  #   { :find_user => { :id => 666 } }.to_soap_xml
-  #   => "<findUser><id>666</id></findUser>"
+  #   { :find_user => { :name => "Eve", :id => 123, :order! => [:id, :name] } }.to_soap_xml
+  #   # => "<findUser><id>123</id><name>Eve</name></findUser>"
   #
-  #   { :find_user => { :name => "Lucy", :id => 666, :@inorder => [:id, :name] } }.to_soap_xml
-  #   => "<findUser><id>666</id><name>Lucy</name></findUser>"
+  # You can also specify attributes for XML tags by via an optional Hash under the :attributes! key.
+  #
+  # === Example:
+  #
+  #   { :find_user => { :person => "Eve", :attributes! => { :person => { :id => 123 } } } }
+  #   # => "<findUser><person id="123">Eve</person></findUser>"
   def to_soap_xml
-    @soap_xml = Builder::XmlMarkup.new
-    inorder(self).each { |key| nested_data_to_soap_xml key, self[key] }
-    @soap_xml.target!
+    xml = Builder::XmlMarkup.new
+    attributes = delete(:attributes!) || {}
+
+    order.each do |key|
+      attrs = attributes[key] || {}
+      value = self[key]
+      key = key.to_soap_key
+
+      case value
+        when Array then xml << value.to_soap_xml(key)
+        when Hash  then xml.tag!(key, attrs) { xml << value.to_soap_xml }
+        else            xml.tag!(key, attrs) { xml << value.to_soap_value }
+      end
+    end
+
+    xml.target!
   end
 
-  # Maps keys and values of a Hash created from SOAP response XML to
-  # more convenient Ruby Objects.
+  # 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)|
-      key = key.strip_namespace.snakecase.to_sym
-
       value = case value
         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
+
+      hash.merge key.strip_namespace.snakecase.to_sym => value
     end
   end
 
 private
 
-  # Expects a Hash +key+ and +value+ and recursively creates an XML structure
-  # representing the Hash content.
-  def nested_data_to_soap_xml(key, value)
-    case value
-      when Array
-        value.map { |subitem| nested_data_to_soap_xml key, subitem }
-      when Hash
-        @soap_xml.tag!(key.to_soap_key) do
-          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
+  # 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?
 
-  # 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
+    order
   end
 
 end

data/lib/savon/core_ext/string.rb

@@ -26,14 +26,26 @@ class String
     str
   end
 
+  # Returns whether the String starts with a given +prefix+.
+  def starts_with?(prefix)
+    prefix = prefix.to_s
+    self[0, prefix.length] == prefix
+  end unless defined? starts_with?
+
+  # Returns whether the String ends with a given +suffix+.
+  def ends_with?(suffix)
+    suffix = suffix.to_s
+    self[-suffix.length, suffix.length] == suffix      
+  end unless defined? ends_with?
+
   # Returns the String without namespace.
   def strip_namespace
-    gsub /(.+:)(.+)/, '\2'
+    split(":").last
   end
 
-  # Translates SOAP response values to more convenient Ruby Objects.
+  # Translates SOAP response values to Ruby Objects.
   def map_soap_response
-    return DateTime.parse( self ) if Savon::SOAPDateTimeRegexp === self
+    return DateTime.parse(self) if Savon::SOAP::DateTimeRegexp === self
     return true if self.strip.downcase == "true"
     return false if self.strip.downcase == "false"
     self

data/lib/savon/core_ext/uri.rb

@@ -3,7 +3,7 @@ module URI
 
     # Returns whether the URI hints to SSL.
     def ssl?
-      /^https/ === @scheme
+      @scheme.starts_with? "https"
     end
 
   end

data/lib/savon/request.rb

@@ -125,6 +125,7 @@ module Savon
         when :wsdl then Net::HTTP::Get.new @endpoint.request_uri
         when :soap then Net::HTTP::Post.new @soap.endpoint.request_uri, soap_headers.merge(headers)
       end
+
       request.basic_auth(*@basic_auth) if @basic_auth
       yield request if block_given?
       request
@@ -137,12 +138,7 @@ module Savon
 
     # Logs a given +message+.
     def log(message)
-      self.class.logger.send self.class.log_level, message if log?
-    end
-
-    # Returns whether to log.
-    def log?
-      self.class.log? && self.class.logger.respond_to?(self.class.log_level)
+      self.class.logger.send self.class.log_level, message if self.class.log?
     end
 
   end