smacks-savon 0.1.61 → 0.2.0

data/README.rdoc

@@ -1,12 +1,8 @@
 = Savon
 
-Ruby SOAP client library to enjoy.
-
-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.
+Savon::Service is a SOAP client library to enjoy. The goal is to minimize
+the overhead of working with SOAP services and provide a lightweight
+alternative to other libraries.
 
 == Install
 
@@ -14,67 +10,48 @@ of options for the service method to receive.
 
 == Dependencies
 
-  hpricot 0.6.164 (also available for JRuby)
-  smacks-apricoteatsgorilla >= 0.4.1
+  smacks-apricoteatsgorilla >= 0.5.2
+  hpricot 0.8.241 (the latest JRuby-compatible version)
+
+Hpricot 0.8.241 is also available at: {Apricot eats Gorilla Downloads}[http://github.com/smacks/apricoteatsgorilla/downloads]
 
 == How to use
 
 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 of your choice 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 = Savon::Service.new("http://example.com/ExampleService?wsdl")
 
-  proxy.wsdl.service_methods
-  # => [ "findExampleById", "findExampleByName" ]
+Call the SOAP service method of your choice on your Savon::Service instance.
 
-=== Handle HTTP and SOAP errors
+  response = proxy.get_all_users
 
-Check if the SOAP request was successful.
+Or pass in a Hash of options for the SOAP service to receive.
 
-  response.success?
-  response.error?
+  response = proxy.find_user_by_id(:id => 123)
 
-Access error message and code in case a request was not successful.
+Or specify a custom XPath-Expression to start translating the SOAP response at.
 
-  response.error_message
-  response.error_code
+  response = proxy.find_user_by_id(nil, "//user/email")
 
-=== Different response formats
+=== Check for available SOAP actions
 
-To work with the response of the service you need to convert the response
-object using one of the following methods.
+Access the WSDL to get an Array of SOAP actions found in the WSDL document.
 
-  # SOAP response XML:
-  response.to_s
+  proxy.wsdl.soap_actions
+  # => [ "getAllUsers", "findUserById" ]
 
-  # response as a Hash
-  response.to_hash
+=== Handle HTTP error and SOAP faults
 
-  # response as a Mash
-  response.to_mash
-
-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")
+Savon::Service raises a Savon::SOAPFault in case of a SOAP fault and a
+Savon::HTTPError in case of an HTTP error.
 
 === Logging request and response
 
-You should specify the logger to use before working with any services.
+You should specify the logger to use before working with any service.
 
   # example for Ruby on Rails
-  Savon::Service.logger = RAILS_DEFAULT_LOGGER
+  Savon.logger = RAILS_DEFAULT_LOGGER
+
+Of course you can also specify the log level if needed. By default it's set to :debug.
+
+  Savon.log_level = :info

data/Rakefile

@@ -0,0 +1,48 @@
+require "rubygems"
+require "rake"
+require "spec/rake/spectask"
+require "rake/rdoctask"
+
+task :default => :spec
+
+Spec::Rake::SpecTask.new do |spec|
+  spec.spec_files = FileList["spec/**/*_spec.rb"]
+  spec.spec_opts << "--color"
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.title = "Savon"
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.main = "README.rdoc"
+  rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rdoc.options = ["--line-numbers", "--inline-source"]
+end
+
+begin
+  require "jeweler"
+  Jeweler::Tasks.new do |spec|
+    spec.name = "savon"
+    spec.author = "Daniel Harrington"
+    spec.email = "me@d-harrington.com"
+    spec.homepage = "http://github.com/smacks/savon"
+    spec.summary = "SOAP client library to enjoy."
+    spec.description = spec.summary
+
+    spec.files = FileList["[A-Z]*", "{lib,spec}/**/*.{rb,xml}"]
+
+    spec.rdoc_options += [
+      "--title", "Savon",
+      "--main", "README.rdoc",
+      "--line-numbers",
+      "--inline-source"
+    ]
+
+    spec.add_runtime_dependency("hpricot", "0.8.241")
+    spec.add_runtime_dependency("smacks-apricoteatsgorilla", "0.5.2")
+
+    spec.add_development_dependency("rspec", ">= 1.2.8")
+    spec.add_development_dependency("rr", ">= 0.10.0")
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/savon.rb

@@ -1,4 +1,47 @@
-$:.unshift(File.join(File.dirname(__FILE__), "savon"))
-require "service"
-require "wsdl"
-require "response"
+module Savon
+
+  # Raised by the <tt>on_http_error</tt> method in case of an HTTP error.
+  # <tt>on_http_error</tt> may be overwritten to customize error handling.
+  class HTTPError < StandardError; end
+
+  # Raised by the <tt>on_soap_fault</tt> method in case of a SOAP fault.
+  # <tt>on_soap_fault</tt> may be overwritten to customize error handling.
+  class SOAPFault < StandardError; end
+
+  # The logger to use.
+  @@logger = nil
+
+  # The log level to use.
+  @@log_level = :debug
+
+  # Sets the logger to use.
+  def self.logger=(logger)
+    @@logger = logger
+  end
+
+  # Sets the log level to use.
+  def self.log_level=(log_level)
+    @@log_level = log_level
+  end
+
+  # Logs a given +message+ using the +@@logger+ instance or yields the logger
+  # to a given +block+ for logging multiple messages at once.
+  def self.log(message = nil)
+    if @@logger
+      @@logger.send(@@log_level, message) if message
+      yield @@logger if block_given?
+    end
+  end
+
+end
+
+%w(net/http uri rubygems hpricot).each do |gem|
+  require gem
+end
+
+#require "apricoteatsgorilla"
+require File.join(File.dirname(__FILE__), "..", "..", "apricoteatsgorilla", "lib", "apricoteatsgorilla")
+
+%w(service wsdl).each do |file|
+  require File.join(File.dirname(__FILE__), "savon", file)
+end

data/lib/savon/service.rb

@@ -1,121 +1,95 @@
-require "rubygems"
-require "net/http"
-require "uri"
-require "apricoteatsgorilla"
-
 module Savon
 
-  # Savon - Ruby SOAP client library to enjoy.
+  # == Savon::Service
+  #
+  # Savon::Service is a SOAP client library to enjoy. The goal is to minimize
+  # the overhead of working with SOAP services and provide a lightweight
+  # alternative to other libraries.
+  #
+  # ==== Example
   #
-  # 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.
+  #   proxy = Savon::Service.new("http://example.com/ExampleService?wsdl")
+  #   response = proxy.find_user_by_id(:id => 123)
   class Service
 
-    # The logger instance to use.
-    @@logger = nil
-
-    # The log level to use.
-    @@log_level = :debug
-
-    # Initializer expects the WSDL +endpoint+ URI and defines nodes to
-    # namespace for Apricot eats Gorilla.
+    # Initializer expects an +endpoint+ URI.
     def initialize(endpoint)
-      @uri = URI(endpoint)
+      raise ArgumentError, "Invalid endpoint: #{endpoint}" unless /^http.+/ === endpoint
+      @endpoint = URI(endpoint)
     end
 
-    # Returns an instance of the Savon::Wsdl.
+    # Returns an instance of Savon::WSDL.
     def wsdl
-      @wsdl = Savon::Wsdl.new(@uri, http) unless @wsdl
-      @wsdl
+      @wsdl ||= WSDL.new(@endpoint, http)
     end
 
-    # Sets the Net::HTTP instance to use.
-    def http=(http)
-      @http = http
-    end
+  private
 
-    # Sets the logger instance to use.
-    def self.logger=(logger)
-      @@logger = logger
-    end
+    # Dispatches a SOAP request, handles any HTTP errors and SOAP faults
+    # and returns the SOAP response.
+    def dispatch(soap_action, soap_body, response_xpath)
+      ApricotEatsGorilla.nodes_to_namespace = { :wsdl => wsdl.choice_elements }
+      headers, body = build_request_parameters(soap_action, soap_body)
 
-    # Sets the log level to use.
-    def self.log_level=(log_level)
-      @@log_level = log_level
-    end
+      Savon.log("SOAP request: #{@endpoint}")
+      Savon.log(headers.map { |k, v| "#{k}: #{v}" }.join(", "))
+      Savon.log(body)
 
-  private
+      response = http.request_post(@endpoint.path, body, headers)
 
-    # Constructs and dispatches the SOAP request. Returns a Savon::Response.
-    def dispatch(root_node = nil)
-      headers = { "Content-Type" => "text/xml; charset=utf-8", "SOAPAction" => @soap_action }
+      Savon.log("SOAP response (status #{response.code})")
+      Savon.log(response.body)
 
-      body = ApricotEatsGorilla.soap_envelope("wsdl" => wsdl.namespace_uri) do
-        ApricotEatsGorilla["wsdl:#{@soap_action}" => @options]
-      end
+      soap_fault = ApricotEatsGorilla[response.body, "//soap:Fault"]
+      raise_soap_fault(soap_fault) if soap_fault && !soap_fault.empty?
+      raise_http_error(response) if response.code.to_i >= 300
 
-      debug do |logger|
-        logger.send @@log_level, "Requesting #{@uri}"
-        logger.send @@log_level, headers.map { |key, value| "#{key}: #{value}" }.join("\n")
-        logger.send @@log_level, body
-      end
-      response = http.request_post(@uri.path, body, headers)
-      debug do |logger|
-        logger.send @@log_level, "Response (Status #{response.code}):"
-        logger.send @@log_level, response.body
-      end
-      Savon::Response.new response, root_node
+      ApricotEatsGorilla[response.body, response_xpath]
     end
 
-    # Returns the Net::HTTP instance to use.
-    def http
-      if @http.nil?
-        raise ArgumentError, "Invalid endpoint URI: #{@uri}" unless @uri.scheme
-        @http = Net::HTTP.new(@uri.host, @uri.port)
+    # Expects the requested +soap_action+ and +soap_body+ and builds and
+    # returns the request header and body to dispatch a SOAP request.
+    def build_request_parameters(soap_action, soap_body)
+      headers = { "Content-Type" => "text/xml; charset=utf-8", "SOAPAction" => soap_action }
+      body = ApricotEatsGorilla.soap_envelope(:wsdl => wsdl.namespace_uri) do
+        ApricotEatsGorilla["wsdl:#{soap_action}" => soap_body]
       end
-      @http
+      [headers, body]
     end
 
-    # Checks if the requested SOAP action was found on the WSDL.
-    # Raises an ArgumentError in case it was not found.
-    def validate_soap_action
-      unless wsdl.service_methods.include? @soap_action
-        raise ArgumentError, "Invalid service method: #{@soap_action}"
-      end
+    # Expects a Hash containing information about a SOAP fault and raises
+    # a Savon::SOAPFault.
+    def raise_soap_fault(soap_fault)
+      raise SOAPFault, "#{soap_fault[:faultcode]}: #{soap_fault[:faultstring]}"
     end
 
-    # Sets options for the XML parser.
-    def setup_parser
-      ApricotEatsGorilla.nodes_to_namespace = wsdl.choice_elements
-      ApricotEatsGorilla.node_namespace = "wsdl"
+    # Expects a Net::HTTPResponse and raises a Savon::HTTPError.
+    def raise_http_error(response)
+      raise HTTPError, "#{response.message} (#{response.code}): #{response.body}"
     end
 
-    # Logs a given +message+ using the +@@logger+ instance or yields the logger
-    # to a given +block+ for logging multiple messages at once.
-    def debug(message = nil)
-      if @@logger
-        @@logger.send(@@log_level, message) if message
-        yield @@logger if block_given?
-      end
+    # Returns a Net::HTTP instance.
+    def http
+      @http ||= Net::HTTP.new(@endpoint.host, @endpoint.port)
+    end
+
+    # Catches calls to SOAP actions, checks if the method called was found in
+    # the WSDL and dispatches the SOAP action if it's valid. Takes an optional
+    # Hash of options to be passed to the SOAP action and an optional XPath-
+    # Expression to define a custom XML root node to start parsing the SOAP
+    # response at.
+    def method_missing(method, *args)
+      soap_action = camelize(method)
+      super unless wsdl.soap_actions.include? soap_action
+      soap_body = args[0] || {}
+      response_xpath = args[1] || "//return"
+      dispatch(soap_action, soap_body, response_xpath)
     end
 
-    # Catches SOAP actions called on the Savon::Service instance.
-    # This is the default way of calling a SOAP action.
-    # 
-    # The given +method+ will be validated against available SOAP actions found
-    # on the WSDL and dispatched if available. Options for the SOAP action to
-    # receive can be given through the optional Hash of +options+. A custom
-    # +root_node+ to start parsing the SOAP response at might be supplied as well.
-    def method_missing(method, options = {}, root_node = nil)
-      @soap_action = ApricotEatsGorilla.to_lower_camel_case(method)
-      @options = options
-      validate_soap_action
-      setup_parser
-      dispatch(root_node)
+    # Converts a given +string+ from snake_case to lowerCamelCase.
+    def camelize(string)
+      string.to_s.gsub(/_(.)/) { $1.upcase } if string
     end
 
   end
-end
+end

data/lib/savon/wsdl.rb

@@ -1,75 +1,70 @@
-require "rubygems"
-require "net/http"
-require "hpricot"
-
 module Savon
 
-  # Savon::Wsdl represents the WSDL.
-  class Wsdl
+  # Savon::WSDL represents the WSDL document.
+  class WSDL
 
-    # The namespace URI.
-    attr_reader :namespace_uri
+    # Returns the namespace URI.
+    def namespace_uri
+      @namespace ||= parse_namespace_uri
+    end
 
-    # SOAP service methods.
-    attr_reader :service_methods
+    # Returns an Array of available SOAP actions.
+    def soap_actions
+      @soap_actions ||= parse_soap_actions
+    end
 
-    # Choice elements.
-    attr_reader :choice_elements
+    # Returns an Array of choice elements.
+    def choice_elements
+      @choice_elements ||= parse_choice_elements
+    end
 
-    # Initializer expects an endpoint +uri+ and an +http+ connection instance,
-    # then gets and parses the WSDL at the given URI.
+    # Initializer expects the endpoint +uri+ and a Net::HTTP instance (+http+).
     def initialize(uri, http)
       @uri, @http = uri, http
-      get_wsdl
-
-      parse_namespace_uri
-      parse_service_methods
-      parse_choice_elements
     end
 
-    # Returns the response body from the WSDL request.
+    # Returns the body of the Net::HTTPResponse from the WSDL request.
     def to_s
-      @response.body
+      @response ? @response.body : nil
     end
 
   private
 
-    # Gets the WSDL at the given URI.
-    def get_wsdl
-      @response = @http.get("#{@uri.path}?#{@uri.query}")
-      @doc = Hpricot.XML(@response.body)
-
-      if !@doc.at("//wsdl:definitions")
-        raise ArgumentError, "Unable to find WSDL at given endpoint URI."
+    # Returns an Hpricot::Document of the WSDL. Retrieves the WSDL from the
+    # endpoint URI in case it wasn't retrieved already.
+    def document
+      unless @document
+        @response = @http.get("#{@uri.path}?#{@uri.query}")
+        @document = Hpricot.XML(@response.body)
+        raise ArgumentError, "Unable to find WSDL at: #{@uri}" if
+          !soap_actions || soap_actions.empty?
       end
+      @document
     end
 
     # Parses the WSDL for the namespace URI.
     def parse_namespace_uri
-      node = @doc.at("//wsdl:definitions")
-      @namespace_uri = node.get_attribute("targetNamespace") if node
+      definitions = document.at("//wsdl:definitions")
+      definitions.get_attribute("targetNamespace") if definitions
     end
 
-    # Parses the WSDL for available SOAP service methods.
-    def parse_service_methods
-      @service_methods, node = [], @doc.search("//soap:operation")
-      if node
-        node.each do |operation|
-          service_methods << operation.parent.get_attribute("name")
-        end
-      end
+    # Parses the WSDL for available SOAP actions.
+    def parse_soap_actions
+      soap_actions = document.search("//soap:operation")
+
+      soap_actions.collect do |soap_action|
+        soap_action.parent.get_attribute("name")
+      end if soap_actions
     end
 
     # Parses the WSDL for choice elements.
     def parse_choice_elements
-      @choice_elements, node = [], @doc.search("//xs:choice//xs:element")
-      if node
-        node.each do |choice|
-          name = choice.get_attribute("ref").sub(/(.+):/, "")
-          choice_elements << name unless @choice_elements.include? name
-        end
-      end
+      choice_elements = document.search("//xs:choice//xs:element")
+
+      choice_elements.collect do |choice_element|
+        choice_element.get_attribute("ref").sub(/(.+):/, "")
+      end if choice_elements
     end
 
   end
-end
+end