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
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<HTML>
<HEAD>
<META CONTENT="text/html; charset=iso-8859-1" HTTP-EQUIV="Content-Type">
<META CONTENT="text/css" HTTP-EQUIV="Content-Style-Type">
<STYLE MEDIA="all" TYPE="text/css">
@import url("css/maven-base.css");
@import url("css/maven-theme.css");
</STYLE>
<LINK HREF="css/maven-theme.css" MEDIA="print" REL="stylesheet"
TYPE="text/css">
<TITLE>Tuscany SCA for C++ - Enabling Axis2C Web Services</TITLE>
</HEAD>
<BODY>
<DIV ID="bodyColumn">
<DIV ID="contentBox">
<DIV CLASS="section">
<H2>Tuscany SCA for C++ - Enabling Axis2C Web Services</H2>
<P>This document describes the deployment and use of the Axis2C Web Service
(binding.ws) service support in the Apache Tuscany SCA C++ runtime.
</P>
<P>The WS service code is based on <A HREF="http://ws.apache.org/axis2/c">Apache
Axis2C version 0.94</A> and allows SCA components to be invoked via Web
Service calls.
</P>
<P>WS service currently supports Document/literal Wrapped style Web Services
only. There are also restrictions about the parameter and return types of the
operations in SCA components that can be exposed as Web Services, see below
for more details.
</P>
<P>See the <A HREF="http://www.osoa.org/display/Main/Service+Component+Architecture+Specifications">SCA
Web Service binding specification</A> for more details about SCA Web
Service support.
</P>
<P>Also, see the <A HREF="../samples/GettingStarted.html">samples</A> for various
demonstrations of the use of the binding.ws service support.
</P>
</DIV>
<DIV CLASS="section">
<H2>Contents</H2>
<OL>
<LI><A HREF="#deploy">Deploying the Tuscany Web Service support to Axis2C..</A>
<UL>
<LI><A HREF="#autodeploy">..automatically via scripts</A></LI>
<LI><A HREF="#mandeploy">..manually</A></LI>
</UL></LI>
<LI><A HREF="#use">Defining an SCA Composite with a WS service</A></LI>
<LI><A HREF="#maptable">XML Schema Type to C++ Type Mapping</A></LI>
<LI><A HREF="#creatingwsdl">Notes on creating WSDL</A></LI>
</OL>
</DIV>
<DIV CLASS="section">
<A NAME="deploy"><H2>Deploying the Tuscany Web Service support to Axis2C</H2></A>
<A NAME="autodeploy"><H3>Deploying via scripts</H3></A>
<P>Tuscany provides simple shell scripts to deploy the Web Service support to Axis2C.
However, the script <STRONG>will overwrite your Axis2C axis.xml file</STRONG>, so if you
have altered your axis2.xml from the default provided by the Axis2C distribution, it is
recommended that you follow the <A HREF="#mandeploy">manual deployment</A> steps
outlined below.
</P>
<P>To automatically deploy Tuscany Web Service support to Axis2C on Linux:
<OL>
<LI>The AXIS2C_HOME environment variable is required:
<UL>
<LI>set AXIS2C_HOME=<path to axis2c version 0.94></LI>
</UL></LI>
<LI>Use the following command sequence to run the deploy script:
<UL>
<LI>cd <tuscany_sca_install_dir>/extensions/ws/service</LI>
<LI>./deploy.sh</LI>
</UL>
</LI>
</OL>
</P>
<P>To automatically deploy Tuscany Web Service support to Axis2C on Windows:
<OL>
<LI>The AXIS2C_HOME environment variable is required:
<UL>
<LI>export AXIS2C_HOME=<path to axis2c version 0.94></LI>
</UL></LI>
<LI>Use the following command sequence to run the deploy script:
<UL>
<LI>cd <tuscany_sca_install_dir>\extensions\ws\service</LI>
<LI>deploy.cmd</LI>
</UL>
</LI>
</OL>
</P>
<A NAME="mandeploy"><H3>Deploying manually</H3></A>
<P>To deploy Tuscany Web Service support to Axis2C manually, use the following steps:
</P>
<OL>
<LI>
Linux:
<OL>
<LI>cd <axis2c version 0.94>/services</LI>
<LI>ln -sf <tuscany_sca_install_dir>/extensions/ws/service/services/tuscany</LI>
<LI>cd <axis2c version 0.94>/modules</LI>
<LI>ln -sf <tuscany_sca_install_dir>/extensions/ws/service/modules/tuscany</LI>
</OL>
Windows:
<OL>
<LI>Create a <axis2c version 0.94>\services\tuscany directory
</LI>
<LI>Copy all the files in <tuscany_sca_install_dir>\extensions\ws\service\services\tuscany
to the directory created above
</LI>
<LI>Create a <axis2c version 0.94>\modules\tuscany directory
</LI>
<LI>Copy all the files in <tuscany_sca_install_dir>\extensions\ws\service\modules\tuscany
to the directory created above
</LI>
</OL>
</LI>
<LI>Edit the <axis2c version 0.94>/axis2.xml file to add a <ref module="tuscany">
element. This will register the above module. E.g.:
<PRE>...
<!-- ================================================= -->
<!-- Global Modules -->
<!-- ================================================= -->
<!-- Comment this to disable Addressing -->
<module ref="addressing"/>
<module ref="tuscany"/>
... </PRE>
</LI>
</OL>
</DIV>
<DIV CLASS="section">
<A NAME="use"><H2>Defining an SCA Composite with a WS service</H2></A>
<P>In this section we will use the Calculator sample as a worked example.
The Calculator code and files can be found at
<tuscany_sca_install_dir>samples/Calculator.
</P>
<P>Pre-requisites:
<UL>
<LI>At least one working component within a composite and solution
composite. The component(s) can be implemented in C++, Ruby or Python.
If this includes C++ components, the SCAGEN generated Proxy and Wrapper
classes and the component class files must have been compiled into a
.dll or .so library. The *.composite and *.componentType files must
also be available and working.
</LI>
</UL>
</P>
<OL>
<LI>Optionally, create the WSDL that defines the interface of your SCA component. See the
table <A HREF="#maptable">XML Schema Type to C++ Type Mapping</A> and
<A HREF="#creatingwsdl">Notes on creating WSDL</A> below
for mapping the parameters and return types of the component operations to XML
schema types in the WSDL. This file will need to be accessible from the component,
so place it in the same directory as the component or in a subdirectory.
<BR/>
See the <tuscany_sca_install_dir>/samples/Calculator/sample.calculator/Calculator.wsdl
file as an example.
<BR/>
If you do not provide a WSDL file describing the service interface then the service will
accept any incoming document/literal wrapped XML request that matches an operation on the
target service (the wrapper element name and types of the sub-elements must match the operation
name and its parameter types). Additionally, if the target component is a Python or Ruby
scripting component, it will accept any parameter type so you can pretty much pass whatever
data you want, as long at the incoming XML request matches to an operation name with the
correct number of parameters on the target service.
</LI>
<LI>Add a service definition to the component .composite file. If you have created a WSDL
definition, set the interface.wsdl interface attribute to the namespace and port name
specified in the WSDL, in the form: "<namespace>#wsdl.interface(<port-name>)".
Link a reference from this service definition to your
component, give the service a name and set the multiplicity if required.
<BR/>
E.g. for the Calculator component, based on the Calculator.wsdl file:
<PRE><service name="CalculatorService">
<interface.wsdl interface="http://sample/calculator#wsdl.interface(Calculator)"/>
<binding.ws/>
<reference>CalculatorComponent/CalculatorService</reference>
</service></PRE>
If the Calculator.wsdl file were not included, the service definition would simply
be as follows:
<PRE><service name="CalculatorService">
<binding.ws/>
<reference>CalculatorComponent/CalculatorService</reference>
</service></PRE>
</LI>
<LI>You are now ready to start the Axis2C HTTP server. Remember you will need to have the
TUSCANY_SCACPP, TUSCANY_SDOCPP and AXIS2C_HOME environment variables set,
as well as the SCA and SDO bin directories and the Axis2C lib directory on
your PATH on Windows or the SCA, SDO and Axis2C lib directories on
your LD_LIBRARY_PATH on Linux. You will also need to set the TUSCANY_SCACPP_SYSTEM_ROOT
and TUSCANY_SCACPP_DEFAULT_COMPONENT environment variables to the
path to your SCA component directory structure and the default component respectively.
E.g. on Windows run the following commands:
<UL>
<LI>set TUSCANY_SCACPP=C:/tuscany_sca </LI>
<LI>set TUSCANY_SDOCPP=C:/tuscany_sdo </LI>
<LI>set AXIS2C_HOME=C:/axis2c-bin-0.94-win32 </LI>
<LI>set PATH=%PATH%;C:/tuscany_sca/bin;C:/tuscany_sdo/bin;C:/axis2c-bin-0.94-win32/lib</LI>
<LI>set TUSCANY_SCACPP_SYSTEM_ROOT=C:/tuscany_sca/samples/Calculator/deploy </LI>
<LI>set TUSCANY_SCACPP_DEFAULT_COMPONENT=sample.calculator.CalculatorComponent </LI>
<LI>cd %AXIS2C_HOME%/bin/ </LI>
<LI>./axis2_http_server.exe </LI>
</UL>
</LI>
<LI>Optionally, enable Tuscany logging by setting the TUSCANY_SCACPP_LOGGING
environment variable with the level you wish to log at (0 for minimal
logging, up to 9 for more detailed logging) and the TUSCANY_SCACPP_LOG
environment variable to define the file to log to (if this is not set,
logging will go to the console). E.g. on Windows run the following
commands:
<UL>
<LI>set TUSCANY_SCACPP_LOGGING=5 </LI>
<LI>set TUSCANY_SCACPP_LOG=C:/tuscany/mylogfile.txt</LI>
</UL>
</LI>
</OL>
<P>Your component should now be exposed as an Axis2C Web Service, via the WS
service you created. See the Axis2C documentation for writing clients to
invoke the Web Service, or you can use any other Web Service client platform
(e.g. <A HREF="http://ws.apache.org/axis2">Axis2 for Java</A>), or you can
invoke your service from another SCA application by using Tuscany's WS
reference support.
</P>
</DIV>
<DIV CLASS="section">
<A name="maptable"><H2>XML Schema Type to C++ Type Mapping</H2></A>
<P>To help define the WSDL that describes the interface of your component, the
table below lists how incoming XML data in Web Service messages is mapped to
C++ types used in the parameters and return types of your component operations.
</P>
<P>This lists the only C++ types that can currently be used on the operations of a
component exposed as a Web Service. For other types, use an SDO DataObject to
wrap the data, and define that wrapping as a complexType in the WSDL. See the
<A HREF="http://www.osoa.org/display/Main/SDO+-+Previously+Published+Specifications">SDO
specifications</A> for the C++ types that SDO supports.
</P>
<TABLE CLASS="bodyTable">
<TBODY>
<TR CLASS="a">
<TD><STRONG>XML Schema Type</STRONG></TD>
<TD><STRONG>C++ Type</STRONG></TD>
</TR>
<TR CLASS="b">
<TD>string</TD>
<TD>std::string</TD>
</TR>
<TR CLASS="a">
<TD>int</TD>
<TD>long</TD>
</TR>
<TR CLASS="b">
<TD>integer</TD>
<TD>long</TD>
</TR>
<TR CLASS="a">
<TD>short</TD>
<TD>short</TD>
</TR>
<TR CLASS="b">
<TD>float</TD>
<TD>float</TD>
</TR>
<TR CLASS="a">
<TD>double</TD>
<TD>long double</TD>
</TR>
<TR CLASS="b">
<TD>boolean</TD>
<TD>bool</TD>
</TR>
<TR CLASS="a">
<TD>hexBinary</TD>
<TD>char*</TD>
</TR>
<TR CLASS="b">
<TD>base64Binary</TD>
<TD>char*</TD>
</TR>
<TR CLASS="a">
<TD>byte</TD>
<TD>char</TD>
</TR>
<TR CLASS="b">
<TD>complexType</TD>
<TD>commonj::sdo::DataObjectPtr</TD>
</TR>
<TR CLASS="a">
<TD>any</TD>
<TD>commonj::sdo::DataObjectPtr with OpenDataObjectType</TD>
</TR>
</TBODY>
</TABLE>
</DIV>
<DIV CLASS="section">
<A name="creatingwsdl"><H2>Notes on creating WSDL</H2></A>
<P>Currently only Document/literal Wrapped style Web Services are supported by
WS EntryPoint, support for RPC style Web Services is planned for future
releases.
</P>
<P>See <A HREF="http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/">this article</A>
for an explanation of Document/literal Wrapped style WSDL and Web Services
</P>
<P>Document/literal Wrapped services require that the operation name is used as
the name of the incoming element that wraps the operation parameters. Additionally,
operation parameter and return messages that are defined in the WSDL must be
XML Schema elements containing a complexType.
</P>
<P>For example, a component operation defined in C++ as:
<PRE>long myOperation(std::string arg1, short arg2, DataObjectPtr arg3);</PRE>
will need to be described in WSDL with messages like:
<PRE><wsdl:message name="myOperationRequestMsg">
<wsdl:part element="tns:myOperation" name="myOperationRequestPart"/>
</wsdl:message>
<wsdl:message name="myOperationResponseMsg">
<wsdl:part element="tns:myOperationResponse" name="myOperationResponsePart"/>
</wsdl:message></PRE>
and will need an XML schema to define the types like:
<PRE><xsd:element name="myOperation">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="arg1" type="xsd:string" minOccurs="1"/>
<xsd:element name="arg2" type="xsd:short" minOccurs="1"/>
<xsd:element name="arg3" minOccurs="1">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="dataObjectFloatData" type="xsd:float"/>
<xsd:element name="dataObjectStringData" type="xsd:string"/>
<xsd:element name="dataObjectIntData" type="xsd:int"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="myOperationResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="result" type="xsd:int" minOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element></PRE>
</DIV>
<DIV CLASS="section">
<A NAME="help"><H2>Getting Help</H2></A>
<P>First place to look is at the Tuscany FAQ at
<A HREF="http://incubator.apache.org/tuscany/faq.html"
TARGET="_blank">http://incubator.apache.org/tuscany/faq.html</A> </P>
<P>Any problem with this release can be reported to the Tuscany
<A HREF="http://incubator.apache.org/tuscany/mail-lists.html"
TARGET="_blank">mailing lists</A> or create a JIRA issue at <A HREF="http://issues.apache.org/jira/browse/Tuscany"
TARGET="_blank">http://issues.apache.org/jira/browse/Tuscany</A>.</P>
</DIV>
</DIV>
</DIV>
</BODY>
</HTML>
|
