diff options
Diffstat (limited to 'sca-cpp/tags/cpp-1.0-incubating-M2-final/sca/doc/CPPComponents.html')
-rw-r--r-- | sca-cpp/tags/cpp-1.0-incubating-M2-final/sca/doc/CPPComponents.html | 333 |
1 files changed, 333 insertions, 0 deletions
diff --git a/sca-cpp/tags/cpp-1.0-incubating-M2-final/sca/doc/CPPComponents.html b/sca-cpp/tags/cpp-1.0-incubating-M2-final/sca/doc/CPPComponents.html new file mode 100644 index 0000000000..4994d4c610 --- /dev/null +++ b/sca-cpp/tags/cpp-1.0-incubating-M2-final/sca/doc/CPPComponents.html @@ -0,0 +1,333 @@ + +<!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++ - Creating C++ SCA Components</TITLE> +</HEAD> + +<BODY> +<DIV ID="bodyColumn"> + <DIV ID="contentBox"> + <DIV CLASS="section"> + <H2>Tuscany SCA for C++ - Creating C++ SCA Components</H2> + + <P>This document describes how to create and run SCA components in Tuscany SCA C++ + milestone release 2. + </P> + <P>See the <A HREF="http://www.osoa.org/display/Main/Service+Component+Architecture+Specifications">SCA + C++ Client and Implementation specification</A> for more details about the SCA C++ + programming model. + </P> + <P>See <A HREF="../samples/Calculator/README.html">Calculator</A> or + <A HREF="../samples/BigBank/README.html">BigBank</A> for samples that + demonstrate the use of C++ components + </P> + </DIV> + <DIV CLASS="section"> + <H2>Creating and deploying an SCA C++ Component</H2> + <P>Each SCA C++ component needs: + </P> + <UL> + <LI>A service header file that defines the operations that can be invoked on the + component + </LI> + <LI>An implementation header file that defines the implementation and extends + the service header file + </LI> + <LI>A C++ implementation of the service that implements the operations defined + in the service header file + </LI> + <LI>Proxy and wrapper header and implementation files generated by the Tuscany + C++ SCAGEN tool + </LI> + <LI>A service definition in a .componentType file + </LI> + <LI>An SCDL component definition within an SCDL composite file. Usually this + composite file will contain multiple components configured and assembled together. + </LI> + </UL> + <P>Once these items are in place for each component in your composite, you will need to + deploy this composite to your SCA system. In this release we are + using the SCA recursive composition model to do this. You simply create another + SCDL component definition in a separate composite file that will represent the composite + you created above in the SCA system. Follow the steps below to see each of these items + being created and used. + </P> + <P>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. + </P> + <OL> + <LI>Create the service header file that defines the operations your component + will implement. E.g. Calculator.h contains the following:<BR/> + <PRE>#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</PRE> + </LI> + <LI>Create the implementation header file that extends the service header file. + E.g. CalculatorImpl.h contains the following:<BR/> + <PRE>#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</PRE> + </LI> + <LI>Create the implementation for the component based on the implementation + header file. E.g. CalculatorImpl.cpp contains the following code:<BR/> + <PRE>#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; +}</PRE> + </LI> + <LI>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:<BR/> + <PRE><componentType xmlns="http://www.osoa.org/xmlns/sca/1.0"> + + <service name="CalculatorService"> + <interface.cpp header="Calculator.h"/> + </service> + +</componentType></PRE> + </LI> + <LI>Create a sample.calculator.composite file for your composite 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 sample.calculator.composite file contains the following XML:<BR/> + <PRE><composite xmlns="http://www.osoa.org/xmlns/sca/1.0" + name="sample.calculator"> + + <component name="CalculatorComponent"> + <implementation.cpp library="Calculator" header="CalculatorImpl.h"/> + </component> + +</composite></PRE> + </LI> + <LI>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.composite 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:<BR/> + <PRE>./bin/scagen.cmd -dir ./samples/Calculator/sample.calculator -output ./samples/Calculator/sample.calculator</PRE> + which produces the following files: + <UL> + <LI>CalculatorImpl_CalculatorService_Proxy.h</LI> + <LI>CalculatorImpl_CalculatorService_Proxy.cpp</LI> + <LI>CalculatorImpl_CalculatorService_Wrapper.h</LI> + <LI>CalculatorImpl_CalculatorService_Wrapper.cpp</LI> + </UL> + </LI> + <LI>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 sample.calculator.composite file. + </LI> + <LI>Create the sample.calculator.solution.composite file and define the Calculator composite + as a component within it. This is used to include the Calculator composite in the SCA system + and should specify the composite name used in the sample.calculator.composite file. + E.g. the Calculator sample.calculator.solution.composite + file contains the following XML:<BR/> + <PRE><composite xmlns="http://www.osoa.org/xmlns/sca/1.0" + name="sample.calculator.solution"> + + <component name="sample.calculator.CalculatorComponent"> + <implementation.composite name="sample.calculator" /> + </component> + +</composite></PRE> + </LI> + <LI>Deploy the various files into the SCA directory structure, as follows: + <UL> + <LI><deploy_root>/CompositeName/CompositeName.composite </LI> + <LI><deploy_root>/CompositeName/Implementation.componentType </LI> + <LI><deploy_root>/CompositeName/Implementation.dll (or .so on Linux) </LI> + <LI><deploy_root>/SolutionName.composite </LI> + </UL> + E.g. for the Calculator sample the structure is: + <UL> + <LI>samples/Calculator/deploy/sample.calculator/Calculator.h </LI> + <LI>samples/Calculator/deploy/sample.calculator/CalculatorImpl.h </LI> + <LI>samples/Calculator/deploy/sample.calculator/sample.calculator.composite </LI> + <LI>samples/Calculator/deploy/sample.calculator/CalculatorImpl.componentType</LI> + <LI>samples/Calculator/deploy/sample.calculator/Calculator.dll </LI> + <LI>samples/Calculator/deploy/sample.calculator.solution.composite</LI> + </UL> + </LI> + <LI>Your component, composite and subsystem are now ready to be invoked. Create a + client that will call the service. E.g. the Calculator client (in the + CalculatorClient.cpp file) contains code similar to the following:<BR/> + <PRE>try +{ + // Locate the service + CompositeContext myContext = CompositeContext::getCurrent(); + Calculator *calcService = (Calculator*) myContext.locateService("CalculatorComponent/CalculatorService"); + if (calcService == 0) + { + cout << "calculator_client: Unable to find Calculator service" << endl; + } + else + { + float result = calcService->add(arg1, arg2); + cout << "calculator_client add(" << arg1 << "," << arg2 << ") = " << result << endl; + } +} +catch (ServiceRuntimeException& ex) +{ + cout << "calculator_client: Error whilst invoking Tuscany: " << + ex.getMessageText() << endl; +} +</PRE> + </LI> + <LI>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 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. + TUSCANY_SCACPP_SYSTEM_ROOT is the directory where the SCA runtime will look for any + .composite files and TUSCANY_SCACPP_DEFAULT_COMPONENT is the name of the base component + to be used by SCA clients or containers when finding services - this component must be + an instance of a composite (i.e. contain an <implementation.composite> element). + <BR/> + 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>./calculator_client.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>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. + </P> + </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> + |