1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
<title>Interoperability with Other SOAP Implementations</title>
</head>
<body bgcolor="#FFFFFF">
<h2 align="center">Interoperability with Other SOAP
Implementations</h2>
<p align="left">Interoperability was one of the main reasons for
creating SOAP in the first place. However, as with any non-trivial
specification, the SOAP specification leaves several items up to
interpretation. As a result (and also due to simply non-conforming
implementations) a SOAP envelope generated by one SOAP
implementation may not be properly understood by another
implementation. </p>
<p align="left">There is an active effort to improve the
interoperability of various SOAP implementations being driven by
folks in the <a href="http://groups.yahoo.com/group/soapbuilders"
target="_top">"SOAP Builders" mailing list</a>. Some of
the issues / solutions described here arose / found by Apache
SOAPers active in that effort (including Sam Ruby, Dug Davis and
Glen Daniels).</p>
<p align="left">If you would like to read more about interop
problems, <a
href="http://msdn.microsoft.com/xml/general/soapinteropbkgnd.asp"
target="_top">see the article by Keith Ballinger on MSDN</a>. In
that article Keith indentifies 3 types of common interop problems:
transport problems, XML problems and SOAP problems. This document
explains how you can configure and improve the interoperability
of Apache SOAP with other SOAP implementations for each of the 3
types of problems. It is important to note that interoperability
testing is an on-going task and that there are bound to be many
other issues that come up in the future.</p>
<h3 align="left">Transport Problems</h3>
<p align="left">The difficulty arises primarily with the "SOAPAction"
header that SOAP uses. The value of the SOAPAction header is
allowed to be null (that is, no value is specified), the empty
string ("") - which means that no "intent" is
specified, or an arbitrary quoted string. Apache SOAP client-side
APIs have no difficulty generating any of these SOAPAction values.
As such we do not believe there are any transport level
interoperability problems with Apache SOAP.</p>
<p align="left">Another common use of SOAPAction is as the
mechanism to route or dispatch the incoming SOAP envelope to the
target code that processes it. Apache SOAP does not support that
- dispatching is done currently based on the namespace URI of the
first child element of the <SOAP:Body> element only. That
can potentially cause interop problems as SOAP does not preclude
unnamespaced body entries. If an Apache SOAP user wishes to
implement a service that must receive and process unnamespaced
body entries, then currently there is no built-in mechanism to
route those requests. It would require some (relatively small)
modifications to the routing infrastructure to enable routing
based on SOAPAction.</p>
<h3 align="left">XML Problems</h3>
<p align="left">There are several XML problems that may occur - <a
href="http://msdn.microsoft.com/xml/general/soapinteropbkgnd.asp"
target="_top">Keith's article</a> identifies one which causes
difficulties for Apache SOAP: the presence of a Byte Order Mark (BOM)
for UTF-8 encoded SOAP requests. If using Apache Xerces, we
believe that Apache SOAP will fail to read proper SOAP requests
encoded in UTF-8 if they also include a BOM. While legal to have
the BOM for UTF-8 encoded messages, it is not required to do so.
The only known workaround at this time is to not send the BOM.
Apache SOAP always sends SOAP envelopes using UTF-8 encoding
currently and hence does not generate the BOM. While there are no
known solutions for this problem when using Apache Xerces, it is
unknown whether using an alternate JAXP enabled parser eliminates
this problem.</p>
<p align="left">The second type of XML problems are related to
XML Schema support. The problem comes with the fact that there
are actually three versions of XML Schema in use today: the
version with a 1999 URI which was current when the SOAP v1.1
specification first came out in April 2000, the version with a
2000 URI reflecting a "nearly done" version and the
recommended specification with a 2001 URI which became final in
May 2001. Apache SOAP currently behaves as follows:</p>
<ul>
<li><p align="left">Built-in serializers for the Java types corresponding
to various XML Schema simple types will by
default indicate the resulting type using
XML Schema from the 2001 namespace. If it
is desired to use one of the other schema
namespaces in the SOAP envelopes generated
by Apache SOAP, then one has to edit org/apache/soap/Constants.java
and change the values of the constants NS_URI_CURRENT_SCHEMA_XSI
and NS_URI_CURRENT_SCHEMA_XSD to the selected
ones (indicated right before these constants).
Once built, the resulting system will generate
SOAP envelopes using the desired target namespace.<br>
</p>
</li>
<li><p align="left">Apache SOAP will correctly deserialize
SOAP envelopes containing XML Schema simple types from
any of the three schema namespaces. That is, an envelope
containing parameters typed using any combination of
schema URIs will be correctly recognized and mapped to
the appropriate Java object.<br>
</p>
</li>
<li><p align="left">If the default behavior of a serializer
or deserializer is not satisfactory, the user can always
replace the default behavior by<a href="serializer.html">
implementing a new serializer/deserializer</a> and
registering it as the serializer/deserializer for the
desired types.</p>
</li>
</ul>
<p align="left">We believe that the current architecture of
Apache SOAP offers the best possible compromise between
flexibility and rigidity: serialize any given way and deserialize
all possible ways.</p>
<h3 align="left">SOAP Problems</h3>
<p align="left"><strong>Depending on xsi:type.</strong> The most
common interop problem that Apache SOAP has had previously is
related to the requirement for every SOAP (RPC) envelope read by
Apache SOAP to be self-describing in terms of types. That is,
Apache SOAP does not (by default) function without every typed
value being explicitly typed in the envelope using the xsi:type
attribute (see the XML Schema specifications for details). All
SOAP envelopes generated by Apache SOAP will always have all the
type information, however, other SOAP implementations do not (and
are not required to) do so. Hence the interoperability problem.</p>
<p align="left">The correct solution to this problem is for the
SOAP runtime to be aware of the service description of the
service of which the SOAP envelope is a request, say in <a
href="http://www.w3.org/TR/wsdl">WSDL</a> form. Apache SOAP is
not WSDL aware and is unlikely to become so. </p>
<p align="left">As of v2.1, Apache SOAP has had a workaround for
this problem. The basic problem is that someone has to tell the
SOAP engine the type of each parameter of a SOAP RPC call so that
the SOAP engine can deserializer the parameter. The workaround
allows one to use the element name of the parameter as the schema
type and to associate a Java type to map that to. An example will
make the solution clear. Consider the following SOAP envelope
representing an RPC call:</p>
<blockquote>
<div align="left"><pre><SOAP:Envelope xmlns:SOAP="soap-uri">
<SOAP:Body SOAP:encodingStyle="soap-enc-uri">
<ns1:foo xmlns:ns1="ns1-uri">
<arg1>.. value of arg1 ..</arg1>
<x:arg2 xmlns:x="x-uri">.. value of arg2 ..</arg2>
</ns1:foo>
</SOAP:Body>
<SOAP:Envelope></pre>
</div>
</blockquote>
<p align="left">The problem is that Apache SOAP will not be able
to deserialize <arg1>...</arg1> and <x:arg2>...</x:arg2>
to appropriate Java objects without help. When an xsi:type
attribute indicating the type of <arg1> or <x:arg2>
is not found, Apache SOAP uses the name of the parameter (arg1 or
x:arg2, in this case) with a namspace URI of "" for
unqualified names as the type. Thus, in the above example, it
would search for a deserializer to deserialize schema types {""}arg1
and {"x-uri"}arg2 (where the string within the braces
represents the namespace URI of the element. All the user needs
to do to is tell Apache SOAP what the deserializer is for each of
these types.</p>
<p align="left">Serializers for types are specified via the
deployment descriptor for the server side and by invoking the
appropriate API call. If one wanted to allow an Apache SOAP
server to receive the above envelope and decode as discussed
above, the deployment descriptor would need to have the following
type mappings:</p>
<blockquote>
<div align="left"><pre><isd:map encodingStyle="soap-enc-uri"
xmlns:z="" qname="z:arg"
xml2JavaClassName="name-of-deserializer-class"/></pre>
</div><div align="left"><pre><isd:map encodingStyle="soap-enc-uri"
xmlns:x="x-uri" qname="x:arg"
xml2JavaClassName="name-of-deserializer-class"/></pre>
</div>
</blockquote>
<p align="left">If one wanted to allow an Apache SOAP client to
receive the above envelope (in response to some call) and decode
as discussed above, the client-side code would need to do the
following: </p>
<blockquote>
<div align="left"><pre>SOAPMappingRegistry smr = new SOAPMappingRegistry ();
Deserializer sd1 = new appropriate-deserializer ();
smr.mapTypes (Constants.NS_URI_SOAP_ENC,
new QName ("", "arg1"), null, null, sd1);
Deserializer sd2 = new appropriate-deserializer ();
smr.mapTypes (Constants.NS_URI_SOAP_ENC,
new QName ("x-uri", "arg2"), null, null, sd2);</pre>
</div>
</blockquote>
<p align="left">The "guidgen" sample shows an instace
of the latter.</p>
<p align="left">While the approach in Apache SOAP allows one to
work around the lack of WSDL support in most cases, there are
cases where it still is not sufficient. Notably, if the name of a
parameter coincides with another name within that parameter or
elsewhere, one cannot use the name as a key to the type. That is,
there is an implicit assumtion tha tthe names will be unique. </p>
<p align="left">Note that the org.apache.soap.encoding.soapenc.BeanSerializer
<em>cannot</em> be used in any of the above. The reason is that
the bean serializer determines the Java type to produce by
querying for the Java type. In the above registrations the Java
type is indicated as null to prevent the type mapping registry
from registering this deserializer as the default one for Java
types. Thus the indicated deserializers must know (intrinsically)
the type of Java object it is going to produce. There are
deserializers for all the built-in types in the org.apache.soap.encoding.soapenc
package to assist users in using this feature.</p>
<p align="left"><strong>Not understanding mustUnderstand headers.</strong>
Apache SOAP currently does not implement the "mustUnderstand"
header concept of <a href="http://www.w3.org/TR/SOAP"
target="_top">SOAP</a>. This leads to potential interop
difficulties as Apache SOAP may ignore unignorable things. The
workaround Apache SOAP offers is the ability to tell the runtime,
on a per-service basis, for RPC services only, whether to fault
if any mustUnderstand headers are seen. This is available via an <a
href="deploy.html">attribute in the deployment descriptor</a>.
The default value of the "checkMustUnderstands"
attribute is false, which means no must understand checks will be
done at all. Good citizen SOAP services should set that to true
to tell the runtime to check for mustUnderstand attributes on
headers.</p>
<p align="left"><strong>Accessing headers.</strong> The default
RPC provider in Apache SOAP does not provide access to any
headers in the SOAP envelope to the actual service implementation.
If one needs access to this, the workaround is to <a
href="provider.html">write your own provider</a> that aceesses
the headers and then processes the body (possibly by delegating
to other providers).</p>
<p align="left"><strong>Return parameters.</strong> SOAP RPC also
has the notion of return parameters: responses carrying more than
one "return" value. Apache SOAP's default RPC service
provicer does not support such return parameters as those are
beyond the scope of Java (which has only a single return value).
Again, the workaround here is to <a href="provider.html">write
your own provider</a> that allows the service implementation to
not only set a return value, but any number of return "values."</p>
<h3 align="left">Interoperability Testing</h3>
<p align="left">As mentioned earlier, the <a
href="http://groups.yahoo.com/group/soapbuilders" target="_top">SOAP
Builders</a> forum is leading the charge on interoperability
testing. There are several sites that are documenting various
parts of the work:</p>
<ul>
<li><p align="left"><a href="http://www.xmethods.net/ilab/"
target="_top">http://www.xmethods.net/ilab/</a></p>
</li>
<li><p align="left"><a href="http://www.mssoapinterop.org/"
target="_top">http://www.mssoapinterop.org/</a></p>
</li>
</ul>
<p>The "bidybuy" sample in the Apache SOAP v2.2 release
is an implementation of the "Bid Buy" test developed by
the SOAP Builders forum. It provides a fairly comprehensive
example of implementing a non-trivial interoperable Web service
and service client.</p>
<P>Last updated 6/28/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
</html>
|
