savon 0.7.5 → 0.7.6

data/CHANGELOG

@@ -1,7 +1,18 @@
+== 0.7.6 (2010-03-21)
+  * Renamed 
+  * Moved documentation from the Github Wiki to the actual class files and established a much nicer
+    documentation combining examples and implementation (using Hanna) at: http://savon.rubiii.com
+  * Added Savon::Client#call as a workaround for dispatching calls to SOAP actions  named after
+	  existing methods. Fix for issue #48.
+  * Add support for specifying attributes for duplicate tags (via Hash values as Arrays). Fix for issue #45.
+  * Fix for issue #41 (Escape special characters (e.g. &) for XML requests).
+  * Fix for issue #39 and #49. Added Savon::SOAP#xml which let's you specify completely custom SOAP request XML.
+
 == 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?).
+  * Changed the key for specifying the order of tags from :@inorder to :order!
 
 == 0.7.4 (2010-02-02)
   * Fix for issue #33 (undefined method 'start_with?').

data/README.rdoc

@@ -2,7 +2,7 @@
 
 ==== 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]
+{Documentation}[http://savon.rubiii.com] | {Metrics}[http://getcaliper.com/caliper/project?repo=git://github.com/rubiii/savon.git]
 
 == Installation
 
@@ -16,6 +16,8 @@ Instantiate Savon::Client, passing in the WSDL of your service.
 
   client = Savon::Client.new "http://example.com/UserService?wsdl"
 
+For production, it is highly recommended to not use Savon::WSDL. Information on {how to disable the WSDL}[http://savon.rubiii.com/docs/latest/classes/Savon/WSDL.html].
+
 == Calling a SOAP action
 
 Assuming your service applies to the defaults, you can now call any available SOAP action.
@@ -54,9 +56,9 @@ Savon::Response represents the HTTP and SOAP response. It contains and raises er
 == 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]
+More information: {Errors}[http://savon.rubiii.com/docs/latest/classes/Savon/Response.html]
 
 == 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]
+More information: {Logging}[http://savon.rubiii.com/docs/latest/classes/Savon/Request.html]

data/Rakefile

@@ -36,6 +36,7 @@ Spec::Rake::SpecTask.new(:run_integration_spec) do |spec|
 end
 
 begin
+  $:.unshift File.join(File.dirname(__FILE__), "..", "hanna", "lib")
   require "hanna/rdoctask"
 
   Rake::RDocTask.new do |rdoc|
@@ -43,6 +44,7 @@ begin
     rdoc.rdoc_dir = "doc"
     rdoc.rdoc_files.include("**/*.rdoc").include("lib/**/*.rb")
     rdoc.options << "--line-numbers"
+    rdoc.options << "--webcvs=http://github.com/rubiii/savon/tree/master/"
   end
 rescue LoadError
   puts "'gem install hanna' for documentation"

data/lib/savon.rb

@@ -23,6 +23,7 @@ require "crack/xml"
 require "savon/core_ext"
 require "savon/wsse"
 require "savon/soap"
+require "savon/logger"
 require "savon/request"
 require "savon/response"
 require "savon/wsdl_stream"

data/lib/savon/client.rb

@@ -1,13 +1,47 @@
 module Savon
 
-  # == Savon::Client
+  # = Savon::Client
   #
-  # Heavy metal Ruby SOAP client library. Minimizes the overhead of working
-  # with SOAP services and XML.
+  # 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"
+  #
+  # == Savon::WSDL
+  #
+  # You can access Savon::WSDL via:
+  #
+  #   client.wsdl
+  #
+  # == Savon::Request
+  #
+  # You can also access Savon::Request via:
+  #
+  #   client.request
   class Client
 
-    # Expects a SOAP +endpoint+ String. Also accepts an optional Hash of
-    # +options+ for specifying a proxy server and SSL client authentication.
+    # Expects a SOAP +endpoint+ string. Also accepts an optional hash of +options+ for specifying
+    # a +:proxy+ server to use.
     def initialize(endpoint, options = {})
       @request = Request.new endpoint, options
       @wsdl = WSDL.new @request
@@ -25,6 +59,12 @@ module Savon
       super
     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
+    end
+
   private
 
     # Dispatches requests to SOAP actions matching a given +method+ name.
@@ -32,12 +72,12 @@ module Savon
       soap_action = soap_action_from method.to_s
       super unless @wsdl.respond_to? soap_action
 
-      setup_objects @wsdl.operation_from(soap_action), &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.
+    # 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?("!")
 
@@ -50,16 +90,17 @@ module Savon
       @wsdl.enabled? ? @wsdl.soap_endpoint : @request.endpoint
     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(operation, &block)
-      @soap, @wsse = SOAP.new(operation, soap_endpoint), WSSE.new
+    # 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
     end
 
-    # Yields Savon::SOAP and Savon::WSSE to a given +block+.
+    # 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

data/lib/savon/core_ext/array.rb

@@ -1,17 +1,31 @@
 class Array
 
-  # Translates the Array into SOAP request compatible XML. See: Hash#to_soap_xml.
-  def to_soap_xml(key)
+  # Translates the Array into SOAP compatible XML. See: Hash.to_soap_xml.
+  def to_soap_xml(key, attributes = {})
     xml = Builder::XmlMarkup.new
 
-    each do |item|
+    each_with_index do |item, index|
+      attrs = tag_attributes attributes, index
       case item
-        when Array, Hash then xml.tag!(key) { xml << item.to_soap_xml }
-        else                  xml.tag!(key) { xml << item.to_soap_value }
+        when Hash then xml.tag!(key, attrs) { xml << item.to_soap_xml }
+        else           xml.tag!(key, attrs) { xml << item.to_soap_value }
       end
     end
 
     xml.target!
   end
 
-end
+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?
+
+    attributes.inject({}) do |hash, (key, value)|
+      value = value[index] if value.kind_of? Array
+      hash.merge key => value
+    end
+  end
+
+end

data/lib/savon/core_ext/hash.rb

@@ -10,26 +10,47 @@ class Hash
 
   # 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>"
   #
-  # 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.
+  # ==== 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>
+  #
+  # ==== :order!
   #
-  # === Example:
+  # 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.
   #
-  #   { :find_user => { :name => "Eve", :id => 123, :order! => [:id, :name] } }.to_soap_xml
-  #   # => "<findUser><id>123</id><name>Eve</name></findUser>"
+  #   { :name => "Eve", :id => 123, :order! => [:id, :name] }.to_soap_xml
+  #   # => "<id>123</id><name>Eve</name>"
   #
-  # You can also specify attributes for XML tags by via an optional Hash under the :attributes! key.
+  # ==== :attributes!
   #
-  # === Example:
+  # If you need attributes, you could either go with an XML string or add another hash under the
+  # +:attributes!+ key.
   #
-  #   { :find_user => { :person => "Eve", :attributes! => { :person => { :id => 123 } } } }
-  #   # => "<findUser><person id="123">Eve</person></findUser>"
+  #   { :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!) || {}
@@ -40,7 +61,7 @@ class Hash
       key = key.to_soap_key
 
       case value
-        when Array then xml << value.to_soap_xml(key)
+        when Array then xml << value.to_soap_xml(key, attrs)
         when Hash  then xml.tag!(key, attrs) { xml << value.to_soap_xml }
         else            xml.tag!(key, attrs) { xml << value.to_soap_value }
       end
@@ -54,7 +75,7 @@ class Hash
     inject({}) do |hash, (key, value)|
       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 Array  then value.map { |val| val.map_soap_response rescue val }
         when String then value.map_soap_response
       end
 
@@ -78,4 +99,4 @@ private
     order
   end
 
-end
+end

data/lib/savon/core_ext/net_http.rb

@@ -6,8 +6,7 @@ module Net
       @address, @port = address, port
     end
 
-    # Convenience method for setting SSL client authentication
-    # through a Hash of +options+.
+    # 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]

data/lib/savon/core_ext/object.rb

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

data/lib/savon/core_ext/string.rb

@@ -35,7 +35,7 @@ class String
   # Returns whether the String ends with a given +suffix+.
   def ends_with?(suffix)
     suffix = suffix.to_s
-    self[-suffix.length, suffix.length] == suffix      
+    self[-suffix.length, suffix.length] == suffix
   end unless defined? ends_with?
 
   # Returns the String without namespace.
@@ -52,8 +52,15 @@ class String
   end
 
   # Returns the String as a SOAP request compliant value.
+  # Escapes special characters for XML.
   def to_soap_value
-    to_s
+    str = dup
+    str.gsub! "&", "&"
+    str.gsub! '"', """
+    str.gsub! "'", "'"
+    str.gsub! "<", "&lt;"
+    str.gsub! ">", "&gt;"
+    str
   end
 
 end

data/lib/savon/core_ext/uri.rb

@@ -3,7 +3,7 @@ module URI
 
     # Returns whether the URI hints to SSL.
     def ssl?
-      @scheme.starts_with? "https"
+      !@scheme ? nil : @scheme.starts_with?("https")
     end
 
   end

data/lib/savon/logger.rb

@@ -0,0 +1,56 @@
+module Savon
+
+  # = Savon::Logger
+  #
+  # Savon::Logger can be mixed into classes to provide logging behavior.
+  #
+  # By default, the Logger mixin uses {Ruby's Logger}[http://ruby-doc.org/stdlib/libdoc/logger/rdoc/]
+  # from the standard library, a log level of :debug and is pointing to STDOUT.
+  module Logger
+
+    module ClassMethods
+
+      # Sets whether to log.
+      def log=(log)
+        @log = log
+      end
+
+      # Returns whether to log. Defaults to +true+.
+      def log?
+        @log != false
+      end
+
+      # Sets the logger.
+      def logger=(logger)
+        @logger = logger
+      end
+
+      # Returns the logger. Defaults to an instance of +Logger+ writing to STDOUT.
+      def logger
+        @logger ||= ::Logger.new STDOUT
+      end
+
+      # Sets the log level.
+      def log_level=(log_level)
+        @log_level = log_level
+      end
+
+      # Returns the log level. Defaults to +debug+.
+      def log_level
+        @log_level ||= :debug
+      end
+
+    end
+
+    # Extends the class including this module with its ClassMethods.
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Logs a given +message+.
+    def log(message)
+      self.class.logger.send self.class.log_level, message if self.class.log?
+    end
+
+  end
+end

data/lib/savon/request.rb

@@ -1,52 +1,51 @@
 module Savon
 
-  # == Savon::Request
+  # = Savon::Request
   #
-  # Handles both WSDL and SOAP HTTP requests.
+  # Savon::Request handles both WSDL and SOAP requests.
+  #
+  # == The Net::HTTP object
+  #
+  # You can access the Net::HTTP object used for both WSDL and SOAP requests via:
+  #
+  #   client.request.http
+  #
+  # Here's an example of how to set open and read timeouts on the Net::HTTP object.
+  #
+  #   client.request.http.open_timeout = 30
+  #   client.request.http.read_timeout = 30
+  #
+  # Please refer to the {Net::HTTP documentation}[http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/]
+  # for more information.
+  #
+  # == HTTP basic authentication
+  #
+  # Setting credentials for HTTP basic authentication:
+  #
+  #   client.request.basic_auth "username", "password"
+  #
+  # == SSL client authentication
+  #
+  # You can use the methods provided by Net::HTTP to set SSL client authentication or use a shortcut:
+  #
+  #   client.request.http.ssl_client_auth(
+  #     :cert => OpenSSL::X509::Certificate.new(File.read("client_cert.pem")),
+  #     :key => OpenSSL::PKey::RSA.new(File.read("client_key.pem"), "password if one exists"),
+  #     :ca_file => "cacert.pem",
+  #     :verify_mode => OpenSSL::SSL::VERIFY_PEER
+  #   )
+  #
+  # == HTTP headers
+  #
+  # There's an accessor for the Hash of HTTP headers sent with any SOAP call:
+  #
+  #   client.request.headers["custom"] = "header"
   class Request
+    include Logger
 
     # Content-Types by SOAP version.
     ContentType = { 1 => "text/xml;charset=UTF-8", 2 => "application/soap+xml;charset=UTF-8" }
 
-    # Whether to log HTTP requests.
-    @@log = true
-
-    # The default logger.
-    @@logger = Logger.new STDOUT
-
-    # The default log level.
-    @@log_level = :debug
-
-    # Sets whether to log HTTP requests.
-    def self.log=(log)
-      @@log = log
-    end
-
-    # Returns whether to log HTTP requests.
-    def self.log?
-      @@log
-    end
-
-    # Sets the logger.
-    def self.logger=(logger)
-      @@logger = logger
-    end
-
-    # Returns the logger.
-    def self.logger
-      @@logger
-    end
-
-    # Sets the log level.
-    def self.log_level=(log_level)
-      @@log_level = log_level
-    end
-
-    # Returns the log level.
-    def self.log_level
-      @@log_level
-    end
-
     # Expects a SOAP +endpoint+ String. Also accepts an optional Hash
     # of +options+ for specifying a proxy server.
     def initialize(endpoint, options = {})
@@ -83,8 +82,7 @@ module Savon
       http.start { |h| h.request request(:wsdl) }
     end
 
-    # Executes a SOAP request using a given Savon::SOAP instance and
-    # returns the Net::HTTP response.
+    # Executes a SOAP request using a given Savon::SOAP instance and returns the Net::HTTP response.
     def soap(soap)
       @soap = soap
       http.endpoint @soap.endpoint.host, @soap.endpoint.port
@@ -118,8 +116,7 @@ module Savon
       log @response.body
     end
 
-    # Returns a Net::HTTP request for a given +type+. Yields the request
-    # to an optional block.
+    # Returns a Net::HTTP request for a given +type+. Yields the request to an optional block.
     def request(type)
       request = case type
         when :wsdl then Net::HTTP::Get.new @endpoint.request_uri
@@ -136,10 +133,5 @@ module Savon
       { "Content-Type" => ContentType[@soap.version], "SOAPAction" => @soap.action }
     end
 
-    # Logs a given +message+.
-    def log(message)
-      self.class.logger.send self.class.log_level, message if self.class.log?
-    end
-
   end
 end