troelskn-handsoap 0.5.2 → 0.5.3

data/README.markdown

@@ -15,6 +15,8 @@ Handsoap is a library for creating SOAP clients in Ruby.
 
 API docs are at [http://rdoc.info/projects/troelskn/handsoap](http://rdoc.info/projects/troelskn/handsoap)
 
+Some usage information is to be found in [the wiki](http://wiki.github.com/troelskn/handsoap).
+
 ![Handsoap](http://ny-image0.etsy.com/il_430xN.68558416.jpg)
 
 Why
@@ -70,180 +72,26 @@ The protocol also contains a large and unwieldy specification of how to do the (
 
 Handsoap only supports RPC-style SOAP. This seems to be the most common style. It's probably possible to add support for Document-style with little effort, but until I see the need I'm not going there.
 
-API documnetation
+API documentation
 ---
 
 In addition to this guide, there's autogenerated API documentation available at [http://rdoc.info/projects/troelskn/handsoap](http://rdoc.info/projects/troelskn/handsoap)
 
-The toolbox
+Getting started
 ---
 
-The Handsoap toolbox consists of the following components.
-
-Handsoap can use either [curb](http://curb.rubyforge.org/) or [httpclient](http://dev.ctor.org/http-access2) for HTTP-connectivity. The former is recommended, and default, but for portability you might choose the latter. You usually don't need to interact at the HTTP-level, but if you do (for example, if you have to use SSL), you can.
+For getting started with Handsoap, you should read [the guide in the wiki](http://wiki.github.com/troelskn/handsoap/recommendations).
 
-For parsing XML, Handsoap defaults to use [Nokogiri](http://github.com/tenderlove/nokogiri/tree/master). Handsoap has an abstraction layer, so that you can switch between REXML, Nokogiri and ruby-libxml. Besides providing portability between these parsers, Handsop also gives some helper functions that are meaningful when parsing SOAP envelopes.
-
-There is also a library for generating XML, which you'll use when mapping from Ruby to SOAP. It's quite similar to [Builder](http://builder.rubyforge.org/), but is tailored towards being used for writing SOAP-messages. The name of this library is `XmlMason` and it is included/part of Handsoap.
-
-Recommendations
+The toolbox
 ---
 
-###Workflow
-
-1. You need a WSDL for the service you want to consume.
-
-2. Figure out the url for the endpoint, as well as the protocol version. Put this in a config file.
-	 * To find the endpoint, look inside the wsdl, for `<soap:address location="..">`
-
-3. Create a service class. Add endpoints and protocol. Alias needed namespace(s).
-   * To find the namespace(s), look in the samples from soapUI. It will be imported as `v1`
-   * Note that you can now use the provided generator to skip this step.
-
-4. Open the wsdl in [soapUI](http://www.soapui.org/).
-
-5. In soapUI, find a sample request for the method you want to use. Copy+paste the body-part.
-
-6. Create a method in your service class (Use ruby naming convention)
-
-7. Write Ruby-code (using XmlMason) to generate a request that is similar to the example from soapUI. (In your copy+paste buffer)
-
-8. Write Ruby-code to parse the response (an XML-document) into Ruby data types.
-
-9. Write an integration test to verify that your method works as expected. You can use soapUI to [generate a mock-service](http://www.soapui.org/userguide/mock/getting_started.html).
-
-Repeat point 5..9 for each method that you need to use.
-Between each iteration, you should refactor shared code into helper functions.
-
-###Configuration
-
-If you use Rails, you should put the endpoint in a constant in the environment file. That way, you can have different endpoints for test/development/production/etc.
-
-If you don't use Rails, it's still a good idea to move this information to a config file.
-
-The configuration could look like this:
-
-    # wsdl: http://example.org/ws/service?WSDL
-    EXAMPLE_SERVICE_ENDPOINT = {
-      :uri => 'http://example.org/ws/service',
-      :version => 2
-    }
-
-If you use Rails, you will need to load the gem from the `config/environment.rb` file, using:
-
-    config.gem 'troelskn-handsoap', :lib => 'handsoap', :source => "http://gems.github.com"
-
-If you use the standard development environment of Rails, you may run into troubles with cached classes. Add the following line to the initializer:
-
-    ActiveSupport::Dependencies.explicitly_unloadable_constants << 'Handsoap::Service'
-
-###Generator
-
-From version 0.2.0 Handsoap sports a generator, that creates the service class + an integration test case. This is just a rough starting point for your service - You still have to fill out the actual mappings to/from xml, but at least it saves your some copy-pasting from this guide.
-
-To use the generator, create a Rails project and run the script `script/generate handsoap`, giving the url of the WSDL.
-
-###Service class
-
-Put your service in a file under `app/models`. You should extend `Handsoap::Service`.
-
-You need to provide the endpoint and the SOAP version (1.1 or 1.2). If in doubt, use version 2.
-
-A service usually has a namespace for describing the message-body ([RPC/Litteral style](http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/#N1011F)). You should set this in the `on_create_document` handler. Likewise, the response returned *from* the server will contain elements that typically are defined in a single namespace relevant to the service. You can register this in the handler `on_response_document`.
-
-A typical service looks like the following:
-
-    # -*- coding: utf-8 -*-
-    require 'handsoap'
-
-    class Example::FooService < Handsoap::Service
-      endpoint EXAMPLE_SERVICE_ENDPOINT
-      def on_create_document(doc)
-        # register namespaces for the request
-        doc.alias 'tns', "http://example.org/ws/spec"
-      end
-      def on_response_document(doc)
-        # register namespaces for the response
-        doc.add_namespace 'ns', 'http://example.org/ws/spec'
-      end
-
-      # public methods
-      # todo
-
-      private
-      # helpers
-      # todo
-    end
-
-The above would go in the file `app/models/example/foo_service.rb`
-
-###Integration tests
-
-Since you're writing mappings manually, it's a good idea to write tests that verify that the service works. If you use standard Rails with `Test::Unit`, you should put these in an integration-test.
-
-For the sample service above, you would create a file in `test/integration/example/foo_service.rb`, with the following content:
-
-    # -*- coding: utf-8 -*-
-    require 'test_helper'
-
-    # Example::FooService.logger = $stdout
-
-    class Example::FooServiceTest < Test::Unit::TestCase
-      def test_update_icon
-        icon = { :href => 'http://www.example.com/icon.jpg', :type => 'image/jpeg' }
-        result = Example::FooService.update_icon!(icon)
-        assert_equal icon.type, result.type
-      end
-    end
-
-Note the commented-out line. If you set a logger on the service-class, you can see exactly which XML goes forth and back, which is very useful for debugging.
-
-###Methods
-
-You should use Ruby naming-conventions for methods names. If the method has side-effects, you should postfix it with an exclamation.
-Repeat code inside the invoke-block, should be refactored out to *builders*, and the response should be parsed with a *parser*.
-
-    def update_icon!(icon)
-      response = invoke("tns:UpdateIcon") do |message|
-        build_icon!(message, icon)
-      end
-      parse_icon(response/"//icon").first)
-    end
-
-
-###Helpers
-
-You'll end up with two kinds of helpers; Ruby->XML transformers (aka. *builders*) and XML->Ruby transformers (aka. *parsers*).
-It's recommended that you stick to the following style/naming scheme:
-
-    # icon -> xml
-    def build_icon!(message, icon)
-      message.add "icon" do |i|
-        i.set_attr "href", icon[:href]
-        i.set_attr "type", icon[:type]
-      end
-    end
-
-    # xml -> icon
-    def parse_icon(node)
-      { :href => (node/"@href").to_s, :type => (node/"@type").to_s }
-    end
+The Handsoap toolbox consists of the following components.
 
-or, if you prefer, you can use a class to represent entities:
+Handsoap can use either [curb](http://curb.rubyforge.org/), [Net::HTTP](http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html) or [httpclient](http://dev.ctor.org/http-access2) for HTTP-connectivity. The former is recommended, and default, but for portability you might choose one of the latter. You usually don't need to interact at the HTTP-level, but if you do (for example, if you have to use SSL), you can do so through a thin abstraction layer.
 
-    # icon -> xml
-    def build_icon!(message, icon)
-      message.add "icon" do |i|
-        i.set_attr "href", icon.href
-        i.set_attr "type", icon.type
-      end
-    end
+For parsing XML, Handsoap defaults to use [Nokogiri](http://github.com/tenderlove/nokogiri/tree/master). Handsoap has an abstraction layer, so that you can switch between REXML, Nokogiri and ruby-libxml. Besides providing portability between these parsers, Handsop also gives some helper functions that are meaningful when parsing SOAP envelopes.
 
-    # xml -> icon
-    def parse_icon(node)
-      Icon.new :href => (node/"@href").to_s,
-               :type => (node/"@type").to_s
-    end
+Finally, there is a library for generating XML, which you'll use when mapping from Ruby to SOAP. It's quite similar to [Builder](http://builder.rubyforge.org/), but is tailored towards being used for writing SOAP-messages. The name of this library is `XmlMason` and it is included/part of Handsoap.
 
 License
 ---

data/VERSION.yml

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

data/lib/handsoap/http.rb

@@ -237,6 +237,29 @@ module Handsoap
       end
     end
 
+    # A mock driver for your testing needs.
+    #
+    # To use it, create a new instance and assign to +Handsoap::Http.drivers+. Then configure +Handsoap::Service+ to use it:
+    #
+    #     Handsoap::Http.drivers[:mock] = Handsoap::Http::HttpMock.new :status => 200, :headers => headers, :content => body
+    #     Handsoap.http_driver = :mock
+    #
+    # Remember that headers should use \r\n, rather than \n.
+    class HttpMock
+      attr_accessor :mock, :last_request, :is_loaded
+      def initialize(mock)
+        @mock = mock
+        @is_loaded = false
+      end
+      def load!
+        is_loaded = true
+      end
+      def send_http_request(request)
+        @last_request = request
+        Handsoap::Http.parse_http_part(mock[:headers], mock[:content], mock[:status], mock[:content_type])
+      end
+    end
+
     # Parses a raw http response into a +Response+ or +Part+ object.
     def self.parse_http_part(headers, body, status = nil, content_type = nil)
       if headers.kind_of? String
@@ -363,7 +386,7 @@ module Handsoap
     def self.parse_headers(raw)
       header = Hash.new([].freeze)
       field = nil
-      raw.each {|line|
+      raw.gsub(/^(\r\n)+|(\r\n)+$/, '').each {|line|
         case line
         when /^([A-Za-z0-9!\#$%&'*+\-.^_`|~]+):\s*(.*?)\s*\z/om
           field, value = $1, $2

data/lib/handsoap/service.rb

@@ -290,112 +290,6 @@ module Handsoap
     end
     return xml_string
   end
-
-  # Parses a multipart http-response body into parts.
-  # +boundary+ is a string of the boundary token.
-  # +content_io+ is either a string or an IO. If it's an IO, then content_length must be specified.
-  # +content_length+ (optional) is an integer, specifying the length of +content_io+
-  #
-  # This code is lifted from cgi.rb
-  #
-  def self.parse_multipart(boundary, content_io, content_length = nil)
-    if content_io.kind_of? String
-      content_length = content_io.length
-      content_io = StringIO.new(content_io, 'r')
-    elsif !(content_io.kind_of? IO) || content_length.nil?
-      raise "Second argument must be String or IO with content_length"
-    end
-
-    boundary = "--" + boundary
-    quoted_boundary = Regexp.quote(boundary, "n")
-    buf = ""
-    bufsize = 10 * 1024
-    boundary_end = ""
-
-    # start multipart/form-data
-    content_io.binmode if defined? content_io.binmode
-    boundary_size = boundary.size + "\r\n".size
-    content_length -= boundary_size
-    status = content_io.read(boundary_size)
-    if nil == status
-      raise EOFError, "no content body"
-    elsif boundary + "\r\n" != status
-      raise EOFError, "bad content body"
-    end
-
-    parts = []
-
-    loop do
-      head = nil
-      if 10240 < content_length
-        require "tempfile"
-        body = Tempfile.new("CGI")
-      else
-        begin
-          require "stringio"
-          body = StringIO.new
-        rescue LoadError
-          require "tempfile"
-          body = Tempfile.new("CGI")
-        end
-      end
-      body.binmode if defined? body.binmode
-
-      until head and /#{quoted_boundary}(?:\r\n|--)/n.match(buf)
-
-        if (not head) and /\r\n\r\n/n.match(buf)
-          buf = buf.sub(/\A((?:.|\n)*?\r\n)\r\n/n) do
-            head = $1.dup
-            ""
-          end
-          next
-        end
-
-        if head and ( ("\r\n" + boundary + "\r\n").size < buf.size )
-          body.print buf[0 ... (buf.size - ("\r\n" + boundary + "\r\n").size)]
-          buf[0 ... (buf.size - ("\r\n" + boundary + "\r\n").size)] = ""
-        end
-
-        c = if bufsize < content_length
-              content_io.read(bufsize)
-            else
-              content_io.read(content_length)
-            end
-        if c.nil? || c.empty?
-          raise EOFError, "bad content body"
-        end
-        buf.concat(c)
-        content_length -= c.size
-      end
-
-      buf = buf.sub(/\A((?:.|\n)*?)(?:[\r\n]{1,2})?#{quoted_boundary}([\r\n]{1,2}|--)/n) do
-        body.print $1
-        if "--" == $2
-          content_length = -1
-        end
-        boundary_end = $2.dup
-        ""
-      end
-
-      body.rewind
-      parts << {:head => head, :body => body.read(body.size)}
-
-      # if body.kind_of? ::StringIO
-      #   parts << {:head => head, :body => body.string}
-      # elsif body.kind_of? ::Tempfile
-      #   body.rewind
-      #   parts << {:head => head, :body => body.read(body.size)}
-      # else
-      #   raise "body must be StringIO or Tempfile"
-      # end
-
-      break if buf.size == 0
-      break if content_length == -1
-    end
-    raise EOFError, "bad boundary end of body part" unless boundary_end =~ /--/
-    parts
-  end
-
 end
 
 # Legacy/BC code here. This shouldn't be used in new applications.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: troelskn-handsoap
 version: !ruby/object:Gem::Version 
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors: 
 - Troels Knak-Nielsen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-13 00:00:00 -07:00
+date: 2009-08-20 00:00:00 -07:00
 default_executable: 
 dependencies: []