diff options
Diffstat (limited to 'cpp/sca/doc/Axis2CWSExtension.html')
| -rw-r--r-- | cpp/sca/doc/Axis2CWSExtension.html | 498 |
1 files changed, 498 insertions, 0 deletions
diff --git a/cpp/sca/doc/Axis2CWSExtension.html b/cpp/sca/doc/Axis2CWSExtension.html new file mode 100644 index 0000000000..17b9676650 --- /dev/null +++ b/cpp/sca/doc/Axis2CWSExtension.html @@ -0,0 +1,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> + |