Tuscany SCA Native - Axis2/C Web Services Extension

This document describes the installation, deployment and use of the Axis2/C Web Service support in the Apache Tuscany SCA Native runtime.

The WS service code is based on Apache Axis2/C version 0.96 and allows SCA components to be invoked via Web Service calls.

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.

See the SCA Web Service binding specification for more details about SCA Web Service support.

Also, see the samples for various demonstrations of the use of the binding.ws service support.

Contents

  1. System Requirements
  2. Installing the Tuscany SCA Axis2/C Web Services Extension..
  3. Deploying the Tuscany Web Service support to Axis2/C..
  4. Deploying Axis2/C to the Apache HTTPD server
  5. Defining an SCA Composite with a WS service
  6. XML Schema Type to C++ Type Mapping
  7. Notes on creating WSDL

System Requirements

In order to install and use the Tuscany SCA Axis2/C Web Services Extension there are some extra requirements in addition to the Tuscany SCA requirements:

Software Download Link
Axis2/C version 0.96 http://ws.apache.org/axis2/c/download.cgi
Please download and follow the installation instructions. Ensure you can run the Axis2/C samples.

Installing the Tuscany SCA Axis2/C Extension

Getting the Tuscany SCA Axis2/C Extension working with the binary release on Linux and Mac OS X
  1. Ensure the AXIS2C_HOME environment variable is set to the Axis2/C installation
  2. Deploy the Axis2/C Web Services extension by following the deployment steps

Getting the Tuscany SCA Axis2/C Extension working with the source release on Linux and Mac OS X
  1. You will need the Tuscany SCA and SDO libraries - follow the instructions here to build the SCA libraries and default extensions
  2. The following environment variables are required:
    • TUSCANY_SCACPP=<path to built Tuscany SCA>
    • TUSCANY_SDOCPP=<path to installed Tuscany SDO>
    • AXIS2C_HOME=<path to Axis2/C installation>
  3. Build the Axis2/C source only with the following command sequence:
    • cd <tuscany_sca_install_dir>
    • ./configure --prefix=$TUSCANY_SCACPP --enable-wsbinding --enable-cpp=no
    • make
    • make install
    NOTE: If you don't provide a --prefix configure option, it will by default install into /usr/local/tuscany/sca

Getting the Tuscany SCA Axis2/C Extension working with the binary release on Windows
  1. Ensure the AXIS2C_HOME environment variable is set to the Axis2/C installation
  2. Deploy the Axis2/C Web Services extension by following the deployment steps

Getting the Tuscany SCA Axis2/C Extension working with the source release on Windows
  1. Unzip the supplied source zip file
  2. The following environment variables are required:
    • TUSCANY_SCACPP=<path to built Tuscany SCA>
    • TUSCANY_SDOCPP=<path to installed Tuscany SDO>
    • AXIS2C_HOME=<path to Axis2/C installation>
  3. 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.
  4. Build the source:
    • cd <to where you unzipped the source>
    • build
    This will build all the projects and put the required output into the 'deploy' directory

    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

Deploying the Tuscany Web Service support to Axis2/C

Deploying via scripts

Tuscany provides simple shell scripts to deploy the Web Service support to Axis2/C. However, the script will overwrite your Axis2/C axis.xml file, so if you have altered your axis2.xml from the default provided by the Axis2/C distribution, it is recommended that you follow the manual deployment steps outlined below.

To automatically deploy Tuscany Web Service support to Axis2/C on Linux and Mac OS X:

  1. The AXIS2C_HOME environment variable is required:
    • set AXIS2C_HOME=<path to axis2c version 0.96>
  2. Use the following command sequence to run the deploy script:
    • cd <tuscany_sca_install_dir>/extensions/ws/service
    • ./deploy.sh

To automatically deploy Tuscany Web Service support to Axis2/C on Windows:

  1. The AXIS2C_HOME environment variable is required:
    • export AXIS2C_HOME=<path to axis2c version 0.96>
  2. Use the following command sequence to run the deploy script:
    • cd <tuscany_sca_install_dir>\extensions\ws\service
    • deploy.bat

Deploying manually

To deploy Tuscany Web Service support to Axis2/C manually, use the following steps:

  1. Linux and Mac OS X:
    1. cd <axis2c version 0.96>/services
    2. ln -sf <tuscany_sca_install_dir>/extensions/ws/service/services/tuscany
    3. cd <axis2c version 0.96>/modules
    4. ln -sf <tuscany_sca_install_dir>/extensions/ws/service/modules/tuscany
    Windows:
    1. Create a <axis2c version 0.96>\services\tuscany directory
    2. Copy all the files in <tuscany_sca_install_dir>\extensions\ws\service\services\tuscany to the directory created above
    3. Create a <axis2c version 0.96>\modules\tuscany directory
    4. Copy all the files in <tuscany_sca_install_dir>\extensions\ws\service\modules\tuscany to the directory created above
  2. Edit the <axis2c version 0.96>/axis2.xml file to add a <ref module="tuscany"> element. This will register the above module. E.g.: 
    ...
    <!-- ================================================= -->
    <!-- Global Modules  -->
    <!-- ================================================= -->
    <!-- Comment this to disable Addressing -->
    <module ref="addressing"/>

    <module ref="tuscany"/>

...

Deploying Axis2/C to the Apache HTTPD server

Follow the Axis2/C documentation to deploy Axis2/C to Apache HTTPD. Also see the HTTPDBigBank sample, which demonstrates running Axis2/C under Apache HTTPD.

Defining an SCA Composite with a WS service

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.

Pre-requisites:

  • 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.

  1. Optionally, create the WSDL that defines the interface of your SCA component. See the table XML Schema Type to C++ Type Mapping and Notes on creating WSDL 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.
    See the <tuscany_sca_install_dir>/samples/CppCalculator/sample.calculator/Calculator.wsdl file as an example.
    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.
  2. 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.
    E.g. for the Calculator component, based on the Calculator.wsdl file: 
    <service name="CalculatorService">
    <interface.wsdl interface="http://sample/calculator#wsdl.interface(Calculator)"/>
    <binding.ws/>
    <reference>CalculatorComponent/CalculatorService</reference>
</service>
    If the Calculator.wsdl file were not included, the service definition would simply be as follows: 
    <service name="CalculatorService">
    <binding.ws/>
    <reference>CalculatorComponent/CalculatorService</reference>
</service>
  3. 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:
    • set TUSCANY_SCACPP=C:/tuscany_sca
    • set TUSCANY_SDOCPP=C:/tuscany_sdo
    • set AXIS2C_HOME=C:/axis2c-bin-0.96-win32
    • set PATH=%PATH%;C:/tuscany_sca/bin;C:/tuscany_sdo/bin;C:/axis2c-bin-0.96-win32/lib
    • set TUSCANY_SCACPP_SYSTEM_ROOT=C:/tuscany_sca/samples/CppCalculator/deploy
    • set TUSCANY_SCACPP_DEFAULT_COMPONENT=sample.calculator.CalculatorComponent
    • cd %AXIS2C_HOME%/bin/
    • ./axis2_http_server.exe
  4. 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:
    • set TUSCANY_SCACPP_LOGGING=5
    • set TUSCANY_SCACPP_LOG=C:/tuscany/mylogfile.txt

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. Axis2 for Java), or you can invoke your service from another SCA application by using Tuscany's WS reference support.

XML Schema Type to C++ Type Mapping

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.

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 SDO specifications for the C++ types that SDO supports.

XML Schema Type C++ Type
string std::string
int long
integer long
short short
float float
double long double
boolean bool
hexBinary char*
base64Binary char*
byte char
complexType commonj::sdo::DataObjectPtr
any commonj::sdo::DataObjectPtr with OpenDataObjectType

Notes on creating WSDL

Currently only Document/literal Wrapped style Web Services are supported by WS EntryPoint, support for RPC style Web Services is planned for future releases.

See this article for an explanation of Document/literal Wrapped style WSDL and Web Services

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.

For example, a component operation defined in C++ as: 

long myOperation(std::string arg1, short arg2, DataObjectPtr arg3);
will need to be described in WSDL with messages like: 
<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>
and will need an XML schema to define the types like: 
<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>

Getting Help

First place to look is at the Tuscany FAQ at http://incubator.apache.org/tuscany/faq.html

Any problem with this release can be reported to the Tuscany mailing lists or create a JIRA issue at http://issues.apache.org/jira/browse/Tuscany.