smacks-savon 0.0.91 → 0.1.0

data/README.rdoc

@@ -1,11 +1,12 @@
 = Savon
 
-Savon is a lightweight SOAP client.
+Ruby SOAP client library to enjoy.
 
-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.
+Communicating with a SOAP webservice can be done in two lines of code.
+Instantiate a new Savon::Service passing in the URI to the WSDL of the
+service you would like to use. Then 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
 
@@ -14,43 +15,66 @@ service method to receive.
 == Dependencies
 
   hpricot 0.6.164 (also available for JRuby)
-  smacks-apricoteatsgorilla >= 0.3.5
+  smacks-apricoteatsgorilla >= 0.4.1
 
 == How to use
 
-=== Usage example
+Instantiate a new Savon::Service instance passing in the WSDL of your service.
 
   proxy = Savon::Service.new "http://example.com/ExampleService?wsdl"
+
+Call the SOAP service method you would like to choose on your Savon::Service
+instance passing in a Hash of options for the service method to receive.
+
   response = proxy.findExampleById(:id => 123)
 
 === Check for available SOAP service methods
 
+You can use the service_methods method of the WSDL in your Savon::Service
+instance to get a list of available SOAP service methods.
+
   proxy.wsdl.service_methods
   # => [ "findExampleById", "findExampleByName" ]
 
-=== Checking for HTTP and SOAP faults
+=== Handle HTTP and SOAP errors
+
+Check if the SOAP request was successful.
 
   response.success?
   response.fault?
 
-=== Access the fault message and code
+Access the fault message and code.
 
   response.fault
   response.fault_code
 
-=== Working with different response formats
+=== Different response formats
 
-  # raw XML response:
+To work with the response of the service you need to convert the response
+object using one of the following methods.
+
+  # SOAP response XML:
   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")
+The to_hash and to_mash methods accept an XPath expression (Hpricot search)
+as second parameter to define a custom root node to start translating the
+response XML at.
+
+  # response as a Hash starting at a custom root node
+  response.to_hash("//item")
+
+  # response as a Mash starting at a custom root node
+  response.to_mash("//user/email")
+
+=== Logging request and response
+
+You should specify the logger to use before working with any services.
+
+  # example for Ruby on Rails
+  Savon::Service.logger = RAILS_DEFAULT_LOGGER

data/lib/savon/mash.rb

@@ -3,8 +3,8 @@ module Savon
   # Savon::Mash converts a given Hash into an Object.
   class Mash
 
-    # Loops through a given +hash+, stores each value in an instance variable
-    # and creates getter and setter methods.
+    # Iterates through a given +hash+, stores each value in an instance
+    # variable and creates getter and setter methods.
     #
     # === Parameters
     #
@@ -19,9 +19,9 @@ module Savon
           end
         end
 
-        set_instance_variable key, value
-        define_reader key
-        define_writer key
+        set_instance_variable(key, value)
+        define_reader(key)
+        define_writer(key)
       end
     end
 

data/lib/savon/response.rb

@@ -5,42 +5,15 @@ require "apricoteatsgorilla"
 module Savon
 
   # 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
 
-    # The HTTP/SOAP fault.
+    # The HTTP or SOAP fault message.
     attr_reader :fault
 
-    # The HTTP/SOAP fault code.
+    # The HTTP or SOAP fault code.
     attr_reader :fault_code
 
-    # Initializer to set the SOAP response.
+    # Initializer expects the HTTP response and checks for HTTP or SOAP faults.
     #
     # === Parameters
     #
@@ -55,18 +28,18 @@ module Savon
       @fault_code.nil?
     end
 
-    # Returns true if the request was not successful, false otherwise.
+    # Returns true if there was a HTTP or SOAP fault, false otherwise.
     def fault?
       !@fault_code.nil?
     end
 
     # Returns the SOAP response message as a Hash. Call with XPath expession
-    # to define a custom +root_node+ to start parsing at. Defaults to "//return".
-    # The root node itself will not be included in the Hash.
+    # (Hpricot search) to define a custom +root_node+ to start parsing at.
+    # Defaults to "//return". The root node will not be included in the Hash.
     #
     # === Parameters
     #
-    # * +root_node+ - Optional. Custom root node to start parsing at. Defaults to "//return".
+    # * +root_node+ - Optional. Custom root node to start parsing at.
     def to_hash(root_node = "//return")
       return nil if fault?
       ApricotEatsGorilla[@response.body, root_node]
@@ -74,25 +47,25 @@ module Savon
 
     # Returns the SOAP response message as a Savon::Mash object. Call with
     # XPath expession to define a custom +root_node+. Defaults to "//return".
-    # The root node itself will not be included in the Mash object.
+    # The root node will not be included in the Mash object.
     #
     # === Parameters
     #
-    # * +root_node+ - Optional. Custom root node to start parsing at. Defaults to "//return".
+    # * +root_node+ - Optional. Custom root node to start parsing at.
     def to_mash(root_node = "//return")
       return nil if fault?
       hash = to_hash(root_node)
       Savon::Mash.new(hash)
     end
 
-    # Returns the raw XML response.
+    # Returns the SOAP response XML.
     def to_s
       @response.body
     end
 
   private
 
-    # Checks for and stores HTTP and SOAP fault errors.
+    # Checks for HTTP and SOAP faults.
     def validate
       if @response.code.to_i >= 300
         @fault, @fault_code = @response.message, @response.code

data/lib/savon/service.rb

@@ -5,54 +5,28 @@ require "apricoteatsgorilla"
 
 module Savon
 
-  # Savon is a lightweight SOAP client.
+  # Ruby SOAP client library to enjoy.
   #
-  # 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.
-  #
-  # === 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" ]
-  #
-  # === 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")
+  # Communicating with a SOAP webservice can be done in two lines of code.
+  # Instantiate a new Savon::Service passing in the URI to the WSDL of the
+  # service you would like to use. Then 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.
   class Service
 
     # The logger to use.
     @@logger = nil
 
-    # The Net::HTTP connection instance to use.
-    attr_writer :http
-
-    # Initializer sets the WSDL +endpoint+ URI.
+    # Initializer expects the WSDL +endpoint+ URI to use and sets up
+    # Apricot eats Gorilla.
     #
     # ==== Parameters
     #
-    # * +endpoint+ - The WSDL endpoint URI.
+    # * +endpoint+ - WSDL endpoint URI to use.
     def initialize(endpoint)
       @uri = URI(endpoint)
+      ApricotEatsGorilla.nodes_to_namespace = wsdl.choice_elements
+      ApricotEatsGorilla.node_namespace = "wsdl"
     end
 
     # Returns an instance of the WSDL.
@@ -61,6 +35,11 @@ module Savon
       @wsdl
     end
 
+    # Sets the Net::HTTP instance to use.
+    def http=(http)
+      @http = http
+    end
+
     # Sets the logger to use.
     def self.logger=(logger)
       @@logger = logger
@@ -68,20 +47,16 @@ module Savon
 
   private
 
-    # Prepares and processes the SOAP request. Returns a Savon::Response object.
+    # Sets up and dispatches the SOAP request. Returns a Savon::Response object.
     def call_service
       headers = { "Content-Type" => "text/xml; charset=utf-8", "SOAPAction" => @action }
 
-      ApricotEatsGorilla.setup do |s|
-        s.nodes_to_namespace = wsdl.choice_elements
-        s.node_namespace = "wsdl"
-      end
       body = ApricotEatsGorilla.soap_envelope("wsdl" => wsdl.namespace_uri) do
         ApricotEatsGorilla["wsdl:#{@action}" => @options]
       end
 
       debug do |logger|
-        logger.info "Request; #{@uri}"
+        logger.info "Requesting #{@uri}"
         logger.info headers.map { |key, value| "#{key}: #{value}" }.join("\n")
         logger.info body
       end
@@ -110,20 +85,19 @@ module Savon
       end
     end
 
-    # Debug method. Outputs a given +message+ to the defined @@logger or
-    # yields the @@logger to a +block+ in case one was given.
+    # Logs a given +message+ using the @@logger instance or yields the logger
+    # to a given +block+ for logging multiple things at once.
     def debug(message = nil)
       if @@logger
-        if message
-          @@logger.info(message)
-        end
-        if block_given?
-          yield @@logger
-        end
+        @@logger.info(message) if message
+        yield @@logger if block_given?
       end
     end
 
-    # Intercepts calls to SOAP service methods.
+    # Method missing catches SOAP service methods called on this object. This
+    # is the default way of calling a SOAP service. The given +method+ will be
+    # validated against the WSDL and dispatched if available. Values supplied
+    # through the optional Hash of +options+ will be send to the service method.
     #
     # === Parameters
     #

data/lib/savon/wsdl.rb

@@ -4,7 +4,7 @@ require "hpricot"
 
 module Savon
 
-  # Savon::Wsdl gets, parses and represents the SOAP-WSDL.
+  # Savon::Wsdl gets, parses and represents the WSDL.
   class Wsdl
 
     # The namespace URI.
@@ -21,7 +21,7 @@ module Savon
     #
     # === Parameters
     #
-    # * +uri+ - The URI to access.
+    # * +uri+ - The URI of the WSDL.
     # * +http+ - The Net::HTTP connection instance to use.
     def initialize(uri, http)
       @uri, @http = uri, http
@@ -49,15 +49,13 @@ module Savon
       end
     end
 
-    # Parses the WSDL to find and store the namespace URI.
+    # Parses the WSDL for the namespace URI.
     def parse_namespace_uri
       node = @doc.at("//wsdl:definitions")
-      if node
-        @namespace_uri = node.get_attribute("targetNamespace")
-      end
+      @namespace_uri = node.get_attribute("targetNamespace") if node
     end
 
-    # Parses the WSDL to find and store the available SOAP service methods.
+    # Parses the WSDL for available SOAP service methods.
     def parse_service_methods
       @service_methods, node = [], @doc.search("//soap:operation")
       if node
@@ -67,7 +65,7 @@ module Savon
       end
     end
 
-    # Parses the WSDL to find and store any choice elements.
+    # Parses the WSDL for choice elements.
     def parse_choice_elements
       @choice_elements, node = [], @doc.search("//xs:choice//xs:element")
       if node

data/test/fixtures/soap_response.rb

@@ -1,26 +1,26 @@
 module SoapResponseFixture
 
   def some_soap_response
-    '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
-      <soap:Body>
-        <ns2:result xmlns:ns2="http://example.com/">
-          <return>
-            <token>secret</token>
-          </return>
-        </ns2:result>
-      </soap:Body>
-    </soap:Envelope>'
+    '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' <<
+      '<soap:Body>' <<
+        '<ns2:result xmlns:ns2="http://example.com/">' <<
+          '<return>' <<
+            '<token>secret</token>' <<
+          '</return>' <<
+        '</ns2:result>' <<
+      '</soap:Body>' <<
+    '</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>'
+    '<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

data/test/helper.rb

@@ -19,15 +19,15 @@ module TestHelper
   end
 
   def service_http_mock(response_body)
-    http_mock = mock()
-    http_mock.expects(:get).returns(response_mock(WsdlFactory.new.build))
-    http_mock.expects(:request_post).returns(response_mock(response_body))
+    http_mock = mock("Net::HTTP")
+    http_mock.stubs(:get).returns(response_mock(WsdlFactory.new.build))
+    http_mock.stubs(:request_post).returns(response_mock(response_body))
     http_mock
   end
 
   def http_mock(response_body)
-    http_mock = mock()
-    http_mock.expects(:get).returns(response_mock(response_body))
+    http_mock = mock("Net::HTTP")
+    http_mock.stubs(:get).returns(response_mock(response_body))
     http_mock
   end
 
@@ -41,10 +41,7 @@ module TestHelper
 
   def build_response_mock(code, message, body = nil)
     response_mock = mock("Net::HTTPResponse")
-    response_mock.stubs(
-      :code => code, :message => message, :content_type => "text/html",
-      :body => body
-    )
+    response_mock.stubs(:code => code, :message => message, :body => body)
     response_mock
   end
 

data/test/savon/mash_test.rb

@@ -2,8 +2,17 @@ require File.join(File.dirname(__FILE__), "..", "helper")
 
 class SavonMashTest < Test::Unit::TestCase
 
-  def test_nupsi
-    assert true
+  context "Creating a new Savon::Mash" do
+    context "with a simple Hash" do
+      should "return a Mash object matching the given Hash" do
+        hash = { :some => { :simple => "test" } }
+        mash = Savon::Mash.new(hash)
+
+        assert_respond_to(mash, :some)
+        assert_respond_to(mash, :simple)
+        assert_equal "test", mash.some.simple
+      end
+    end
   end
 
 end

data/test/savon/service_test.rb

@@ -7,6 +7,10 @@ class SavonServiceTest < Test::Unit::TestCase
 
   context "Savon::Service" do
     setup do
+      @some_factory = WsdlFactory.new
+      @some_wsdl = Savon::Wsdl.new(some_uri, http_mock(@some_factory.build))
+      Savon::Wsdl.stubs(:new).returns(@some_wsdl)
+
       @service = Savon::Service.new(some_url)
       @service.http = service_http_mock(some_soap_response)
       @result = @service.findById

data/test/savon_test.rb

@@ -1,5 +1,5 @@
-$:.unshift(File.join(File.dirname(__FILE__), 'savon'))
+$:.unshift(File.join(File.dirname(__FILE__), "savon"))
+require "service_test"
+require "response_test"
 require "mash_test"
 require "wsdl_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.91
+  version: 0.1.0
 platform: ruby
 authors: 
 - Daniel Harrington
@@ -30,9 +30,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.3.8
+        version: 0.4.1
     version: 
-description: Savon is a lightweight SOAP client.
+description: Ruby SOAP client library to enjoy.
 email: 
 executables: []
 
@@ -73,7 +73,7 @@ rubyforge_project:
 rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
-summary: Savon is a lightweight SOAP client.
+summary: Ruby SOAP client library to enjoy.
 test_files: 
 - test/savon_test.rb
 - test/helper.rb