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
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
|
<!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 Native - Axis2/C Web Services Extension</TITLE>
</HEAD>
<BODY>
<DIV ID="bodyColumn">
<DIV ID="contentBox">
<DIV CLASS="section">
<H1>Tuscany SCA Native - Axis2/C Web Services Extension</H1>
<P>This document describes the installation, deployment and use of the Axis2/C Web Service
support in the Apache Tuscany SCA Native runtime.
</P>
<P>The WS service code is based on <A HREF="http://ws.apache.org/axis2/c">Apache
Axis2/C version 0.96</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="#requirements">System Requirements</A></LI>
<LI><A HREF="#install">Installing the Tuscany SCA Axis2/C Web Services Extension..</A>
<UL>
<LI><A HREF="#linuxbin">..from the binary release on Linux and Mac OS X</A></LI>
<LI><A HREF="#linuxsrc">..from the source release on Linux and Mac OS X</A></LI>
<LI><A HREF="#winbin">..from the binary release on Windows</A></LI>
<LI><A HREF="#winsrc">..from the source release on Windows</A></LI>
</UL></LI>
<LI><A HREF="#deploy">Deploying the Tuscany Web Service support to Axis2/C..</A>
<UL>
<LI><A HREF="#autodeploy">..automatically via scripts</A></LI>
<LI><A HREF="#mandeploy">..manually</A></LI>
</UL></LI>
<LI><A HREF="#deployhttpd">Deploying Axis2/C to the Apache HTTPD server</A></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="requirements"><H2>System Requirements</H2></A>
<P>In order to install and use the Tuscany SCA Axis2/C Web Services Extension there are some
extra requirements in addition to the <A HREF="../GettingStarted.html#requirements">Tuscany
SCA requirements</A>:</P>
<TABLE CLASS="bodyTable">
<TBODY>
<TR CLASS="a">
<TD><B>Software</B></TD>
<TD><B>Download Link</B></TD>
</TR>
<TR CLASS="b">
<TD>Axis2/C version 0.96</TD>
<TD>
<A HREF="http://ws.apache.org/axis2/c/download.cgi"
TARGET="_blank">http://ws.apache.org/axis2/c/download.cgi</A><BR/>
Please download and follow the installation instructions. Ensure you can run
the Axis2/C samples.
</TD>
</TR>
</TBODY>
</TABLE>
</DIV>
<DIV CLASS="section">
<A NAME="install"><H2>Installing the Tuscany SCA Axis2/C Extension</H2></A>
<A NAME="linuxbin"><H3>Getting the Tuscany SCA Axis2/C Extension working with the binary release on Linux and Mac OS X</H3></A>
<OL>
<LI>Ensure the AXIS2C_HOME environment variable is set to the Axis2/C installation</LI>
<LI>Deploy the Axis2/C Web Services extension by following the <A HREF="#deploy">deployment steps</A></LI>
</OL>
<A NAME="linuxsrc"><H3>Getting the Tuscany SCA Axis2/C Extension working with the source release on Linux and Mac OS X</H3></A>
<OL>
<LI>You will need the Tuscany SCA and SDO libraries - follow the instructions
<A HREF="../GettingStarted.html">here</A> to build the SCA libraries and default extensions</LI>
<LI>The following environment variables are required:
<UL>
<LI>TUSCANY_SCACPP=<path to built Tuscany SCA></LI>
<LI>TUSCANY_SDOCPP=<path to installed Tuscany SDO></LI>
<LI>AXIS2C_HOME=<path to Axis2/C installation></LI>
</UL></LI>
<LI>Build the Axis2/C source only with the following command sequence:
<UL>
<LI>cd <tuscany_sca_install_dir></LI>
<LI>./configure --prefix=$TUSCANY_SCACPP --enable-wsbinding --enable-cpp=no</LI>
<LI>make</LI>
<LI>make install</LI>
</UL>
NOTE: If you don't provide a --prefix configure option, it will by default install into
/usr/local/tuscany/sca</LI>
</OL>
<A NAME="winbin"><H3>Getting the Tuscany SCA Axis2/C Extension working with the binary release on Windows</H3></A>
<OL>
<LI>Ensure the AXIS2C_HOME environment variable is set to the Axis2/C installation</LI>
<LI>Deploy the Axis2/C Web Services extension by following the <A HREF="#deploy">deployment steps</A></LI>
</OL>
<A NAME="winsrc"><H3>Getting the Tuscany SCA Axis2/C Extension working with the source release on Windows</H3></A>
<OL>
<LI>Unzip the supplied source zip file</LI>
<LI>The following environment variables are required:
<UL>
<LI>TUSCANY_SCACPP=<path to built Tuscany SCA></LI>
<LI>TUSCANY_SDOCPP=<path to installed Tuscany SDO></LI>
<LI>AXIS2C_HOME=<path to Axis2/C installation></LI>
</UL></LI>
<LI>You must have set up the environment for Microsoft Visual C++ tools. The build command
will call vcvars32 to set the environment. Ensure the directory containing this is on your path.
This will be where you installed the compiler.</LI>
<LI>Build the source:
<UL>
<LI>cd <to where you unzipped the source></LI>
<LI>build</LI>
</UL>
This will build all the projects and put the required output into the 'deploy' directory<BR/><BR/>
Alternatively, open the workspace at <tuscany_sca_install_dir>/projects/tuscany_sca/tuscany_sca.dsw
in Visual Studio 6 or at at <tuscany_sca_install_dir>/projectsvc7/tuscany_sca/tuscany_sca.sln
in Visual Studio 7.1 - you can build projects individually
or build the samples to rebuild all the projects</LI>
</OL>
</DIV>
<DIV CLASS="section">
<A NAME="deploy"><H2>Deploying the Tuscany Web Service support to Axis2/C</H2></A>
<A NAME="autodeploy"><H3>Deploying via scripts</H3></A>
<P>Tuscany provides simple shell scripts to deploy the Web Service support to Axis2/C.
However, the script <STRONG>will overwrite your Axis2/C axis.xml file</STRONG>, so if you
have altered your axis2.xml from the default provided by the Axis2/C 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 Axis2/C on Linux and Mac OS X:
<OL>
<LI>The AXIS2C_HOME environment variable is required:
<UL>
<LI>set AXIS2C_HOME=<path to axis2c version 0.96></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 Axis2/C on Windows:
<OL>
<LI>The AXIS2C_HOME environment variable is required:
<UL>
<LI>export AXIS2C_HOME=<path to axis2c version 0.96></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.bat</LI>
</UL>
</LI>
</OL>
</P>
<A NAME="mandeploy"><H3>Deploying manually</H3></A>
<P>To deploy Tuscany Web Service support to Axis2/C manually, use the following steps:
</P>
<OL>
<LI>
Linux and Mac OS X:
<OL>
<LI>cd <axis2c version 0.96>/services</LI>
<LI>ln -sf <tuscany_sca_install_dir>/extensions/ws/service/services/tuscany</LI>
<LI>cd <axis2c version 0.96>/modules</LI>
<LI>ln -sf <tuscany_sca_install_dir>/extensions/ws/service/modules/tuscany</LI>
</OL>
Windows:
<OL>
<LI>Create a <axis2c version 0.96>\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.96>\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.96>/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="deployhttpd"><H2>Deploying Axis2/C to the Apache HTTPD server</H2></A>
<P>Follow the <A HREF="http://ws.apache.org/axis2/c/docs/installationguide.html#installing-apache2">Axis2/C documentation</A>
to deploy Axis2/C to Apache HTTPD. Also see the <A HREF="../samples/HTTPDBigBank/README.html">HTTPDBigBank</A>
sample, which demonstrates running Axis2/C under Apache HTTPD.</P>
</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/CppCalculator.
</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/CppCalculator/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 Axis2/C 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 Axis2/C lib directory on
your PATH on Windows or the SCA, SDO and Axis2/C lib directories on
your LD_LIBRARY_PATH on Linux and your DYLD_LIBRARY_PATH on Mac OS X.
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.96-win32 </LI>
<LI>set PATH=%PATH%;C:/tuscany_sca/bin;C:/tuscany_sdo/bin;C:/axis2c-bin-0.96-win32/lib</LI>
<LI>set TUSCANY_SCACPP_SYSTEM_ROOT=C:/tuscany_sca/samples/CppCalculator/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 Axis2/C Web Service, via the WS
service you created. See the Axis2/C 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>
|
