troelskn-handsoap 0.3.8 → 0.4.0

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:minor: 3
-:patch: 8
+:minor: 4
+:patch: 0
 :major: 0

data/lib/handsoap/service.rb

@@ -24,40 +24,6 @@ module Handsoap
     @xml_query_driver = Handsoap::XmlQueryFront.load_driver!(driver)
   end
 
-  SOAP_NAMESPACE = { 1 => 'http://schemas.xmlsoap.org/soap/envelope/', 2 => 'http://www.w3.org/2003/05/soap-envelope' }
-
-  class Response
-    def initialize(http_body, soap_namespace)
-      @http_body = http_body
-      @soap_namespace = soap_namespace
-      @document = :lazy
-      @fault = :lazy
-    end
-    def document?
-      !! document
-    end
-    def document
-      if @document == :lazy
-        begin
-          @document = Handsoap::XmlQueryFront.parse_string(@http_body, Handsoap.xml_query_driver)
-        rescue Handsoap::XmlQueryFront::ParseError => ex
-          @document = nil
-        end
-      end
-      return @document
-    end
-    def fault?
-      !! fault
-    end
-    def fault
-      if @fault == :lazy
-        nodes = document? ? document.xpath('/env:Envelope/env:Body/descendant-or-self::env:Fault', { 'env' => @soap_namespace }) : []
-        @fault = nodes.any? ? Fault.from_xml(nodes.first, :namespace => @soap_namespace) : nil
-      end
-      return @fault
-    end
-  end
-
   class Fault < Exception
     attr_reader :code, :reason, :details
     def initialize(code, reason, details)
@@ -91,18 +57,33 @@ module Handsoap
     def self.logger=(io)
       @@logger = io
     end
+		# Sets the endpoint for the service.
+		# Arguments:
+		#   :uri                  => endpoint uri of the service. Required.
+		#   :version              => 1 | 2
+		#   :envelope_namespace   => Namespace of SOAP-envelope
+		#   :request_content_type => Content-Type of HTTP request.
+		# You must supply either :version or both :envelope_namspace and :request_content_type.
+		# :version is simply a shortcut for default values.
     def self.endpoint(args = {})
-      @protocol_version = args[:version] || raise("Missing option :version")
       @uri = args[:uri] || raise("Missing option :uri")
+			if args[:version]
+        soap_namespace = { 1 => 'http://schemas.xmlsoap.org/soap/envelope/', 2 => 'http://www.w3.org/2003/05/soap-envelope' }
+				raise("Unknown protocol version '#{@protocol_version.inspect}'") if soap_namespace[args[:version]].nil?
+				@envelope_namespace = soap_namespace[args[:version]]
+				@request_content_type = args[:version] == 1 ? "text/xml" : "application/soap+xml"
+			end
+			@envelope_namespace = args[:envelope_namespace] unless args[:envelope_namespace].nil?
+			@request_content_type = args[:request_content_type] unless args[:request_content_type].nil?
+			if @envelope_namespace.nil? || @request_content_type.nil?
+				raise("Missing option :envelope_namespace, :request_content_type or :version")
+			end
     end
     def self.envelope_namespace
-      if SOAP_NAMESPACE[@protocol_version].nil?
-        raise "Unknown protocol version '#{@protocol_version.inspect}'"
-      end
-      SOAP_NAMESPACE[@protocol_version]
+			@envelope_namespace
     end
     def self.request_content_type
-      @protocol_version == 1 ? "text/xml" : "application/soap+xml"
+      @request_content_type
     end
     def self.uri
       @uri
@@ -158,6 +139,11 @@ module Handsoap
     # You can override this to provide filtering and logging.
     def on_before_dispatch
     end
+    # Hook that is called after the http_client is created.
+    #
+    # You can override this to customize the http_client
+    def on_after_create_http_client(http_client)
+    end
     # Hook that is called when there is a response.
     #
     # You can override this to register common namespaces, useful for parsing the document.
@@ -172,13 +158,18 @@ module Handsoap
     # Hook that is called if the dispatch returns a +Fault+.
     #
     # Default behaviour is to raise the Fault, but you can override this to provide logging and more fine-grained handling faults.
+    #
+    # See also: parse_soap_fault
     def on_fault(fault)
       raise fault
     end
     # Hook that is called if the response does not contain a valid SOAP enevlope.
     #
     # Default behaviour is to raise an error
-    def on_missing_document(soap_response)
+    #
+    # Note that if your service has operations that are one-way, you shouldn't raise an error here.
+    # This is however a fairly exotic case, so that is why the default behaviour is to raise an error.
+    def on_missing_document(http_response_body)
       raise "The response is not a valid SOAP envelope"
     end
     def debug(message = nil) #:nodoc:
@@ -195,17 +186,20 @@ module Handsoap
     def send_http_request(uri, post_body, headers)
       if Handsoap.http_driver == :curb
         http_client = Curl::Easy.new(uri)
+        on_after_create_http_client(http_client)
         http_client.headers = headers
         http_client.http_post post_body
         return { :status => http_client.response_code, :body => http_client.body_str, :content_type => http_client.content_type }
       elsif Handsoap.http_driver == :httpclient
-        response = HTTPClient.new.post(uri, post_body, headers)
+        http_client = HTTPClient.new
+        on_after_create_http_client(http_client)
+        response = http_client.post(uri, post_body, headers)
         return { :status => response.status, :body => response.content, :content_type => response.contenttype }
       else
         raise "Unknown http driver #{Handsoap.http_driver}"
       end
     end
-    # Send document and parses the response into a +Response+
+    # Send document and parses the response into a +XmlQueryFront::XmlElement+ (XmlDocument)
     def dispatch(doc, action)
       on_before_dispatch
       headers = {
@@ -229,18 +223,29 @@ module Handsoap
         logger.puts "---"
         logger.puts Handsoap.pretty_format_envelope(response[:body])
       end
-      soap_response = Response.new(response[:body], self.class.envelope_namespace)
-      if soap_response.fault?
-        return on_fault(soap_response.fault)
+      # Start the parsing pipe-line.
+      # There are various stages and hooks for each, so that you can override those in your service classes.
+      xml_document = parse_soap_response_document(response[:body])
+      soap_fault = parse_soap_fault(xml_document)
+      # Is the response a soap-fault?
+      unless soap_fault.nil?
+        return on_fault(soap_fault)
       end
-      if response[:status] >= 300
+      # Does the http-status indicate an error?
+      if response[:status] >= 400
         return on_http_error(response[:status], response[:body])
       end
-      unless soap_response.document?
-        return on_missing_document(soap_response)
+      # Does the response contain a valid xml-document?
+      if xml_document.nil?
+        return on_missing_document(response[:body])
+      end
+      # Everything seems in order.
+      on_response_document(xml_document)
+      # BC hack
+      def xml_document.document
+        self
       end
-      on_response_document(soap_response.document)
-      return soap_response
+      return xml_document
     end
     # Creates a standard SOAP envelope and yields the +Body+ element.
     def make_envelope # :yields: Handsoap::XmlMason::Element
@@ -258,6 +263,21 @@ module Handsoap
       end
       return doc
     end
+    # String -> [XmlDocument | nil]
+    def parse_soap_response_document(http_body)
+      begin
+        Handsoap::XmlQueryFront.parse_string(http_body, Handsoap.xml_query_driver)
+      rescue Handsoap::XmlQueryFront::ParseError => ex
+        nil
+      end
+    end
+    # XmlDocument -> [Fault | nil]
+    def parse_soap_fault(document)
+      unless document.nil?
+        node = document.xpath('/env:Envelope/env:Body/descendant-or-self::env:Fault', { 'env' => self.class.envelope_namespace }).first
+        Fault.from_xml(node, :namespace => self.class.envelope_namespace) unless node.nil?
+      end
+    end
   end
 
   def self.pretty_format_envelope(xml_string)
@@ -312,7 +332,7 @@ module Handsoap
     private
     # Helper to serialize a node into a ruby string
     #
-    # *deprecated*. Use Handsoap::XmlQueryFront::BaseDriver#to_s
+    # *deprecated*. Use Handsoap::XmlQueryFront::XmlElement#to_s
     def xml_to_str(node, xquery = nil)
       n = xquery ? node.xpath(xquery, ns).first : node
       return if n.nil?
@@ -321,7 +341,7 @@ module Handsoap
     alias_method :xml_to_s, :xml_to_str
     # Helper to serialize a node into a ruby integer
     #
-    # *deprecated*. Use Handsoap::XmlQueryFront::BaseDriver#to_i
+    # *deprecated*. Use Handsoap::XmlQueryFront::XmlElement#to_i
     def xml_to_int(node, xquery = nil)
       n = xquery ? node.xpath(xquery, ns).first : node
       return if n.nil?
@@ -330,7 +350,7 @@ module Handsoap
     alias_method :xml_to_i, :xml_to_int
     # Helper to serialize a node into a ruby float
     #
-    # *deprecated*. Use Handsoap::XmlQueryFront::BaseDriver#to_f
+    # *deprecated*. Use Handsoap::XmlQueryFront::XmlElement#to_f
     def xml_to_float(node, xquery = nil)
       n = xquery ? node.xpath(xquery, ns).first : node
       return if n.nil?
@@ -339,7 +359,7 @@ module Handsoap
     alias_method :xml_to_f, :xml_to_float
     # Helper to serialize a node into a ruby boolean
     #
-    # *deprecated*. Use Handsoap::XmlQueryFront::BaseDriver#to_boolean
+    # *deprecated*. Use Handsoap::XmlQueryFront::XmlElement#to_boolean
     def xml_to_bool(node, xquery = nil)
       n = xquery ? node.xpath(xquery, ns).first : node
       return if n.nil?
@@ -347,7 +367,7 @@ module Handsoap
     end
     # Helper to serialize a node into a ruby Time object
     #
-    # *deprecated*. Use Handsoap::XmlQueryFront::BaseDriver#to_date
+    # *deprecated*. Use Handsoap::XmlQueryFront::XmlElement#to_date
     def xml_to_date(node, xquery = nil)
       n = xquery ? node.xpath(xquery, ns).first : node
       return if n.nil?

data/lib/handsoap/xml_query_front.rb

@@ -13,7 +13,7 @@ module Handsoap
   #   :nokogiri
   #   :libxml
   #
-  # The resulting object is a wrapper, of the type Handsoap::XmlQueryFront::BaseDriver.
+  # The resulting object is a wrapper, of the type Handsoap::XmlQueryFront::XmlElement.
   #
   module XmlQueryFront
 
@@ -65,7 +65,7 @@ module Handsoap
       end
     end
 
-    # NodeSelection is a wrapper around Array, that implicitly delegates BaseDriver methods to the first element.
+    # NodeSelection is a wrapper around Array, that implicitly delegates XmlElement methods to the first element.
     #
     # It makes mapping code prettier, since you often need to access the first element of a selection.
     class NodeSelection < Array
@@ -102,7 +102,7 @@ module Handsoap
     end
 
     # Wraps the underlying (native) xml driver, and provides a uniform interface.
-    module BaseDriver
+    module XmlElement
       def initialize(element, namespaces = {})
         @element = element
         @namespaces = namespaces
@@ -116,7 +116,7 @@ module Handsoap
       # Checks that an xpath-query doesn't refer to any undefined prefixes in +ns+
       def assert_prefixes!(expression, ns)
         expression.scan(/([a-zA-Z_][a-zA-Z0-9_.-]*):[^:]+/).map{|m| m[0] }.each do |prefix|
-          raise "Undefined prefix '#{prefix}'" if ns[prefix].nil?
+          raise "Undefined prefix '#{prefix}' in #{ns.inspect}" if ns[prefix].nil?
         end
       end
       # Returns the value of the element as an integer.
@@ -203,7 +203,7 @@ module Handsoap
     #
     # http://libxml.rubyforge.org/
     class LibXMLDriver
-      include BaseDriver
+      include XmlElement
       def node_name
         @element.name
       end
@@ -236,7 +236,7 @@ module Handsoap
     #
     # http://www.germane-software.com/software/rexml/
     class REXMLDriver
-      include BaseDriver
+      include XmlElement
       def node_name
         @element.name
       end
@@ -274,7 +274,7 @@ module Handsoap
     #
     # http://nokogiri.rubyforge.org/nokogiri/
     class NokogiriDriver
-      include BaseDriver
+      include XmlElement
       def node_name
         @element.name
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: troelskn-handsoap
 version: !ruby/object:Gem::Version 
-  version: 0.3.8
+  version: 0.4.0
 platform: ruby
 authors: 
 - Troels Knak-Nielsen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-30 00:00:00 -07:00
+date: 2009-07-31 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -33,7 +33,7 @@ files:
 - lib/handsoap/service.rb
 - lib/handsoap/xml_mason.rb
 - lib/handsoap/xml_query_front.rb
-has_rdoc: false
+has_rdoc: true
 homepage: http://github.com/troelskn/handsoap
 licenses: 
 post_install_message: 
@@ -62,7 +62,7 @@ requirements:
 rubyforge_project: 
 rubygems_version: 1.3.5
 signing_key: 
-specification_version: 3
+specification_version: 2
 summary: Handsoap is a library for creating SOAP clients in Ruby
 test_files: []