savon 0.7.5 → 0.7.6

data/lib/savon/response.rb

@@ -1,8 +1,61 @@
 module Savon
 
-  # == Savon::Response
+  # = Savon::Response
   #
-  # Represents the HTTP and SOAP response.
+  # Savon::Response represents both HTTP and SOAP response.
+  #
+  # == SOAP fault
+  #
+  # Assuming the default behavior of raising errors is disabled, you can ask the response object
+  # if there was a SOAP fault or an HTTP error and get the SOAP fault or HTTP error message.
+  #
+  #   response.soap_fault?
+  #   # => true
+  #
+  #   response.soap_fault
+  #   # => "(soap:Server) Fault occurred while processing."
+  #
+  #   response.http_error?
+  #   # => true
+  #
+  #   response.http_error
+  #   # => "Not found (404)"
+  #
+  # == Response as XML
+  #
+  # To get the raw SOAP response XML, you can call to_xml or to_s on the response object.
+  #
+  #   response.to_xml
+  #   => "<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  #   => "..."
+  #   => "</soap:Envelope>"
+  #
+  # == Response as a Hash
+  #
+  # You can also let Savon translate the SOAP response body to a Hash.
+  #
+  #   response.to_hash
+  #   => { :findUserByIdResponse => {
+  #   =>   :id => "123",
+  #   =>   :username => "eve"
+  #   =>   :active => true
+  #   => }
+  #
+  # When translating the SOAP response to a Hash, some XML tags and values are converted to more
+  # convenient Ruby objects. Translation is done through John Nunemaker's {Crack}[http://github.com/jnunemaker/crack]
+  # library along with some custom mapping.
+  #
+  # * XML tags (Hash keys) are converted to snake_case Symbols and namespaces are stripped off
+  # * SOAP xs:nil values are converted to nil objects
+  # * XML values specified in xs:DateTime format are converted to DateTime objects
+  # * XML values of "true" and "false" are converted to TrueClass and FalseClass
+  #
+  # == Net::HTTP response
+  #
+  # If for some reason you need to access the Net::HTTP response object ... you can.
+  #
+  #   bc. response.http
+  #   => #<Net::HTTPOK:0x7f749a1aa4a8>
   class Response
 
     # The maximum HTTP response code considered to be OK.
@@ -57,13 +110,13 @@ module Savon
 
     # Returns the HTTP response object.
     attr_reader :http
-	
+
     alias :to_s :to_xml
 
   private
 
-    # Handles SOAP faults. Raises a Savon::SOAPFault unless the default
-    # behavior of raising errors was turned off.
+    # Handles SOAP faults. Raises a Savon::SOAPFault unless the default behavior of raising errors
+    # was turned off.
     def handle_soap_fault
       if soap_fault_message
         @soap_fault = soap_fault_message
@@ -76,8 +129,8 @@ module Savon
       @soap_fault_message ||= soap_fault_message_by_version to_hash[:fault]
     end
 
-    # Expects a Hash that might contain information about a SOAP fault.
-    # Returns the SOAP fault message in case one was found.
+    # Expects a Hash that might contain information about a SOAP fault. Returns the SOAP fault
+    # message in case one was found.
     def soap_fault_message_by_version(soap_fault)
       return unless soap_fault
 
@@ -88,8 +141,8 @@ module Savon
       end
     end
 
-    # Handles HTTP errors. Raises a Savon::HTTPError unless the default
-    # behavior of raising errors was turned off.
+    # Handles HTTP errors. Raises a Savon::HTTPError unless the default behavior of raising errors
+    # was turned off.
     def handle_http_error
       if @http.code.to_i > MaxNonErrorResponseCode
         @http_error = "#{@http.message} (#{@http.code})"

data/lib/savon/soap.rb

@@ -1,10 +1,123 @@
 module Savon
 
-  # == Savon::SOAP
+  # = Savon::SOAP
   #
-  # Represents the SOAP parameters and envelope.
+  # 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.
+  #
+  # == Body
+  #
+  # The body method lets you specify parameters to be received by the SOAP action.
+  #
+  # You can either pass in a hash (which will be translated to XML via Hash.to_soap_xml):
+  #
+  #   response = client.get_user_by_id do |soap|
+  #     soap.body = { :id => 123 }
+  #   end
+  #
+  # Or a string containing the raw XML:
+  #
+  #   response = client.get_user_by_id do |soap|
+  #     soap.body = "<id>123</id>"
+  #   end
+  #
+  # Request output:
+  #
+  #   <env:Envelope
+  #       xmlns:wsdl="http://example.com/user/1.0/UserService"
+  #       xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+  #     <env:Body>
+  #       <wsdl:getUserById><id>123</id></wsdl:getUserById>
+  #     </env:Body>
+  #   </env:Envelope>
+  #
+  # Please look at the documentation of Hash.to_soap_xml for some more information.
+  #
+  # == Version
+  #
+  # Savon defaults to SOAP 1.1. In case your service uses SOAP 1.2, you can use the version method
+  # to change the default per request.
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.version = 2
+  #   end
+  #
+  # You can also change the default to SOAP 1.2 for all request:
+  #
+  #   Savon::SOAP.version = 2
+  #
+  # == Header
+  #
+  # If you need to add custom XML into the SOAP header, you can use the header method.
+  #
+  # The value is expected to be a hash (which will be translated to XML via Hash.to_soap_xml):
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.header["specialApiKey"] = "secret"
+  #   end
+  #
+  # Or a string containing the raw XML:
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.header = "<specialApiKey>secret</specialApiKey>"
+  #   end
+  #
+  # Request output:
+  #
+  #   <env:Envelope
+  #       xmlns:wsdl="http://example.com/user/1.0/UserService"
+  #       xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+  #     <env:Header>
+  #       <specialApiKey>secret</specialApiKey>
+  #     </env:Header>
+  #     <env:Body>
+  #       <wsdl:getAllUsers></wsdl:getAllUsers>
+  #     </env:Body>
+  #   </env:Envelope>
+  #
+  # == Namespaces
+  #
+  # The namespaces method contains a hash of attributes for the SOAP envelope. You can overwrite it
+  # or add additional attributes.
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.namespaces["xmlns:domains"] = "http://domains.example.com"
+  #   end
+  #
+  # Request output:
+  #
+  #   <env:Envelope
+  #       xmlns:wsdl="http://example.com/user/1.0/UserService"
+  #       xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
+  #       xmlns:domains="http://domains.example.com">
+  #     <env:Body>
+  #       <wsdl:getAllUsers></wsdl:getAllUsers>
+  #     </env:Body>
+  #   </env:Envelope>
+  #
+  # == Input
+  #
+  # You can change the name of the SOAP input tag in case you need to.
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.input = "GetAllUsersRequest"
+  #   end
+  #
+  # Request output:
+  #
+  #   <env:Envelope
+  #       xmlns:wsdl="http://example.com/user/1.0/UserService"
+  #       xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+  #     <env:Body>
+  #       <wsdl:GetAllUsersRequest></wsdl:GetAllUsersRequest>
+  #     </env:Body>
+  #   </env:Envelope>
   class SOAP
 
+    # Supported SOAP versions.
+    Versions = [1, 2]
+
     # SOAP namespaces by SOAP version.
     Namespace = {
       1 => "http://schemas.xmlsoap.org/soap/envelope/",
@@ -14,9 +127,6 @@ module Savon
     # Content-Types by SOAP version.
     ContentType = { 1 => "text/xml", 2 => "application/soap+xml" }
 
-    # Supported SOAP versions.
-    Versions = [1, 2]
-
     # SOAP xs:dateTime format.
     DateTimeFormat = "%Y-%m-%dT%H:%M:%SZ"
 
@@ -36,8 +146,8 @@ module Savon
       @@version = version if Versions.include? version
     end
 
-    # Sets the global SOAP header. Expected to be a Hash that can be translated
-    # to XML via Hash.to_soap_xml or any other Object responding to to_s.
+    # Sets the global SOAP header. Expected to be a Hash that can be translated to XML via
+    # Hash.to_soap_xml or any other Object responding to to_s.
     def self.header=(header)
       @@header = header
     end
@@ -47,21 +157,21 @@ module Savon
       @@header ||= {}
     end
 
-    # Sets the global namespaces. Expected to be a Hash containing the
-    # namespaces (keys) and the corresponding URI's (values).
+    # Sets the global namespaces. Expected to be a Hash containing the namespaces (keys) and the
+    # corresponding URI's (values).
     def self.namespaces=(namespaces)
       @@namespaces = namespaces if namespaces.kind_of? Hash
     end
 
-    # Returns the global namespaces. A Hash containing the namespaces (keys)
-    # and the corresponding URI's (values).
+    # Returns the global namespaces. A Hash containing the namespaces (keys) and the corresponding
+    # URI's (values).
     def self.namespaces
       @@namespaces ||= {}
     end
 
-    # Initialzes the SOAP object.
-    def initialize(operation, endpoint)
-      @action, @input = operation[:action], operation[:input]
+    # Initialzes the SOAP object. Expects a SOAP +operation+ Hash along with an +endpoint+.
+    def initialize(action, input, endpoint)
+      @action, @input = action, input
       @endpoint = endpoint.kind_of?(URI) ? endpoint : URI(endpoint)
       @builder = Builder::XmlMarkup.new
     end
@@ -88,8 +198,8 @@ module Savon
     # Accessor for the SOAP endpoint.
     attr_accessor :endpoint
 
-    # Sets the SOAP header. Expected to be a Hash that can be translated
-    # to XML via Hash.to_soap_xml or any other Object responding to to_s.
+    # Sets the SOAP header. Expected to be a Hash that can be translated to XML via Hash.to_soap_xml
+    # or any other Object responding to to_s.
     attr_writer :header
 
     # Returns the SOAP header. Defaults to an empty Hash.
@@ -97,21 +207,25 @@ module Savon
       @header ||= {}
     end
 
-    # Sets the SOAP body. Expected to be a Hash that can be translated to
-    # XML via Hash.to_soap_xml or any other Object responding to to_s.
-    attr_writer :body
+    # Accessor for the SOAP body. Expected to be a Hash that can be translated to XML via Hash.to_soap_xml
+    # or any other Object responding to to_s.
+    attr_accessor :body
 
-    # Sets the namespaces. Expected to be a Hash containing the namespaces
-    # (keys) and the corresponding URI's (values).
+    # Accessor for overwriting the default SOAP request. Let's you specify completely custom XML.
+    attr_accessor :xml
+
+    # Sets the namespaces. Expected to be a Hash containing the namespaces (keys) and the
+    # corresponding URI's (values).
     attr_writer :namespaces
 
-    # Returns the namespaces. A Hash containing the namespaces (keys)
-    # and the corresponding URI's (values).
+    # Returns the namespaces. A Hash containing the namespaces (keys) and the corresponding URI's
+    # (values). Defaults to a Hash containing an +xmlns:env+ key and the namespace for the current
+    # SOAP version.
     def namespaces
       @namespaces ||= { "xmlns:env" => Namespace[version] }
     end
 
-    # Convenience method for setting the "xmlns:wsdl" namespace.
+    # Convenience method for setting the +xmlns:wsdl+ namespace.
     def namespace=(namespace)
       namespaces["xmlns:wsdl"] = namespace
     end
@@ -128,25 +242,28 @@ module Savon
 
     # Returns the SOAP envelope XML.
     def to_xml
-      unless @xml_body
-        @xml_body = @builder.env :Envelope, all_namespaces do |xml|
-          xml.env(:Header) { xml << all_header } unless all_header.empty?
+      unless @xml
+        @builder.instruct!
+        @xml = @builder.env :Envelope, merged_namespaces do |xml|
+          xml.env(:Header) { xml << merged_header } unless merged_header.empty?
           xml_body xml
         end
       end
-      @xml_body
+      @xml
     end
 
   private
 
     # Returns a String containing the global and per request header.
-    def all_header
+    def merged_header
       if self.class.header.kind_of?(Hash) && header.kind_of?(Hash)
-        custom_header = self.class.header.merge(header).to_soap_xml
+        merged_header = self.class.header.merge(header).to_soap_xml
       else
-        custom_header = self.class.header.to_s + header.to_s
+        global_header = self.class.header.to_soap_xml rescue self.class.header.to_s
+        request_header = header.to_soap_xml rescue header.to_s
+        merged_header = global_header + request_header
       end
-      custom_header + wsse_header
+      merged_header + wsse_header
     end
 
     # Returns the WSSE header or an empty String in case WSSE was not set.
@@ -157,26 +274,24 @@ module Savon
     # Adds a SOAP XML body to a given +xml+ Object.
     def xml_body(xml)
       xml.env(:Body) do
-        xml.tag!(:wsdl, *input_array) do
-          xml << (@body.to_soap_xml rescue @body.to_s)
-        end
+        xml.tag!(:wsdl, *input_array) { xml << (@body.to_soap_xml rescue @body.to_s) }
       end
     end
 
     # Returns a Hash containing the global and per request namespaces.
-    def all_namespaces
+    def merged_namespaces
       self.class.namespaces.merge namespaces
     end
 
-    # Returns an Array of SOAP input names to append to the :wsdl namespace.
-    # Defaults to use the name of the SOAP action and may be an empty Array
-    # in case the specified SOAP input seems invalid.
+    # Returns an Array of SOAP input names to append to the wsdl namespace. Defaults to use the
+    # name of the SOAP action. May return an empty Array in case the specified SOAP input seems
+    # to be invalid.
     def input_array
-      if !input.blank? && input.kind_of?(Array)
+      if input.kind_of?(Array) && !input.blank?
         [input[0].to_sym, input[1]]
       elsif !input.blank?
         [input.to_sym]
-      elsif action.blank?
+      elsif !action.blank?
         [action.to_sym]
       else
         []
@@ -184,4 +299,4 @@ module Savon
     end
 
   end
-end
+end

data/lib/savon/wsdl.rb

@@ -1,8 +1,74 @@
 module Savon
 
-  # Savon::WSDL
+  # = Savon::WSDL
   #
-  # Represents the WSDL document.
+  # Savon::WSDL represents the WSDL of your service, including information like the namespace URI,
+  # the SOAP endpoint and available SOAP actions.
+  #
+  # == The WSDL document
+  #
+  # Retrieve the raw WSDL document:
+  #
+  #   client.wsdl.to_s
+  #
+  # == Available SOAP actions
+  #
+  # Get an array of available SOAP actions:
+  #
+  #   client.wsdl.soap_actions
+  #   # => [:get_all_users, :get_user_by_id]
+  #
+  # == Namespace URI
+  #
+  # Get the namespace URI:
+  #
+  #   client.wsdl.namespace_uri
+  #   # => "http://ws.userservice.example.com"
+  #
+  # == SOAP endpoint
+  #
+  # Get the SOAP endpoint:
+  #
+  #   client.wsdl.soap_endpoint
+  #   # => "http://example.com"
+  #
+  # == Disable Savon::WSDL
+  #
+  # Especially with large services (i.e. Ebay), getting and parsing the WSDL document can really
+  # slow down your request. The WSDL is great for exploring a service, but it's recommended to
+  # disable it for production.
+  #
+  # When disabling the WSDL, you need to pay attention to certain differences:
+  #
+  # 1. You instantiate Savon::Client with the actual SOAP endpoint instead of pointing it to the
+  #    WSDL of your service.
+  # 2. You also need to manually specify the SOAP.namespace.
+  # 3. Append an exclamation mark (!) to your SOAP call:
+  #
+  #   client = Savon::Client.new "http://example.com"
+  #
+  #   client.get_user_by_id! do |soap|
+  #     soap.namespace = "http://example.com/UserService"
+  #     soap.body = { :id => 666 }
+  #   end
+  #
+  # Without the WSDL, Savon also has to guess the name of the SOAP action and input tag. It takes
+  # the name of the method called on its client instance, converts it from snake_case to lowerCamelCase
+  # and uses the result.
+  #
+  # The example above expects a SOAP action with an original name of "getUserById". If you service
+  # uses UpperCamelCase method names, you can just use the original name:
+  #
+  #   client.GetAllUsers!
+  #
+  # For special cases, you could also specify the SOAP.action and SOAP.input inside the block:
+  #
+  #   client.get_user_by_id! do |soap|
+  #     soap.namespace = "http://example.com/UserService"
+  #     soap.action = "GetUserById"
+  #     soap.input = "GetUserByIdRequest"
+  #     soap.body = { :id => 123 }
+  #   end
   class WSDL
 
     # Initializer, expects a Savon::Request.
@@ -45,11 +111,10 @@ module Savon
       super
     end
 
-    # Returns a SOAP operation Hash containing the SOAP action and input
-    # for a given +soap_call+.
+    # Returns an Array containg the SOAP action and input for a given +soap_call+.
     def operation_from(soap_action)
-      return operations[soap_action] if enabled?
-      { :action => soap_action.to_soap_key, :input => soap_action.to_soap_key }
+      return [soap_action.to_soap_key, soap_action.to_soap_key] unless enabled?
+      [operations[soap_action][:action], operations[soap_action][:input]]
     end
 
     # Returns the raw WSDL document.