Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 115 lines (72 sloc) 6.563 kb
bc5ab1d Added documentation
unwire\tkn authored
1 Handsoap
2 ===
3
9cc57dc Added note on how to install
unwire\tkn authored
4 Install
5 ---
6
61128a4 Updated install instructions to point to gemcutter
Troels authored
7 gem sources -a http://gemcutter.org
8 sudo gem install handsoap curb nokogiri
9cc57dc Added note on how to install
unwire\tkn authored
9
bc5ab1d Added documentation
unwire\tkn authored
10 What
11 ---
12 Handsoap is a library for creating SOAP clients in Ruby.
13
79b4072 linked to sample-app
unwire\tkn authored
14 [Watch a tutorial](http://www.vimeo.com/4813848), showing how to use Handsoap. The final application can be found at: [http://github.com/troelskn/handsoap-example/tree/master](http://github.com/troelskn/handsoap-example/tree/master)
99e0229 Aded link to tutorial
unwire\tkn authored
15
30c12da Updated links to point to new home
Troels Knak-Nielsen authored
16 API docs are at [http://rdoc.info/projects/unwire/handsoap/](http://rdoc.info/projects/unwire/handsoap/)
7c866f9 Added note on internal classes
Troels authored
17
30c12da Updated links to point to new home
Troels Knak-Nielsen authored
18 Some usage information is to be found in [the wiki](http://wiki.github.com/unwire/handsoap).
b433c7b @troelskn Moved guide into wiki
troelskn authored
19
6b58754 It's a handsoap
unwire\tkn authored
20 ![Handsoap](http://ny-image0.etsy.com/il_430xN.68558416.jpg)
21
bc5ab1d Added documentation
unwire\tkn authored
22 Why
23 ---
24
25 Ruby already has a SOAP-client library, [soap4r](http://dev.ctor.org/soap4r), so why create another one?
26
27 > Let me summarize SOAP4R: it smells like Java code built on a Monday morning by an EJB coder.
28 >
29 > -- [Ruby In Practice: REST, SOAP, WebSphere MQ and SalesForce](http://blog.labnotes.org/2008/01/28/ruby-in-practice-rest-soap-websphere-mq-and-salesforce/)
30
31 OK, not entirely fair, but soap4r has problems. It's incomplete and buggy. If you try to use it for any real-world services, you quickly run into compatibility issues. You can get around some of them, if you have control over the service, but you may not always be that lucky. In the end, even if you get it working, it has a bulky un-Rubyish feel to it.
32
33 Handsoap tries to do better by taking a minimalistic approach. Instead of a full abstraction layer, it is more like a toolbox with which you can write SOAP bindings. You could think of it as a [ffi](http://c2.com/cgi/wiki?ForeignFunctionInterface) targeting SOAP.
34
35 This means that you generally need to do more manual labor in the cases where soap4r would have automated the mapping. It also means that you need to get your hands dirty with wsdl, xsd and other heavyweight specifications. However, it does give you some tools to help you stay sane.
36
37 There are several benefits of using Handsoap:
38
39 * It supports the entire SOAP specification, all versions (because you have to implement it your self).
40 * You actually get a sporting chance to debug and fix protocol level bugs.
41 * It's much faster than soap4r, because it uses fast low-level libraries for xml-parsing and http-communication.
42
43 To summarise, soap4r takes an optimistic approach, where Handsoap expects things to fail. If soap4r works for you today, it's probably the better choice. If you find your self strugling with it, Handsoap will offer a more smooth ride. It won't magically fix things for you though.
44
b020793 Added benchmark to documentation
unwire\tkn authored
45 Handsoap vs. soap4r benchmark
46 ---
47
48 Benchmarks are always unfair, but my experiments has placed Handsoap at being approximately double as fast as soap4r. I'd love any suggestions for a more precise measure.
49
50 $ ruby tests/benchmark_test.rb 1000
51 Benchmarking 1000 calls ...
52 user system total real
53 handsoap 0.750000 0.090000 0.840000 ( 1.992437)
54 soap4r 2.240000 0.140000 2.380000 ( 3.605836)
55 ---------------
56 Legend:
57 The user CPU time, system CPU time, the sum of the user and system CPU times,
58 and the elapsed real time. The unit of time is seconds.
59
bc5ab1d Added documentation
unwire\tkn authored
60 SOAP basics
61 ---
62
63 SOAP is a protocol that is tunneled through XML over HTTP. Apart from using the technology for transportation, it doesn't have much to do with HTTP. Some times, it hasn't even got much to do with XML either.
64
65 A SOAP client basically consists of three parts:
66
67 * A http-connectivity layer,
68 * a mechanism for marshalling native data types to XML,
69 * and a mechanism for unmarshalling XML to native data types.
70
71 The protocol also contains a large and unwieldy specification of how to do the (un)marshalling, which can be used as the basis for automatically mapping to a rich type model. This makes the protocol fitting for .net/Java, but is a huge overhead for a very dynamically typed language such as Ruby. Much of the complexity of clients such as soap4r, is in the parts that tries to use this specification. Handsoap expects you to manually write the code that marshals/unmarshals, thereby bypassing this complexity (or rather - pass it to the programmer)
72
73 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.
74
b433c7b @troelskn Moved guide into wiki
troelskn authored
75 API documentation
f722b22 Added link to rdoc.info
Troels authored
76 ---
77
30c12da Updated links to point to new home
Troels Knak-Nielsen authored
78 In addition to this guide, there's autogenerated API documentation available at [http://rdoc.info/projects/unwire/handsoap/](http://rdoc.info/projects/unwire/handsoap/)
f722b22 Added link to rdoc.info
Troels authored
79
b433c7b @troelskn Moved guide into wiki
troelskn authored
80 Getting started
bc5ab1d Added documentation
unwire\tkn authored
81 ---
82
30c12da Updated links to point to new home
Troels Knak-Nielsen authored
83 For getting started with Handsoap, you should read [the guide in the wiki](http://wiki.github.com/unwire/handsoap/recommendations).
bc5ab1d Added documentation
unwire\tkn authored
84
b433c7b @troelskn Moved guide into wiki
troelskn authored
85 The toolbox
bc5ab1d Added documentation
unwire\tkn authored
86 ---
87
b433c7b @troelskn Moved guide into wiki
troelskn authored
88 The Handsoap toolbox consists of the following components.
bc5ab1d Added documentation
unwire\tkn authored
89
b433c7b @troelskn Moved guide into wiki
troelskn authored
90 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.
bc5ab1d Added documentation
unwire\tkn authored
91
b433c7b @troelskn Moved guide into wiki
troelskn authored
92 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.
bc5ab1d Added documentation
unwire\tkn authored
93
b433c7b @troelskn Moved guide into wiki
troelskn authored
94 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.
bc5ab1d Added documentation
unwire\tkn authored
95
13131a5 @jimmiw Added a maintainer and contributer area
jimmiw authored
96 Maintainers & Contributors
97 ---
98
99 Handsoap is maintained by [Unwire A/S](http://www.unwire.dk), namely [Troels Knak-Nielsen](http://github.com/troelskn) and [Jimmi Westerberg](http://github.com/jimmiw), with the help of many other contributors.
100
101 Use the git command below to see a list of them all. (GIT command was found at formtastic)
102
103 git shortlog -n -s --no-merges
104
b292a51 Added copyright notice
unwire\tkn authored
105 License
106 ---
107
108 Copyright: [Unwire A/S](http://www.unwire.dk), 2009
109
ec2698e Changed license to point to the English version of the license
unwire\tkn authored
110 License: [Creative Commons Attribution 2.5 Denmark License](http://creativecommons.org/licenses/by/2.5/dk/deed.en_GB)
f5eee9d Added LGPL license permissions
Troels authored
111 or: [LGPL 3](http://www.gnu.org/copyleft/lesser.html)
b292a51 Added copyright notice
unwire\tkn authored
112 ___
113
f5eee9d Added LGPL license permissions
Troels authored
114 troelskn@gmail.com - April, 2009
Something went wrong with that request. Please try again.