RELEASE_en.html

Revision 1560, 71.0 kB (checked in by nahi, 4 years ago)
follow #22.
Property svn:eol-style set to `native` Property svn:keywords set to `author date id revision`

Line
1	<?xml version="1.0"?>
2	<!DOCTYPE html
3	PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
4	"DTD/xhtml1-strict.dtd">
5	<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
6	<head>
7	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
8	<meta http-equiv="Content-Style-Type" content="text/css" />
9	<link rev="MADE" href="mailto:nakahiro@sarion.co.jp" />
10	<link rel="StyleSheet" href="rubyStyle.css" type="text/css" media="screen" />
11	<title>Release Notes - SOAP4R</title>
12	</head>
13	<body>
14
15	<div class="header">
16	<h1>
17	Release Notes - SOAP4R
18	</h1>
19
20	<p class="status">
21	Last modified: May 22, 2005<br />
22	Created: July 17, 2000
23	</p>
24	</div>
25
26	<hr />
27
28	<div class="main">
29	<h2><span class="content">0. In this document...</span></h2>
30
31	<p>
32	This is Release Notes of SOAP4R.
33	</p>
34
35	<p>
36	Target SOAP4R version: SOAP4R/1.5.4
37	</p>
38
39	<ol>
40	<li><a href="#changes">Changes</a></li>
41	<li><a href="#install">Install</a></li>
42	<li><a href="#uninstall">Uninstall</a></li>
43	<li><a href="#whats">What is SOAP4R?</a></li>
44	<li><a href="#dependencies">Dependencies</a></li>
45	<li><a href="#samples">Samples</a></li>
46	<li><a href="#restrictions">Restrictions</a></li>
47	<li><a href="#resources">Resources</a></li>
48	<li><a href="#history">History</a></li>
49	<li><a href="#author">Author</a></li>
50	<li><a href="#copyright">Copyright</a></li>
51	</ol>
52
53	<h2 id="changes" name="changes"><span class="content">1. Changes</span></h2>
54
55	<p>
56	This is version 1.5.4.
57	Version 1.5.3 is the module which is included in ruby-1.8.2,
58	and not released independently.
59	Following changes consist from 2 parts; Changes from 1.5.3 to 1.5.4,
60	and from 1.5.2 to 1.5.3.
61	</p>
62
63	<p>
64	Changes in 1.5.4 from 1.5.3
65	</p>
66
67	<ul>
68	<li>SOAP client and server
69	<ul>
70	<li>for both client side and server side
71	<ul>
72	<li>improved document/literal service support. style(rpc, document)/use(encoding, literal) combination are all supported. for the detail about combination, see test/soap/test_style.rb.</li>
73	<li>let WSDLEncodedRegistry#soap2obj map SOAP/OM to Ruby according to WSDL as well as obj2soap.</li>
74	<li>let SOAP::Mapping::Object handle XML attribute for doc/lit service. you can set/get XML attribute via accessor methods which as a name 'xmlattr_' prefixed (<foo name="bar"/> -> Foo#xmlattr_name).</li>
75	</ul>
76	</li>
77	<li>client side
78	<ul>
79	<li>WSDLDriver capitalized name operation bug fixed. from 1.5.3-ruby1.8.2, operation which has capitalized name (such as KeywordSearchRequest in AWS) is defined as a method having uncapitalized name. (converted with GenSupport.safemethodname to handle operation name 'foo-bar'). it introduced serious incompatibility; in the past, it was defined as a capitalized. define capitalized method as well under that circumstance.</li>
80	<li>added new factory interface 'WSDLDriverFactory#create_rpc_driver' to create RPC::Driver, not WSDLDriver (RPC::Driver and WSDLDriver are merged). 'WSDLDriverFactory#create_driver' still creates WSDLDriver for compatibility but it warns that the method is deprecated. please use create_rpc_driver instead of create_driver.</li>
81	<li>allow to use an URI object as an endpoint_url even with net/http, not http-access2.</li>
82	</ul>
83	</li>
84	<li>server side
85	<ul>
86	<li>added mod_ruby support to SOAP::CGIStub. rename a CGI script server.cgi to server.rb and let mod_ruby's RubyHandler handles the script. CGIStub detects if it's running under mod_ruby environment or not.</li>
87	<li>added fcgi support to SOAP::CGIStub. see the sample at sample/soap/calc/server.fcgi. (almost same as server.cgi but has fcgi handler at the bottom.)</li>
88	<li>allow to return a SOAPFault object to respond customized SOAP fault.</li>
89	<li>added the interface 'generate_explicit_type' for server side (CGIStub, HTTPServer). call 'self.generate_explicit_type = true' if you want to return simplified XML even if it's rpc/encoded service.</li>
90	</ul>
91	</li>
92	</ul>
93	</li>
94
95	<li>WSDL
96	<ul>
97	<li>WSDL definition
98	<ul>
99	<li>improved XML Schema support such as extension, restriction, simpleType, complexType + simpleContent, ref, length, import, include.</li>
100	<li>reduced "unknown element/attribute" warnings (warn only 1 time for each QName).</li>
101	<li>importing XSD file at schemaLocation with xsd:import.</li>
102	</ul>
103	</li>
104	<li>code generation from WSDL
105	<ul>
106	<li>generator crashed when there's '-' in defined element/attribute name.</li>
107	<li>added ApacheMap WSDL definition.</li>
108	</ul>
109	</li>
110	</ul>
111	</li>
112
113	<li>Samples
114	<ul>
115	<li>added XML <-> Ruby mapping utility. XSD::Mapping#xml2obj maps an XML to a tree of SOAP::Mapping::Object. XSD::Mapping#obj2xml is for reverse direction conversion. see a sample in sample/wsdl/noaa/client.rb</li>
116	<li>added a sample for weather.gov's NDFD services.</li>
117	<li>add a sample of googleAdWords. CAUTION: I don't have an account of AdWords so the sample code is NOT tested. Please tell me (nahi@ruby-lang.org) if you will get good/bad result in communicating with AdWords Server.</li>
118	<li>add a sample of AWSECommerce. CAUTION: I don't have an account of AWSECommerce so the sample code is NOT tested. Please tell me (nahi@ruby-lang.org) if you will get good/bad result in communicating with AWSECommerce Server.</li>
119	</ul>
120	</li>
121
122	<li>Redists
123	<ul>
124	<li>include xmlscan as a redistributed module. xmlscan now is a first class XML processor. still soap4r should run with REXML and XMLParser.</li>
125	</ul>
126	</li>
127	</ul>
128
129	<p>
130	Changes in 1.5.3 from 1.5.2
131	</p>
132
133	<ul>
134	<li>SOAP client and server
135	<ul>
136	<li>for both client side and server side
137	<ul>
138	<li>added a header handler class for simple SOAPHeader handling. see samples in sample/soap/authheader/*.</li>
139	<li>SSL support (both client side and server side). check sample/soap/ssl/*</li>
140	<li>gzipped content encoding support. see sample/soap/helloworld/hw_{c,s}_gzip.rb.</li>
141	</ul>
142	</li>
143	<li>client side
144	<ul>
145	<li>HTTP-Cookies support under soap4r + http-access2. not supported under soap4r + net/http.</li>
146	<li>added a method (SOAP::RPC::Driver#test_loopback_response) for loopback test with the specified response.</li>
147	<li>added SOAP::RPC::Driver#loadproperty interface to load property file.</li>
148	<li>let SOAP::RPC::Driver#add_method returns Method object. you can invoke a service like; drv.add_method("hello").call("world")</li>
149	<li>added http options to get/set timeout seconds.
150	<ul>
151	<li>for http-access2:
152	<ul>
153	<li>driver.options["protocol.http.connect_timeout"]</li>
154	<li>driver.options["protocol.http.send_timeout"]</li>
155	<li>driver.options["protocol.http.receive_timeout"]</li>
156	</ul>
157	</li>
158	<li>for net/http:
159	<ul>
160	<li>driver.options["protocol.http.connect_timeout"]</li>
161	<li>driver.options["protocol.http.receive_timeout"]</li>
162	</ul>
163	</li>
164	</ul>
165	</li>
166	<li>raise NotImplementedError when net/http + basic_auth.</li>
167	</ul>
168	</li>
169	<li>server side
170	<ul>
171	<li>introduced the new server class SOAP::RPC::HTTPServer which takes WEBrick's HTTPServer compatible config parameter.</li>
172	<li>added a debug log of SOAP request/response.</li>
173	</ul>
174	</li>
175	</ul>
176	</li>
177
178	<li>SOAP core part
179	<ul>
180	<li>added XMLSchema derived type support; byte, nonPositiveInteger, negativeInteger, nonNegativeInteger, positiveInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte.</li>
181	<li>'eval' cleanup. I hope it allows soap4r to work under mod_ruby environment.</li>
182	<li>SOAPProperty raise RuntimeError under ruby-1.9 when accessing locked property. still raises TypeError under ruby-1.8 or earlier. the change is from ruby's behaviour change about an exception when accessing a frozen object.</li>
183	<li>make SOAPHeader a child of SOAPStruct, not SOAPArray.</li>
184	<li>SOAPProperty does not eval whole string. \\, \t, \r, \n, \f escaping chars are supported like Java's Properties.</li>
185	<li>URI object was not mapped correctly so that URI object was not interoperable under some situation. fixed.</li>
186	<li>SOAP::Mapping::Object: handle multiple value as an array.
187	<pre>
188	<foo>
189	<bar>1</bar>
190	<bar>2</bar>
191	<bar>3</bar>
192	<baz>4</baz>
193	</foo>
194	->
195	foo.bar => [1, 2, 3]
196	foo.baz => 4
197	</pre>
198	</li>
199	<li>raise an exception while dumping singleton class. [ruby-dev:22588]
200	<pre>
201	e.g. c = class << Object.new
202	class C; self; end
203	end
204	SOAPMarshal.dump(c)
205	</pre>
206	</li>
207	</ul>
208	</li>
209
210	<li>WSDL
211	<ul>
212	<li>WSDL definition
213	<ul>
214	<li>added <xsd:simpleContent> support.</li>
215	<li>initial (means "far from complete") simpleType support.</li>
216	<li>support parts attribute of soap:body element.</li>
217	<li>xmlSchema's 'any' element support; for parsing, just treat the element as an element which has a name 'any'.</li>
218	<li>add mustUnderstand attribute support.</li>
219	<li>a special well-known type: ApacheMap support.</li>
220	</ul>
221	</li>
222
223	<li>code generation from WSDL
224	<ul>
225	<li>added simple code generation utils (lib/xsd/codegen)</li>
226	<li>dump attribute definition in XMLSchema as 'attr_*' attribute. [experimental]</li>
227	<li>wsdl2ruby.rb: add document/literal service support. see sample/wsdl/documentliteral/*</li>
228	<li>untyped element should be treated as xsd:anyType.</li>
229	<li>added a tool xsd2ruby.rb for generating classdef from xsd file.</li>
230	</ul>
231	</li>
232	</ul>
233	</li>
234
235	<li>Samples
236	<ul>
237	<li>added RAA/2.4 sample client</li>
238	<li>added sample for Application/Request scope use. Session scope (with Cookies) feature is not yet exists.</li>
239	</ul>
240	</li>
241	</ul>
242
243	<p>
244	For details, see ChangeLog.
245	</p>
246
247	<p>
248	Thanks to all of soap4r ML members and soap4r users for their support.
249	</p>
250
251	<h2 id="install" name="install"><span class="content">2. Install</span></h2>
252
253	<p>
254	At first, see <a href="#dependencies">Dependencies</a> section.
255	You may need to install some extra packages.
256	Next, get the archived file of SOAP4R and extract it, then simply try;
257	</p>
258	<pre class="path">
259	$ ruby install.rb
260	</pre>
261
262	<p>
263	Necessary files will be installed to suitable directory.
264	</p>
265
266	<p>
267	Files and directories in lib directory are SOAP4R library program itself.
268	</p>
269
270	<dl>
271	<dt class="path">lib/</dt>
272	<dd>Libraries.</dd>
273
274	<dt class="path">sample/</dt>
275	<dd>SOAP4R samples.
276	See <a href="#samples">Samples</a> section.</dd>
277
278	<dt class="path">test/</dt>
279	<dd>Tests. It also contains useful sample scripts for servers and clients.
280	<br/>
281	test/interopR2/ directory includes Clients/Server for
282	<a href="http://www.xmethods.net/ilab/">`SOAPBuilders Interoperability Lab.'</a>
283	Followings are advanced examples to use complex type transmit,
284	sending base64 encoded string, multi-dimensional array, and so on.
285	<ul>
286	<li>test/interopR2/server.rb is a RPC Server side implementation.</li>
287	<li>test/interopR2/client.rb is a RPC Client side implementation.</li>
288	<li>test/interopR2/base.rb includes common definitions for client/server.</li>
289	</ul>
290	</dd>
291	</dl>
292
293	<h2 id="uninstall" name="uninstall"><span class="content">3. Uninstall</span></h2>
294
295	<p>
296	Simply delete installed files.
297	</p>
298
299	<h2 id="whats" name="whats"><span class="content">4. What is SOAP4R?</span></h2>
300
301	<p>
302	'SOAP4R' is an implementation of
303	<a href="http://www.w3.org/TR/SOAP/">Simple Object Access Protocol (SOAP) 1.1 (W3C Note)</a>.
304	</p>
305
306	<p>
307	Comments, information such as interoperability between SOAP4R and another implementation are welcomed.
308	Feel free sending mail to
309	<a href="mailto:nakahiro@sarion.co.jp" class="path">nakahiro@sarion.co.jp</a>.
310	</p>
311
312	<h2 id="dependencies" name="dependencies"><span class="content">5. Dependencies</span></h2>
313
314	<p>
315	SOAP4R is written in <a href="http://www.ruby-lang.org">Ruby</a> and
316	aims to use with Ruby application.
317	You have to install Ruby itself.
318	Ruby/1.6 series or later is required.
319	</p>
320	<ul>
321	<li>ruby-1.8.2</li>
322	<li>ruby-1.8.1</li>
323	<li>ruby-1.6.8</li>
324	<li>developing version of ruby-1.9.x at Ruby's CVS repository(HEAD)</li>
325	<li>developing version of ruby-1.8.x at Ruby's CVS repository(ruby_1_8)</li>
326	</ul>
327
328	<p>
329	SOAP4R depends on following Ruby modules in
330	<a href="http://raa.ruby-lang.org">RAA</a>.
331	You also have to install these modules to use SOAP4R.
332	</p>
333
334	<h3>for ruby-1.8.2, ruby-1.8.1, developing versions of ruby-1.9.x and ruby-1.8.x</h3>
335
336	<dl>
337	<dt class="path"><a href="http://raa.ruby-lang.org/project/http-access2/">[RAA:http-access2]</a> (2.0.5) (required for SSL)</dt>
338	<dd>Yet another HTTP client implementation by NaHi.
339	It's not required when you don't use SSL, but it's recommended to use.
340	The author always runs and checks soap4r with http-access2.</dd>
341
342	<dt class="path"><a href="http://raa.ruby-lang.org/project/uconv/">[RAA:uconv]</a> (0.4.10) (not required but needed if your Ruby doesn't have iconv module and you need UTF-8 encoded Japanese chars)</dt>
343	<dd>by Yoshida Masato.
344	It is requred when you want automatic CES conversion between
345	SJIS <-> UTF8 and EUC <-> UTF8.
346	Note: SJIS <-> EUC uses NKF module which is in standard distribution.
347	</dd>
348
349	</dl>
350
351	<h3>for ruby-1.6.8</h3>
352
353	<dl>
354	<dt class="path"><a href="http://raa.ruby-lang.org/project/webrick/">[RAA:webrick]</a> (1.3.1)</dt>
355	<dd>TCP server toolkit by Gotoyuzo.</dd>
356
357	<dt class="path"><a href="http://raa.ruby-lang.org/project/http-access2/">[RAA:http-access2]</a> (2.0.5)</dt>
358	<dd>Yet another HTTP client implementation by NaHi.</dd>
359
360	<dt class="path"><a href="http://raa.ruby-lang.org/project/devel-logger/">[RAA:devel-logger]</a> (1.1.0)</dt>
361	<dd>Logging utility by NaHi.</dd>
362
363	<dt class="path"><a href="http://raa.ruby-lang.org/project/date2/">[RAA:date2]</a> (3.2)</dt>
364	<dd>Date and DateTime implementation by Todayoshi Funaba.</dd>
365
366	<dt class="path"><a href="http://raa.ruby-lang.org/project/uconv/">[RAA:uconv]</a> (0.4.10) (required for UTF-8 handling)</dt>
367	<dd>by Yoshida Masato.
368	It is requred when you want automatic CES conversion between
369	SJIS <-> UTF8 and EUC <-> UTF8.
370	Note: SJIS <-> EUC uses NKF module which is in standard distribution.
371	</dd>
372
373	</dl>
374
375	<h2 id="samples" name="samples"><span class="content">6. Samples</span></h2>
376
377	<p>
378	Samples are in sample/ directory of distribution.
379	Some samples try to connect to public servers.
380	Set environment variable SOAP_USE_PROXY and HTTP_PROXY if you are in a firewall and you have
381	http proxy to the internet like;
382	</p>
383	<pre class="path">
384	$ export SOAP_USE_PROXY=on
385	$ export HTTP_PROXY=http://myproxyserver:8080
386	or
387	$ setenv SOAP_USE_PROXY on
388	$ setenv HTTP_PROXY http://myproxyserver:8080
389	</pre>
390
391	<dl>
392	<dt class="path">soap/</dt>
393	<dd>
394	<dl>
395	<dt class="path">calc/</dt>
396	<dd>Calc service contains 2 servers and 2 clients.
397	calc.rb is hosted by server.rb, calc2.rb is hosted by server2.rb.
398	client.rb is for server.rb, client2.rb is for server2.rb.
399	<dl>
400	<dt>calc.rb</dt>
401	<dd>Calc server definition using module and module methods.
402	This module responds 'add', 'sub', 'multi' and 'div'.
403	</dd>
404	<dt>server.rb</dt>
405	<dd>Standalone server.
406	It requires calc.rb and serve module methods of this module.
407	To run this server;
408	<pre class="path">
409	$ ./server.rb
410	</pre>
411	</dd>
412	<dt>server.cgi</dt>
413	<dd>CGI version.
414	To run this server, copy server.cgi and calc.rb to suitable
415	directory of your WWW server.
416	</dd>
417	<dt>client.rb</dt>
418	<dd>It connects to server.rb or server.cgi,
419	and hit methods served by calc.rb.
420	To run the client;
421	<pre class="path">
422	$ ./client.rb
423	</pre>
424	Is it stacked? Did you run the server.rb?<br/>
425	Turn logger and wireDumpDev in its source on to see logs and wire
426	dumps of SOAP transport.
427	</dd>
428	<dt>calc2.rb</dt>
429	<dd>Calc server definition using class and instance methods.
430	An instance of this class holds its value. Methods 'set' and 'get'
431	is to set/get the value.
432	It also responds to '+', '-', '*', and '/'.
433	</dd>
434	<dt>server2.rb</dt>
435	<dd>It requires calc2.rb and creates an instance of CalcService2
436	that responds all SOAP requests.
437	Since '+', '-' and so on of calc2.rb are not valid name as an
438	element in XML instance, this sample register the method '+' as
439	'add', '-' as 'sub', and so on.
440	</dd>
441	<dt>server2.cgi</dt>
442	<dd>CGI version.
443	To run this server, copy server2.cgi and calc2.rb to suitable
444	directory of your WWW server.
445	</dd>
446	<dt>client2.rb</dt>
447	<dd>It connects to server2.rb or server2.cgi.
448	Set a value at first and call methods like 'puts objAtServer + 2'.
449	</dd>
450	</dl>
451	</dd>
452
453	<dt class="path">exchange/</dt>
454	<dd>A sample to retrieve the currency rate from public SOAP service.
455	<dl>
456	<dt>iExchange.rb</dt>
457	<dd>It includes common definitions for client and server of
458	Exchange service. Including only a definition of namespace URI of
459	this service.</dd>
460	<dt>exchange.rb</dt>
461	<dd>Definition of servant class ExchangeService which returns the
462	currency rate after connecting to another site by SOAP to get the
463	real rate.
464	So that this class is the SOAP server for local client and
465	is also a SOAP client for public server.
466	An instance of this class is hosted by server.rb.
467	The instance responds to only 'getRate' which receives two country
468	code such as 'USA' and 'Japan'.</dd>
469	<dt>server.rb</dt>
470	<dd>It requires exchange.rb and creates an instance of
471	ExchangeService that responds all SOAP requests.
472	To run this server;
473	<pre class="path">
474	$ ./server.rb
475	</pre>
476	</dd>
477	<dt>server.cgi</dt>
478	<dd>CGI version. To run this server, copy server.cgi and exchange.rb
479	to suitable directory of your WWW server.</dd>
480	<dt>client.rb</dt>
481	<dd>It connects to server.rb. Turn logger and wireDumpDev in its
482	source on to see logs and wire dumps of SOAP transport.
483	To run the client;
484	<pre class="path">
485	$ ./client.rb
486	</pre>
487	</dd>
488	</dl>
489	</dd>
490
491	<dt class="path">authheader/</dt>
492	<dd>It contains a sample to utilize SOAP Header handler. Send
493	userid/passwd and receive sessionid via SOAP Header</dd>
494
495	<dt class="path">raa2.4/</dt>
496	<dd>sample/soap/raa2.4/sample.rb is a sample client to retrieve project
497	information on RAA. It uses raaDriver.rb which is generated by
498	wsdl2ruby.rb from WSDL at
499	<a href="http://www.ruby-lang.org/xmlns/soap/interface/RAA/0.0.4/">http://www.ruby-lang.org/xmlns/soap/interface/RAA/0.0.4/</a>.
500	You'll find wsdlDriver.rb in sample/wsdl/raa2.4/wsdlDriver.rb which
501	loads the WSDL at runtime to connect.</dd>
502
503	<dt class="path">scopesample/</dt>
504	<dd>SOAP server sample which shows a different behavior of SOAP server scope settings; Request scope vs Application scope.
505	sample/soap/scopesample/servant.rb is a servant which holds push-ed
506	object that can be pop-ed afterward.
507	See sample/soap/scopesample/server.rb how to define a servant as
508	a Request scope servant or an Application scope servant.
509	Application scope servant works as we expected because the servant
510	object is living from beginning to the time server terminated.
511	In contrast, request scope servant(s) does not work because a servant
512	object is created for each request.
513	</dd>
514
515	<dt class="path">ssl/</dt>
516	<dd>SSL SOAP server and client samples.
517	<dl>
518	<dt class="path">sslserver.rb</dt>
519	<dd>SSL server sample which hosts "hello world" service.
520	This server uses SSL server certificate in files/ directory
521	(SSL client should check this certificate for SSL server
522	authentication).</dd>
523	<dt class="path">sslserver_noauth.rb</dt>
524	<dd>This server generates SSL server certificate
525	at runtime. No security.</dd>
526	<dt class="path">sslserver_require_clientauth.rb</dt>
527	<dd>This server users SSL server certificate in files/ directory
528	and requires SSL client authentication (clients must
529	have SSL client certificate and send it to the server).</dd>
530	<dt class="path">sslclient.rb</dt>
531	<dd>SSL client sample which calls "hello world" service via HTTPS.
532	This client checks SSL server certificate sent from SSL server.</dd>
533	<dt class="path">sslclient_require_noserverauth.rb</dt>
534	<dd>This client does not check SSL server certificate.
535	No security.</dd>
536	<dt class="path">sslclient_with_clientauth.rb</dt>
537	<dd>This client sends SSL client certificate in files/ directory
538	and checks SSL server certificate.</dd>
539	</dl>
540	</dd>
541
542	<dt class="path">swa/</dt>
543	<dd>SOAP server and client sample of SwA (SOAP with Attachments).</dd>
544
545	<dt class="path">digraph.rb</dt>
546	<dd>A sample of SOAP marshalling/unmarshalling.
547	It creates a digraph that contains multi-ref-ed nodes at first
548	and marshals this object to get serialized XML instance.
549	Then reads and unmarshals this XML instance to recover a object
550	which has the same links among nodes in the digraph.
551	</dd>
552
553	<dt class="path">sampleStruct/</dt>
554	<dd>A sample to transmit complex structured object which has recursive
555	object reference.
556	<dl>
557	<dt>iSampleStruct.rb</dt>
558	<dd>It includes common definitions for client and server of
559	SampleStruct service. Definition of SampleStruct class and
560	namespace URI of this service.</dd>
561	<dt>sampleStruct.rb</dt>
562	<dd>Definition of servant class SampleStructService.
563	An instance of this class is hosted by server.rb.
564	The instance responds to only 'hi' which receives a SampleStruct
565	and wraps it in the new instance of SampleStruct to return .</dd>
566	<dt>server.rb</dt>
567	<dd>It requires sampleStruct.rb and creates an instance of
568	SampleStructService that responds all SOAP requests.
569	To run this server;
570	<pre class="path">
571	$ ./server.rb
572	</pre>
573	</dd>
574	<dt>server.cgi</dt>
575	<dd>CGI version. To run this server, copy server.cgi and
576	sampleStruct.rb to suitable directory of your WWW server.</dd>
577	<dt>client.rb</dt>
578	<dd>It connects to server.rb. Turn logger and wireDumpDev in its
579	source on to see logs and wire dumps of SOAP transport.
580	To run the client;
581	<pre class="path">
582	$ ./client.rb
583	</pre>
584	</dd>
585	</dl>
586	</dd>
587
588	<dt class="path">icd/</dt>
589	<dd>A client for
590	<a href="http://www.iwebmethod.net/">Insider's Computer Dictionary Web Service</a>.
591	This service is implemented with ASP.NET so that it's also a sample of
592	a client which connects to ASP.NET.
593	CAUTION: this sample contains non-ascii chars in its source and dumped
594	results.
595	<dl>
596	<dt>IICD.rb</dt>
597	<dd>Class(type) definitions for this server.</dd>
598	<dt>icd.rb</dt>
599	<dd>Client implementation. To run the client;
600	<pre class="path">
601	$ ./icd.rb
602	</pre>
603	</dd>
604	</dl>
605	</dd>
606	</dl>
607	</dd>
608
609	<dt class="path">wsdl/</dt>
610	<dd>
611	<dl>
612	<dt class="path">googleSearch/</dt>
613	<dd>Sample client to search with <a href="http://www.google.com/apis/">Google Web API</a> using WSDL. You need to get a developer's key to use it. See wsdlDriver.rb.</dd>
614
615	<dt class="path">amazon/</dt>
616	<dd>Sample client to connect with <a href="http://associates.amazon.com/exec/panama/associates/ntg/browse/-/1067662/086-5207681-4585409">AmazonWebServices</a> using WSDL. See wsdlDriver.rb.</dd>
617
618	<dt class="path">documentliteral/</dt>
619	<dd>Sample client and server of document/literal service. See README.txt in this directory to run this sample.</dd>
620
621	<dt class="path">noaa/</dt>
622	<dd>Sample client of National Weather Service digital weather forecast data service at http://weather.gov/</dd>
623
624	<dt class="path">raa2.4/</dt>
625	<dd>sample/wsdl/raa2.4/wsdlDriver.rb is a sample client to retrieve
626	project information on RAA. It loads WSDL file
627	<a href="http://www.ruby-lang.org/xmlns/soap/interface/RAA/0.0.4/">http://www.ruby-lang.org/xmlns/soap/interface/RAA/0.0.4/</a>
628	at <strong>runtime</strong>.
629	You'll find a sample client at sample/soap/raa2.4/sample.rb
630	which connects RAA using pre-generated service definitions
631	(not loads WSDL at runtime).</dd>
632
633	<dt class="path">googleAdwords/</dt>
634	<dd>Sample client of Google AdWords service.
635	CAUTION: I don't have an account of AdWords so the sample code is NOT
636	tested. Please tell me (nahi@ruby-lang.org) if you will get good/bad
637	result in communicating with AdWords Server.</dd>
638
639	<dt class="path">amazonEC/</dt>
640	<dd>Sample client of AWSECommerce service.
641	CAUTION: I don't have an account of AWSECommerce so the sample code is
642	NOT tested. Please tell me (nahi@ruby-lang.org) if you will get
643	good/bad result in communicating with AWSECommerce Server.</dd>
644	</dl>
645	</dd>
646
647	</dl>
648	</dd>
649
650	</dl>
651
652	<h2 id="restrictions" name="restrictions"><span class="content">7. Restrictions</span></h2>
653
654	<p>
655	The following features of the
656	<a href="http://www.w3.org/TR/SOAP/">SOAP 1.1 (W3C Note)</a>
657	spec are <strong>NOT</strong> currently supported:
658	</p>
659
660	<ul>
661	<li style="margin-top: 2ex;">SOAP Envelope
662	<ul>
663	<li>SOAP actor attribute</li>
664	<li>SOAP Fault Codes</li>
665	</ul></li>
666	<li style="margin-top: 2ex;">Othres
667	<ul>
668	<li>Transport binding except HTTP server and client</li>
669	</ul></li>
670	</ul>
671
672	<h2 id="resources" name="resources"><span class="content">8. Resources</span></h2>
673
674	<dl>
675	<dt class="path"><a href="http://dev.ctor.org/soap4r">soap4r project page</a></dt>
676	<dd>You can get the latest information and the latest development version of soap4r here.</dd>
677
678	<dt class="path"><a href="http://raa.ruby-lang.org/project/soap4r">[RAA:soap4r]</a></dt>
679	<dd>RAA meta information</dd>
680
681	<dt class="path"><a href="http://groups-beta.google.com/group/soap4r">soap4r Mailing List on Google Groups</a></dt>
682	<dd>Feel free to join the list to ask any question and comment about soap4r.
683	You can browse messages archive. Bear in mind that Google Groups is still
684	in [beta] stage.</dd>
685
686	<dt class="path">Subversion repository</dt>
687	<dd>Soap4r's svn repository is here: http://dev.ctor.org/svn/soap4r/ .
688	To checkout the latest soap4r module, try
689	<pre>
690	svn checkout http://dev.ctor.org/svn/soap4r/trunk soap4r
691	</pre>
692	CVS repository of soap4r which was located at cvs.ruby-lang.org is pending since 2004-05-27. </dd>
693	</dl>
694
695	<h2 id="history" name="history"><span class="content">9. History</span></h2>
696
697	<dl>
698	<dt>1.5.4 - May 13, 2005</dt>
699	<dd>This is version 1.5.4.
700	Version 1.5.3 is the module which is included in ruby-1.8.2,
701	and not released independently.
702	Following changes consist from 2 parts; Changes from 1.5.3 to 1.5.4,
703	and from 1.5.2 to 1.5.3.
704	<br/><br/>
705	Changes in 1.5.4 from 1.5.3
706	<br/><br/>
707	<ul>
708	<li>SOAP client and server
709	<ul>
710	<li>for both client side and server side
711	<ul>
712	<li>improved document/literal service support. style(rpc, document)/use(encoding, literal) combination are all supported. for the detail about combination, see test/soap/test_style.rb.</li>
713	<li>let WSDLEncodedRegistry#soap2obj map SOAP/OM to Ruby according to WSDL as well as obj2soap.</li>
714	<li>let SOAP::Mapping::Object handle XML attribute for doc/lit service. you can set/get XML attribute via accessor methods which as a name 'xmlattr_' prefixed (<foo name="bar"/> -> Foo#xmlattr_name).</li>
715	</ul>
716	</li>
717	<li>client side
718	<ul>
719	<li>WSDLDriver capitalized name operation bug fixed. from 1.5.3-ruby1.8.2, operation which has capitalized name (such as KeywordSearchRequest in AWS) is defined as a method having uncapitalized name. (converted with GenSupport.safemethodname to handle operation name 'foo-bar'). it introduced serious incompatibility; in the past, it was defined as a capitalized. define capitalized method as well under that circumstance.</li>
720
721	<li>added new factory interface 'WSDLDriverFactory#create_rpc_driver' to create RPC::Driver, not WSDLDriver (RPC::Driver and WSDLDriver are merged). 'WSDLDriverFactory#create_driver' still creates WSDLDriver for compatibility but it warns that the method is deprecated. please use create_rpc_driver instead of create_driver.</li>
722	<li>allow to use an URI object as an endpoint_url even with net/http, not http-access2.</li>
723	</ul>
724	</li>
725	<li>server side
726	<ul>
727	<li>added mod_ruby support to SOAP::CGIStub. rename a CGI script server.cgi to server.rb and let mod_ruby's RubyHandler handles the script. CGIStub detects if it's running under mod_ruby environment or not.</li>
728	<li>added fcgi support to SOAP::CGIStub. see the sample at sample/soap/calc/server.fcgi. (almost same as server.cgi but has fcgi handler at the bottom.)</li>
729	<li>allow to return a SOAPFault object to respond customized SOAP fault.</li>
730	<li>added the interface 'generate_explicit_type' for server side (CGIStub, HTTPServer). call 'self.generate_explicit_type = true' if you want to return simplified XML even if it's rpc/encoded service.</li>
731	</ul>
732	</li>
733	</ul>
734	</li>
735
736	<li>WSDL
737	<ul>
738	<li>WSDL definition
739	<ul>
740	<li>improved XML Schema support such as extension, restriction, simpleType, complexType + simpleContent, ref, length, import, include.</li>
741	<li>reduced "unknown element/attribute" warnings (warn only 1 time for each QName).</li>
742	<li>importing XSD file at schemaLocation with xsd:import.</li>
743	</ul>
744	</li>
745	<li>code generation from WSDL
746	<ul>
747	<li>generator crashed when there's '-' in defined element/attribute name.</li>
748	<li>added ApacheMap WSDL definition.</li>
749	</ul>
750	</li>
751	</ul>
752	</li>
753
754	<li>Samples
755	<ul>
756	<li>added XML <-> Ruby mapping utility. XSD::Mapping#xml2obj maps an XML to a tree of SOAP::Mapping::Object. XSD::Mapping#obj2xml is for reverse direction conversion. see a sample in sample/wsdl/noaa/client.rb</li>
757	<li>added a sample for weather.gov's NDFD services.</li>
758	<li>add a sample of googleAdWords. CAUTION: I don't have an account of AdWords so the sample code is NOT tested. Please tell me (nahi@ruby-lang.org) if you will get good/bad result in communicating with AdWords Server.</li>
759	<li>add a sample of AWSECommerce. CAUTION: I don't have an account of AWSECommerce so the sample code is NOT tested. Please tell me (nahi@ruby-lang.org) if you will get good/bad result in communicating with AWSECommerce Server.</li>
760	</ul>
761	</li>
762
763	<li>Redists
764	<ul>
765	<li>include xmlscan as a redistributed module. xmlscan now is a first class XML processor. still soap4r should run with REXML and XMLParser.</li>
766	</ul>
767	</li>
768	</ul>
769	<br/>
770	Changes in 1.5.3 from 1.5.2
771	<br/><br/>
772	<ul>
773	<li>SOAP client and server
774	<ul>
775	<li>for both client side and server side
776	<ul>
777	<li>added a header handler class for simple SOAPHeader handling. see samples in sample/soap/authheader/*.</li>
778	<li>SSL support (both client side and server side). check sample/soap/ssl/*</li>
779	<li>gzipped content encoding support. see sample/soap/helloworld/hw_{c,s}_gzip.rb.</li>
780	</ul>
781	</li>
782	<li>client side
783	<ul>
784	<li>HTTP-Cookies support under soap4r + http-access2. not supported under soap4r + net/http.</li>
785	<li>added a method (SOAP::RPC::Driver#test_loopback_response) for loopback test with the specified response.</li>
786	<li>added SOAP::RPC::Driver#loadproperty interface to load property file.</li>
787	<li>let SOAP::RPC::Driver#add_method returns Method object. you can invoke a service like; drv.add_method("hello").call("world")</li>
788	<li>added http options to get/set timeout seconds.
789	<ul>
790	<li>for http-access2:
791	<ul>
792	<li>driver.options["protocol.http.connect_timeout"]</li>
793	<li>driver.options["protocol.http.send_timeout"]</li>
794	<li>driver.options["protocol.http.receive_timeout"]</li>
795	</ul>
796	</li>
797	<li>for net/http:
798	<ul>
799	<li>driver.options["protocol.http.connect_timeout"]</li>
800	<li>driver.options["protocol.http.receive_timeout"]</li>
801	</ul>
802	</li>
803	</ul>
804	</li>
805	<li>raise NotImplementedError when net/http + basic_auth.</li>
806	</ul>
807	</li>
808	<li>server side
809	<ul>
810	<li>introduced the new server class SOAP::RPC::HTTPServer which takes WEBrick's HTTPServer compatible config parameter.</li>
811	<li>added a debug log of SOAP request/response.</li>
812	</ul>
813	</li>
814	</ul>
815	</li>
816
817	<li>SOAP core part
818	<ul>
819	<li>added XMLSchema derived type support; byte, nonPositiveInteger, negativeInteger, nonNegativeInteger, positiveInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte.</li>
820	<li>'eval' cleanup. I hope it allows soap4r to work under mod_ruby environment.</li>
821	<li>SOAPProperty raise RuntimeError under ruby-1.9 when accessing locked property. still raises TypeError under ruby-1.8 or earlier. the change is from ruby's behaviour change about an exception when accessing a frozen object.</li>
822	<li>make SOAPHeader a child of SOAPStruct, not SOAPArray.</li>
823	<li>SOAPProperty does not eval whole string. \\, \t, \r, \n, \f escaping chars are supported like Java's Properties.</li>
824	<li>URI object was not mapped correctly so that URI object was not interoperable under some situation. fixed.</li>
825	<li>SOAP::Mapping::Object: handle multiple value as an array.
826	<pre>
827	<foo>
828	<bar>1</bar>
829	<bar>2</bar>
830	<bar>3</bar>
831	<baz>4</baz>
832	</foo>
833	->
834	foo.bar => [1, 2, 3]
835	foo.baz => 4
836	</pre>
837	</li>
838	<li>raise an exception while dumping singleton class. [ruby-dev:22588]
839	<pre>
840	e.g. c = class << Object.new
841	class C; self; end
842	end
843	SOAPMarshal.dump(c)
844	</pre>
845	</li>
846	</ul>
847	</li>
848
849	<li>WSDL
850	<ul>
851	<li>WSDL definition
852	<ul>
853	<li>added <xsd:simpleContent> support.</li>
854	<li>initial (means "far from complete") simpleType support.</li>
855	<li>support parts attribute of soap:body element.</li>
856	<li>xmlSchema's 'any' element support; for parsing, just treat the element as an element which has a name 'any'.</li>
857	<li>add mustUnderstand attribute support.</li>
858	<li>a special well-known type: ApacheMap support.</li>
859	</ul>
860	</li>
861
862	<li>code generation from WSDL
863	<ul>
864	<li>added simple code generation utils (lib/xsd/codegen)</li>
865	<li>dump attribute definition in XMLSchema as 'attr_*' attribute. [experimental]</li>
866	<li>wsdl2ruby.rb: add document/literal service support. see sample/wsdl/documentliteral/*</li>
867	<li>untyped element should be treated as xsd:anyType.</li>
868	<li>added a tool xsd2ruby.rb for generating classdef from xsd file.</li>
869	</ul>
870	</li>
871	</ul>
872	</li>
873
874	<li>Samples
875	<ul>
876	<li>added RAA/2.4 sample client</li>
877	<li>added sample for Application/Request scope use. Session scope (with Cookies) feature is not yet exists.</li>
878	</ul>
879	</li>
880	</ul>
881	</dd>
882
883	<dt>1.5.2 - December 25, 2003</dt>
884	<dd>
885	<ul>
886	<li>License;
887	<ul>
888	<li>Changed license from GPL2 to Ruby's.</li>
889	</ul></li>
890
891	<li>Features;
892	<ul>
893	<li>Add SOAP Messages with Attachments (SwA) support.
894	Patched by Jamie Herre.
895	"SOAP Messages with Attachments" is the W3C Note which defines a
896	binding for a SOAP 1.1 message to be carried within a MIME
897	multipart/related message. <a href="http://www.w3.org/TR/SOAP-attachments">http://www.w3.org/TR/SOAP-attachments</a>
898	This feature is still experimental. Interop testing is going on.</li>
899
900	<li>HTTPS support even when you use net/http (not http-access2).
901	Patched by Oliver M. Bolzer.</li>
902
903	<li>Property file support. SOAP and WSDL client reads "soap/property"
904	file located at somewhere in $: (ruby libray locations). For
905	example, save these lines to
906	"$rubylibdir/site_ruby/1.8/soap/property".
907	<pre>
908	client.protocol.http.proxy = http://myproxy:8080
909	client.protocol.http.no_proxy = 192.168.71.71,192.168.71.72
910	</pre>
911	Then all HTTP connections should use these proxy and no_proxy
912	definition.</li>
913
914	<li>Do not trust "HTTP_PROXY" environment variable by default to
915	avoid security problem. cf.
916	<ul>
917	<li><a href="http://ftp.ics.uci.edu/pub/websoft/libwww-perl/archive/2001h1/0072.html">http://ftp.ics.uci.edu/pub/websoft/libwww-perl/archive/2001h1/0072.html</a></li>
918	<li><a href="http://ftp.ics.uci.edu/pub/websoft/libwww-perl/archive/2001h1/0241.html">http://ftp.ics.uci.edu/pub/websoft/libwww-perl/archive/2001h1/0241.html</a></li>
919	<li><a href="http://curl.haxx.se/mail/archive-2001-12/0034.html">http://curl.haxx.se/mail/archive-2001-12/0034.html</a></li>
920	</ul>
921	To use HTTP_PROXY and NO_PROXY environment variable, you must set
922	SOAP_USE_PROXY environment variable 'on', too.
923	<pre>
924	bash$ soap_use_proxy=on http_proxy=http://myproxy:8080 ruby ...
925	csh$ env soap_use_proxy=on http_proxy=http://myproxy:8080 ruby ...
926	</pre></li>
927
928	<li>Add SOAP::RPC::Driver#mandatorycharset= and
929	SOAP::WSDLDriver#mandatorycharset= interface to force using
930	charset when parsing response from buggy server such as AWS.</li>
931
932	<li>Support a halfway-typed multi-ref array that Axis dumps.</li>
933
934	<li>Added a interface XSD::Charset.encoding= to control internal
935	encoding scheme. Internal encoding scheme was fixed to 'utf-8'
936	when iconv or uconv was installed. You can set 'euc-jp', etc.
937	to avoid encoding scheme conversion if you know what encoding
938	scheme the server uses.</li>
939	</ul></li>
940
941	<li>Bug fixes;
942	<ul>
943	<li>SOAP::Marshal.unmarshal: raise an exception if parse fails.
944	(returned nil)</li>
945
946	<li>SOAP::WSDLDriver: decode unknown element according to self-defined
947	type even if WSDL was given.</li>
948
949	<li> SOAP::Mapping::Factory#create_empty_object: fix Class#allocate
950	emulation code for ruby/1.6. no effective change under ruby/1.8.</li>
951
952	<li>SOAP::RPC::SOAPMethodResponse: element name of response message
953	could have the name other than 'return'.</li>
954
955	<li>SOAP::RPC::StandaloneServer: add methods 'shutdown' and 'status'
956	as delegates to WEBrick.</li>
957
958	<li>WSDL::SOAP::ClassDefCreator: WSDL/1.1 allows plural fault
959	definition in a operation.</li>
960
961	<li>XSD::Charset.init: use cp932 under emx.
962	Patched by Siena. / SHINAGAWA, Norihide.</li>
963	</ul></li>
964	</ul></dd>
965
966	<dt>1.5.1 - November 2, 2003</dt>
967	<dd>
968	<ul>
969	<li>Features;
970	<ul>
971	<li>Sample updates; Update Amazon Web Service WSDL (v2 -> v3), and update RAA WSDL(0.0.1 -> 0.0.2).
972	<li>Supports ivars of basetype and extending modules marshalling with XML attribute.
973	Using XML attribute to support ruby object dependent information, marshalled object keeps compatibility with SOAP spec.
974	It shows the power of XML, extensibility.<br/>
975	Now I think SOAP marshaller supports all kind of object graph which is supported by Ruby's original marshaller.</li>
976	<li>Better XML pretty printing.
977	<pre>
978	puts SOAPMarshal.dump(Person.new("NaHi", 33))
979
980	=>
981
982	<?xml version="1.0" encoding="utf-8" ?>
983	<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
984	xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
985	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
986	<env:Body>
987	<Person xmlns:n1="http://www.ruby-lang.org/xmlns/ruby/type/custom"
988	xsi:type="n1:Person"
989	env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
990	<age xsi:type="xsd:int">33</age>
991	<name xsi:type="xsd:string">NaHi</name>
992	</Person>
993	</env:Body>
994	</env:Envelope>
995	</pre></li>
996	</ul></li>
997
998	<li>Installation;
999	<ul>
1000	<li>The previous version soap4r/1.5.0 required http-access2 to be installed to build CGI server, but no longer needed fot this purpose now.
1001	You can use almost all features of soap4r without http-access2,
1002	but for actual usage, consider installing http-access2 for speed and
1003	thread-safe SOAP client.</li>
1004	<li>Under ruby/1.8, installer installs lib files to rubylibdir(e.g. /usr/local/lib/ruby/1.8) instead of sitelibdir(e.g. /usr/local/lib/ruby/site_ruby/1.8)</li>
1005	</ul></li>
1006
1007	<li>Bug fixes;
1008	<ul>
1009	<li>Do not introduce XSD constants to toplevel.</li>
1010	<li>'NO_PROXY'/'no_proxy' env var was not supported under net/http. Fixed.</li>
1011	<li>Remove some ruby/1.8 dependent codes. Should work fine under 1.6, too.</li>
1012	<li>XSD::XSDString did not check its value space under $KCODE = 'NONE' env for example where iconv module is not installed.</li>
1013	<li>XSD::XSDFloat, XSD::XSDDouble: add +/- sign explicitly when stringified and embedded into XML instance. Ruby's sprintf may format -0.0 as "0.0" (no minus sign) depending on underlying C sprintf implementation.</li>
1014	</ul></li>
1015	</ul></dd>