diff options
Diffstat (limited to 'tags/cpp-0.1.incubating-M1-RC3/sca/doc/CreatingSCACPPComponents.txt')
| -rw-r--r-- | tags/cpp-0.1.incubating-M1-RC3/sca/doc/CreatingSCACPPComponents.txt | 281 |
1 files changed, 0 insertions, 281 deletions
diff --git a/tags/cpp-0.1.incubating-M1-RC3/sca/doc/CreatingSCACPPComponents.txt b/tags/cpp-0.1.incubating-M1-RC3/sca/doc/CreatingSCACPPComponents.txt deleted file mode 100644 index 17f6430b79..0000000000 --- a/tags/cpp-0.1.incubating-M1-RC3/sca/doc/CreatingSCACPPComponents.txt +++ /dev/null @@ -1,281 +0,0 @@ -Creating SCA Components in Tuscany SCA C++ -========================================== - -This document describes how to create and run SCA components in Tuscany SCA C++ -milestone release 1. - - -Creating and deploying an SCA C++ Component -=========================================== - -Each SCA C++ component needs: - o A service header file that defines the operations that can be invoked on the - component - o An implementation header file that defines the implementation and extends - the service header file - o A C++ implementation of the service that implements the operations defined - in the service header file - o Proxy and wrapper header and implementation files generated by the Tuscany - C++ SCAGEN tool - o A component definition in the module sca.module file - o A service definition in a .componentType file - o A module component definition in a sca.subsystem file - - -In this section we will use the Calculator sample as a worked example. -The Calculator code and files can be found at samples/Calculator and has been -developed further than the details specified below. In the interests of -readability, the example used below takes the simplest path. - - -1. Create the service header file that defines the operations your component - will implement. E.g. Calculator.h contains the following: - -#ifndef CALCULATOR_H -#define CALCULATOR_H -class Calculator -{ -public: - virtual float add(float arg1, float arg2) = 0; - virtual float sub(float arg1, float arg2) = 0; - virtual float mul(float arg1, float arg2) = 0; - virtual float div(float arg1, float arg2) = 0; -}; - -#endif - - -2. Create the implementation header file that extends the service header file. - E.g. CalculatorImpl.h contains the following: - -#ifndef CALCULATORIMPL_H -#define CALCULATORIMPL_H - -#include "Calculator.h" - -class CalculatorImpl : public Calculator -{ -public: - CalculatorImpl(); - virtual ~CalculatorImpl(); - - // Calculator interface - virtual float add(float arg1, float arg2); - virtual float sub(float arg1, float arg2); - virtual float mul(float arg1, float arg2); - virtual float div(float arg1, float arg2); -}; - -#endif - - -3. Create the implementation for the component based on the implementation - header file. E.g. CalculatorImpl.cpp contains the following code: - -#include "CalculatorImpl.h" -#include <stdio.h> - -CalculatorImpl::CalculatorImpl() -{ -} - -CalculatorImpl::~CalculatorImpl() -{ -} - -// Calculator interface -float CalculatorImpl::add(float arg1, float arg2) -{ - float result = arg1 + arg2; - - printf("CalculatorImpl::add %f + %f = %f\n", arg1, arg2, result); - return result; -} - -float CalculatorImpl::sub(float arg1, float arg2) -{ - float result = arg1 - arg2; - printf("CalculatorImpl::sub %f - %f = %f\n", arg1, arg2, result); - return result; -} - -float CalculatorImpl::div(float arg1, float arg2) -{ - float result = arg1 / arg2; - printf("CalculatorImpl::div %f / %f = %f\n", arg1, arg2, result); - return result; -} - -float CalculatorImpl::mul(float arg1, float arg2) -{ - float result = arg1 * arg2; - printf("CalculatorImpl::mul %f * %f = %f\n", arg1, arg2, result); - return result; -} - - -4. Create the componentType file for your component to define the service that - your component provides. The file must be named after your implementation - class and specifies the name of the service and the service header file - (which describes the service operations). E.g. CalculatorImpl.componentType - contains the following XML: - -<?xml version="1.0" encoding="ASCII"?> -<componentType xmlns="http://www.osoa.org/xmlns/sca/0.9" - xmlns:xs="http://www.w3.org/2001/XMLSchema"> - - <service name="CalculatorService"> - <interface.cpp header="Calculator.h"/> - </service> -</componentType> - - -5. Create the sca.module file for your module and define your component within - it. The component definition specifies the implementation library to use (a - .dll file on Windows and a .so file on Linux) and the implementation header - file (which describes the implementation class). Component properties and - references to other services can also be specified here. E.g. the - Calculator sca.module file contains the following XML: - -<?xml version="1.0" encoding="ASCII"?> -<module xmlns="http://www.osoa.org/xmlns/sca/0.9" - xmlns:v="http://www.osoa.org/xmlns/sca/values/0.9" - name="CalculatorModule"> - - <!-- The Calculator component --> - <component name="CalculatorServiceComponent"> - <implementation.cpp dll="Calculator.dll" header="CalculatorImpl.h"/> - <properties></properties> - <references></references> - </component> -</module> - - -6. Generate the proxy and wrapper classes and header files using the SCAGEN - tool. These classes are used by the Tuscany SCA C++ runtime to enable - service implementations to be invoked from a client or another component. - Run the SCAGEN tool, specifying the directory where your header files, - sca.module and componentType file are and the directory where you - want the generated files to be placed. E.g. on Windows, the - following command is run from the directory where Tuscany SCA is deployed: - -bin/scagen.cmd -dir samples/Calculator/CalculatorModule -output samples/Calculator/CalculatorModule - - which produces the following files: - -CalculatorImpl_CalculatorService_Proxy.h -CalculatorImpl_CalculatorService_Proxy.cpp -CalculatorImpl_CalculatorService_Wrapper.h -CalculatorImpl_CalculatorService_Wrapper.cpp - - -7. Compile and link the code that has been written and generated. This will - produce a .dll or .so library file. The name should match the library name - specified in the sca.module file. - - -8. Create the sca.subsystem file and define your module component within it. - The module component definition should specify the service name used in the - componentType file and the module name used in the sca.module file. E.g. - the Calculator sca.subsystem file contains the following XML: - -<?xml version="1.0" encoding="ASCII"?> -<subsystem xmlns="http://www.osoa.org/xmlns/sca/0.9" - name="CalculatorSubsystem"> - - <moduleComponent name="CalculatorService" module="CalculatorModule"/> -</subsystem> - - -9. Deploy the various files into the SCA directory structure, as follows: - -<deploy_root>/modules/ModuleName/ServiceHeader.h -<deploy_root>/modules/ModuleName/ImplementationHeader.h -<deploy_root>/modules/ModuleName/sca.module -<deploy_root>/modules/ModuleName/Implementation.componentType -<deploy_root>/modules/ModuleName/Implementation.dll (or .so on Linux) -<deploy_root>/subsystems/SubsystemName/sca.subsystem - - E.g. for the Calculator sample the structure is: - -samples/Calculator/deploy/modules/CalculatorModule/Calculator.h -samples/Calculator/deploy/modules/CalculatorModule/CalculatorImpl.h -samples/Calculator/deploy/modules/CalculatorModule/sca.module -samples/Calculator/deploy/modules/CalculatorModule/CalculatorImpl.componentType -samples/Calculator/deploy/modules/CalculatorModule/Calculator.dll -samples/Calculator/deploy/subsystems/CalculatorSubsystem/sca.subsystem - - -10. Your component, module and subsystem are now ready to be invoked. Create a - client that will call the service. E.g. the Calculator client (in the - Calc.cpp file) contains code similar to the following: - -try -{ - // Define and start the Tuscany runtime: - // Set the system root path that contains the SCA directory structure, set - // the default module component that will be used based on the format - // <SubsystemName>/<ModuleComponentName> and then start the runtime - TuscanyRuntime rt; - rt.setSystemRoot("C:/tuscany_sca/samples/Calculator/deploy"); - rt.setDefaultModuleComponent("CalculatorSubsystem/CalculatorService"); - rt.start(); - - - // Locate the service - ModuleContext myContext = ModuleContext::getCurrent(); - Calculator *calcService = (Calculator*) myContext.locateService("CalculatorServiceComponent"); - if (calcService == 0) - { - cout << "MyCalculatorClient.exe: Unable to find Calculator service" << endl; - } - else - { - result = calcService->add(arg1, arg2); - cout << "Calculator: add(" << arg1 << "," << arg2 << ") = " << result << endl; - } -} -catch (ServiceRuntimeException& ex) -{ - cout << "MyCalculatorClient.exe: Error whilst starting or invoking Tuscany: " << - ex.getMessageText() << endl; -} - - -11. Compile, link and run the client that has been created. You should - (hopefully!) see your component invoked. 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 (or LD_LIBRARY_PATH on Linux). 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.92-win32 -set PATH=%PATH%;C:/tuscany_sca/bin;C:/tuscany_sdo/bin;C:/axis2c-bin-0.92-win32/lib -./MyCalculatorClient.exe - - -12. 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 - - -Further Steps -------------- - -The Calculator sample has been developed further than the details specified -above. In particular, it demonstrates how two services can be wired together -such that one references and invokes the other. It also demonstrates how to -expose the Calculator component service as an Axis2C Web Service. See the -WSEntrypoint.txt document for more details on exposing components as Web -Services. - - - |