smacks-savon 0.0.4 → 0.0.5

data/README.rdoc

@@ -2,10 +2,52 @@
 
 Savon is a lightweight SOAP client.
 
+Instantiate Savon::Service and pass in the WSDL of the service you would
+like to use. Then just call the SOAP service method on your Savon::Service
+instance (catched via method_missing) and pass in a Hash of options for the
+service method to receive.
+
 == Install
 
-  $ sudo gem install smacks-savon --source http://gems.github.com
+  $ gem install smacks-savon --s http://gems.github.com
 
 == Dependencies
 
-  Hpricot 0.6.164 (also available for JRuby)
+  Hpricot 0.6.164 (also available for JRuby)
+
+=== Usage example
+
+  proxy = Savon::Service.new "http://example.com/ExampleService?wsdl"
+  response = proxy.findExampleById(:id => 123)
+
+=== Check for available SOAP service methods
+
+  proxy.wsdl.service_methods
+  => [ "findExampleById", "findExampleByName" ]
+
+=== Checking for HTTP and SOAP faults
+
+  response.success?
+  response.fault?
+
+=== Access the fault message and code
+
+  response.fault
+  response.fault_code
+
+=== Working with different response formats
+
+  # raw XML response:
+  response.to_s
+
+  # response as a Hash
+  response.to_hash
+
+  # response as a Hash starting at a custom root node (via XPath)
+  response.to_hash("//item")
+
+  # response as a Mash
+  response.to_mash
+
+  # response as a Mash starting at a custom root node (via XPath)
+  response.to_mash("//user/email")

data/lib/savon/response.rb

@@ -1,29 +1,84 @@
-# -*- coding: utf-8 -*-
-require 'rubygems'
-require 'apricoteatsgorilla'
+require "rubygems"
+require "hpricot"
+require "apricoteatsgorilla"
 
 module Savon
 
-  # Savon::Response represents the SOAP response and includes methods for
-  # working with the raw XML, a Hash or a Savon::Mash object.
+  # Savon::Response represents the HTTP response.
+  #
+  # === Checking for HTTP and SOAP faults
+  #
+  #   response.success?
+  #   response.fault?
+  #
+  # === Access the fault message and code
+  #
+  #   response.fault
+  #   response.fault_code
+  #
+  # === Different response formats
+  #
+  #   # raw XML response:
+  #   response.to_s
+  #
+  #   # response as a Hash
+  #   response.to_hash
+  #
+  #   # response as a Hash starting at a custom root node (via XPath)
+  #   response.to_hash("//item")
+  #
+  #   # response as a Mash
+  #   response.to_mash
+  #
+  #   # response as a Mash starting at a custom root node (via XPath)
+  #   response.to_mash("//user/email")
+  #
+  # ===
   class Response
 
+    attr_reader :fault, :fault_code
+
     # Initializer to set the SOAP response.
+    #
+    # === Parameters
+    #
+    # * +response+ - The Net::HTTP response.
     def initialize(response)
       @response = response
+      validate
+    end
+
+    # Returns true if the request was successful, false otherwise.
+    def success?
+      @fault_code.nil?
+    end
+
+    # Returns true if the request was not successful, false otherwise.
+    def fault?
+      !@fault.nil?
     end
 
     # Returns the SOAP response message as a Hash. Call with XPath expession
-    # as parameter to define a custom root node. The root node itself will not
-    # be included in the Hash.
+    # to define a custom +root_node+ to start parsing at. Defaults to "//return".
+    # The root node itself will not be included in the Hash.
+    #
+    # === Parameters
+    #
+    # * +root_node+ - Optional. Custom root node to start parsing at. Defaults to "//return".
     def to_hash(root_node = "//return")
-      ApricotEatsGorilla(@response.body, root_node)
+      return nil if fault?
+      ApricotEatsGorilla[@response.body, root_node]
     end
 
     # Returns the SOAP response message as a Savon::Mash object. Call with
-    # XPath expession as parameter to define a custom root node. The root node
-    # itself will not be included in the Mash object.
+    # XPath expession to define a custom +root_node+. Defaults to "//return".
+    # The root node itself will not be included in the Mash object.
+    #
+    # === Parameters
+    #
+    # * +root_node+ - Optional. Custom root node to start parsing at. Defaults to "//return".
     def to_mash(root_node = "//return")
+      return nil if fault?
       hash = to_hash(root_node)
       Savon::Mash.new(hash)
     end
@@ -33,30 +88,19 @@ module Savon
       @response.body
     end
 
-  end
+  private
 
-  # Savon::Mash converts a given Hash into a Mash object.
-  class Mash
-
-    def initialize(hash)
-      hash.each do |key,value|
-        value = Savon::Mash.new value if value.is_a? Hash
-
-        if value.is_a? Array
-          value = value.map do |item|
-            if item.is_a?(Hash) then Savon::Mash.new(item) else item end
-          end
-        end
-
-        # Create and initialize an instance variable for this key/value pair
-        self.instance_variable_set("@#{key}", value)
-        # Create the getter that returns the instance variable
-        self.class.send(:define_method, key, proc{self.instance_variable_get("@#{key}")})
-        # Create the setter that sets the instance variable
-        self.class.send(:define_method, "#{key}=", proc{|value| self.instance_variable_set("@#{key}", value)})
+    # Checks for and stores HTTP and SOAP-Fault errors.
+    def validate
+      if @response.code.to_i >= 300
+        @fault = @response.message
+        @fault_code = @response.code
+      else
+        fault = to_hash("//soap:Fault")
+        @fault = fault[:faultstring] unless fault.nil?
+        @fault_code = fault[:faultcode] unless fault.nil?
       end
     end
 
   end
-
 end

data/lib/savon/service.rb

@@ -1,43 +1,58 @@
-# -*- coding: utf-8 -*-
-require 'rubygems'
-require 'net/http'
-require 'uri'
-require 'apricoteatsgorilla'
+require "rubygems"
+require "net/http"
+require "uri"
+require "apricoteatsgorilla"
 
 module Savon
 
-  # Savon::Service is the actual SOAP client implementation to use.
+  # Savon is a lightweight SOAP client.
   #
   # Instantiate Savon::Service and pass in the WSDL of the service you would
-  # like to work with. Then simply call the SOAP service method on your
-  # instance (which will be catched via method_missing) and pass in a Hash
-  # of options you would like to send.
+  # like to use. Then just call the SOAP service method on your Savon::Service
+  # instance (catched via method_missing) and pass in a Hash of options for the
+  # service method to receive.
+  #
+  # === Usage example
   #
-  # Example:
   #   proxy = Savon::Service.new "http://example.com/ExampleService?wsdl"
-  #   response = proxy.findExampleById(:id => "123")
+  #   response = proxy.findExampleById(:id => 123)
+  #
+  # === Check for available SOAP service methods
+  #
+  #   proxy.wsdl.service_methods
+  #   # => [ "findExampleById", "findExampleByName" ]
   #
-  # Get the raw response XML:
+  # === Working with different response formats
+  #
+  #   # raw XML response:
   #   response.to_s
   #
-  # Get it as a Hash (offers optional XPath expression to set a custom root node):
+  #   # response as a Hash
   #   response.to_hash
-  #   response.to_hash("//return")
   #
-  # Or as a Mash object (also offers specifying a custom root node):
+  #   # response as a Hash starting at a custom root node (via XPath)
+  #   response.to_hash("//item")
+  #
+  #   # response as a Mash
   #   response.to_mash
+  #
+  #   # response as a Mash starting at a custom root node (via XPath)
   #   response.to_mash("//user/email")
   class Service
 
-    # Sets the HTTP connection instance.
+    # The Net::HTTP connection instance to use.
     attr_writer :http
 
-    # Initializer sets the endpoint URI.
+    # Initializer sets the WSDL +endpoint+ URI.
+    #
+    # ==== Parameters
+    #
+    # * +endpoint+ - The WSDL endpoint URI.
     def initialize(endpoint)
       @uri = URI(endpoint)
     end
 
-    # Returns an Wsdl instance.
+    # Returns an instance of the WSDL.
     def wsdl
       @wsdl = Savon::Wsdl.new(@uri, http) if @wsdl.nil?
       @wsdl
@@ -45,37 +60,34 @@ module Savon
 
   private
 
-    # Sets up the request headers and body, makes the request and returns a
-    # Savon::Response object.
+    # Prepares and processes the SOAP request. Returns a Savon::Response object.
     def call_service
-      headers = { 'Content-Type' => 'text/xml; charset=utf-8', 'SOAPAction' => @action }
+      headers = { "Content-Type" => "text/xml; charset=utf-8", "SOAPAction" => @action }
       body = ApricotEatsGorilla.soap_envelope("wsdl" => wsdl.namespace_uri) do
-        ApricotEatsGorilla("wsdl:#{@action}" => namespaced_options)
+        ApricotEatsGorilla["wsdl:#{@action}" => namespaced_options]
       end
       response = @http.request_post(@uri.path, body, headers)
       Savon::Response.new(response)
     end
 
-    # Returns an HTTP connection instance.
+    # Returns the Net::HTTP instance to use.
     def http
       if @http.nil?
         raise ArgumentError, "Invalid endpoint URI" unless @uri.scheme
         @http = Net::HTTP.new(@uri.host, @uri.port)
-        #@http.set_debug_output(STDOUT)
-        #@http.read_timeout = 5
       end
       @http
     end
 
-    # Checks if the requestion SOAP action is available.
-    # Raises an ArgumentError in case it isn't.
+    # Checks if the requested SOAP service method is available.
+    # Raises an ArgumentError in case it is not.
     def validate_action
       unless wsdl.service_methods.include? @action
         raise ArgumentError, "Invalid service method '#{@action}'"
       end
     end
 
-    # Checks if there were any choice elements found in the wsdl and namespaces
+    # Checks if there were any choice elements found in the WSDL and namespaces
     # the corresponding keys from the passed in Hash of options.
     def namespaced_options
       return @options if wsdl.choice_elements.empty?
@@ -97,7 +109,12 @@ module Savon
       options
     end
 
-    # Catches calls to SOAP service methods.
+    # Intercepts calls to SOAP service methods.
+    #
+    # === Parameters
+    #
+    # * +method+ - The SOAP service method to call.
+    # * +options+ - Hash of options for the service method to receive.
     def method_missing(method, options = {})
       @action = method.to_s
       @options = options

data/lib/savon/wsdl.rb

@@ -1,7 +1,6 @@
-# -*- coding: utf-8 -*-
-require 'rubygems'
-require 'net/http'
-require 'hpricot'
+require "rubygems"
+require "net/http"
+require "hpricot"
 
 module Savon
 
@@ -11,14 +10,19 @@ module Savon
     # The namespace URI.
     attr_reader :namespace_uri
 
-    # Available service methods.
+    # SOAP service methods.
     attr_reader :service_methods
 
     # Choice elements.
     attr_reader :choice_elements
 
-    # Initializer expects an endpoint URI and an HTTP connection instance.
-    # Gets and parses the WSDL at the given URI.
+    # Initializer expects an endpoint +uri+ and an +http+ connection instance,
+    # then gets and parses the WSDL at the given URI.
+    #
+    # === Parameters
+    #
+    # * +uri+ - The URI to access.
+    # * +http+ - The Net::HTTP connection instance to use.
     def initialize(uri, http)
       @uri = uri
       @http = http
@@ -42,16 +46,16 @@ module Savon
     # Parses the WSDL for the namespace URI, available service methods
     # and choice elements.
     def parse_wsdl
-      @namespace_uri = @doc.at('//wsdl:definitions').get_attribute('targetNamespace')
+      @namespace_uri = @doc.at("//wsdl:definitions").get_attribute("targetNamespace")
 
       @service_methods = []
-      @doc.search('//soap:operation').each do |operation|
-        service_methods << operation.parent.get_attribute('name')
+      @doc.search("//soap:operation").each do |operation|
+        service_methods << operation.parent.get_attribute("name")
       end
 
       @choice_elements = []
-      @doc.search('//xs:choice//xs:element').each do |choice|
-        name = choice.get_attribute('ref').sub(/(.+):/, '')
+      @doc.search("//xs:choice//xs:element").each do |choice|
+        name = choice.get_attribute("ref").sub(/(.+):/, "")
         choice_elements << name unless @choice_elements.include? name
       end
     end

data/lib/savon.rb

@@ -1,5 +1,5 @@
-# -*- coding: utf-8 -*-
-$:.unshift(File.join(File.dirname(__FILE__), 'savon'))
-require 'response'
-require 'wsdl'
-require 'service'
+$:.unshift(File.join(File.dirname(__FILE__), "savon"))
+require "service"
+require "response"
+require "wsdl"
+require "mash"

data/tests/fixtures/soap_response.rb

@@ -12,4 +12,23 @@ module SoapResponseFixture
     </soap:Envelope>'
   end
 
+  def soap_fault_response
+    '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+       <soap:Body>
+          <soap:Fault>
+             <faultcode>' << soap_fault_code << '</faultcode>
+             <faultstring>' << soap_fault << '</faultstring>
+          </soap:Fault>
+       </soap:Body>
+    </soap:Envelope>'
+  end
+
+  def soap_fault
+    "Failed to authenticate client."
+  end
+
+  def soap_fault_code
+    "soap:Server"
+  end
+
 end

data/tests/helper.rb

@@ -1,13 +1,10 @@
-require 'rubygems'
-require 'test/unit'
-require 'mocha'
-require 'shoulda'
+require "rubygems"
+require "test/unit"
+require "mocha"
+require "shoulda"
 require "apricoteatsgorilla"
 
-["service", "wsdl", "response"].each do |file|
-  require File.join(File.dirname(__FILE__), "..", "lib", "savon", file)
-end
-
+require File.join(File.dirname(__FILE__), "..", "lib", "savon")
 require File.join(File.dirname(__FILE__), "factories", "wsdl")
 require File.join(File.dirname(__FILE__), "fixtures", "soap_response")
 
@@ -35,10 +32,18 @@ module TestHelper
   end
 
   def response_mock(response_body)
-    response_mock = mock('Net::HTTPResponse')
+    build_response_mock("200", "OK", response_body)
+  end
+
+  def response_fault_mock
+    build_response_mock("404", "NotFound")
+  end
+
+  def build_response_mock(code, message, body = nil)
+    response_mock = mock("Net::HTTPResponse")
     response_mock.stubs(
-      :code => '200', :message => "OK", :content_type => "text/html",
-      :body => response_body
+      :code => code, :message => message, :content_type => "text/html",
+      :body => body
     )
     response_mock
   end

data/tests/savon/mash_test.rb

@@ -0,0 +1,9 @@
+require File.join(File.dirname(__FILE__), "..", "helper")
+
+class SavonMashTest < Test::Unit::TestCase
+
+  def test_nupsi
+    assert true
+  end
+
+end

data/tests/savon/response_test.rb

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 require File.join(File.dirname(__FILE__), "..", "helper")
 
 class SavonResponseTest < Test::Unit::TestCase
@@ -17,7 +16,7 @@ class SavonResponseTest < Test::Unit::TestCase
     end
 
     should "return a Hash equal to the response on to_hash" do
-      assert_equal ApricotEatsGorilla(some_soap_response, "//return"), @response.to_hash
+      assert_equal ApricotEatsGorilla[some_soap_response, "//return"], @response.to_hash
     end
 
     should "return a Mash object on to_mash" do
@@ -31,6 +30,93 @@ class SavonResponseTest < Test::Unit::TestCase
     should "return the raw XML response on to_s" do
       assert_equal some_soap_response, @response.to_s
     end
+
+    should "return 'true' on success?" do
+      assert_equal true, @response.success?
+    end
+
+    should "return 'false' on fault?" do
+      assert_equal false, @response.fault?
+    end
+
+    should "return 'nil' for fault" do
+      assert_equal nil, @response.fault
+    end
+
+    should "return 'nil' for fault_code" do
+      assert_equal nil, @response.fault_code
+    end
+  end
+
+  context "Savon::Response with SOAP::Fault response" do
+    setup do
+      ApricotEatsGorilla.sort_keys = true
+      @response = Savon::Response.new(response_mock(soap_fault_response))
+    end
+
+    should "return 'nil' on to_hash" do
+      assert_equal nil, @response.to_hash
+    end
+
+    should "return 'nil' on to_mash" do
+      assert_equal nil, @response.to_mash
+    end
+
+    should "return the raw XML response on to_s" do
+      assert_equal soap_fault_response, @response.to_s
+    end
+
+    should "return 'false' on success?" do
+      assert_equal false, @response.success?
+    end
+
+    should "return 'true' on fault?" do
+      assert_equal true, @response.fault?
+    end
+
+    should "return the fault on fault" do
+      assert_equal soap_fault, @response.fault
+    end
+
+    should "return the fault_code on fault_code" do
+      assert_equal soap_fault_code, @response.fault_code
+    end
+  end
+
+  context "Savon::Response with 404 error" do
+    setup do
+      ApricotEatsGorilla.sort_keys = true
+      @response = Savon::Response.new(response_fault_mock)
+    end
+
+    should "return 'nil' on to_hash" do
+      assert_equal nil, @response.to_hash
+    end
+
+    should "return 'nil' on to_mash" do
+      assert_equal nil, @response.to_mash
+    end
+
+    should "return nil on to_s" do
+      assert_equal nil, @response.to_s
+    end
+
+    should "return 'false' on success?" do
+      assert_equal false, @response.success?
+    end
+
+    should "return 'true' on fault?" do
+      assert_equal true, @response.fault?
+    end
+
+    should "return the fault on fault" do
+      assert_equal "NotFound", @response.fault
+    end
+
+    should "return the fault_code on fault_code" do
+      assert_equal "404", @response.fault_code
+    end
+
   end
 
 end

data/tests/savon/service_test.rb

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 require File.join(File.dirname(__FILE__), "..", "helper")
 
 class SavonServiceTest < Test::Unit::TestCase

data/tests/savon/wsdl_test.rb

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 require File.join(File.dirname(__FILE__), "..", "helper")
 
 class SavonWsdlTest < Test::Unit::TestCase

data/tests/savon_test.rb

@@ -1,5 +1,5 @@
-# -*- coding: utf-8 -*-
 $:.unshift(File.join(File.dirname(__FILE__), 'savon'))
-require "service_test"
+require "mash_test"
 require "wsdl_test"
-require "response_test"
+require "response_test"
+require "service_test"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: smacks-savon
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors: 
 - Daniel Harrington
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.2.8
+        version: 0.3.31
     version: 
 description: Savon is a lightweight SOAP client.
 email: 
@@ -79,5 +79,6 @@ test_files:
 - tests/factories/wsdl.rb
 - tests/fixtures/soap_response.rb
 - tests/savon/service_test.rb
-- tests/savon/wsdl_test.rb
 - tests/savon/response_test.rb
+- tests/savon/wsdl_test.rb
+- tests/savon/mash_test.rb