diff options
Diffstat (limited to 'sca-cpp/tags/cpp-stable-20060304/sca/tools/scagen/src/org/apache/tuscany/sca/cpp/tools/services/package.html')
| -rw-r--r-- | sca-cpp/tags/cpp-stable-20060304/sca/tools/scagen/src/org/apache/tuscany/sca/cpp/tools/services/package.html | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/sca-cpp/tags/cpp-stable-20060304/sca/tools/scagen/src/org/apache/tuscany/sca/cpp/tools/services/package.html b/sca-cpp/tags/cpp-stable-20060304/sca/tools/scagen/src/org/apache/tuscany/sca/cpp/tools/services/package.html new file mode 100644 index 0000000000..316e4cd56e --- /dev/null +++ b/sca-cpp/tags/cpp-stable-20060304/sca/tools/scagen/src/org/apache/tuscany/sca/cpp/tools/services/package.html @@ -0,0 +1,140 @@ +<html> + +<head> +<title>Design documentation for org\apache\tuscany\sca\cpp\tools\services</title> +</head> + +<body lang=EN-GB> + +<div class=Section1> + +<h1>Overview</h1> + + + +<p>This package contains classes that generate C++ wrappers and +proxies for C++ implementations of SCA services. </p> + +<h2>What the package does</h2> + +<p>The Scagen class main method will take in an input and +output directory name. The input directory is taken to be the SCA module root +directory. The tool will generate the wrapper and proxy headers and methods +bodies in the output directory. </p> + +<p>These proxies and wrappers enable the SCA for C++ runtime to +act as a conduit for SCA C++ calls in a type free manner. Client code can call +the type specific functions that are in the generated proxy classes. The call +is marshalled into a generic format and a SCA for C++ runtime function with a +standard signature is invoked. The details of the call are passed as data. </p> + +<p>On the other end of the runtime, a generated function with a +standard signature is called, this function will inspect the data that +represents the call’s method name and call the appropriate type specific +function in the C++ implementation. </p> + +<h2>The Input Data Used</h2> + +<p>The input directory passed to the Scagen method is taken to +be the SCA module root directory. All the sca.module and .fragment files in +that directory are inspected to resolve all the <component/> elements +within them. </p> + +<p>Each <component/> element found is inspected to see if +it has a <implementation.cpp/> element within it. </p> + +<p>Each <implementation.cpp/> element should have a +header attribute that represents a C++ header file that contains function +prototypes for the C++ implementation of the service. An optional class +attribute can be used to select one class if more than one that is present in +the header file. The default class is the one with the same name as the header +file. The tool will verify that the implementation header contains an +appropriate class prototype. </p> + + + +<p>The directory that contains the implementation header should +also contain a matching .componentType file for the equivalent SCA component. So +for example, a MyServiceImpl.h file would have a corresponding MyServiceImpl.componentType +file in the same directory. </p> + + + +<p>Each componentType file is inspected for <service/> +and <reference/> elements. For each <service/> element that is +found that contains a <interface.cpp/> element within it,</p> + +<p>the header attribute of the <interface.cpp/> is taken +as the filename of the C++ interface header for the SCA service. This C++ +header file is opened and used as a means for specifying the SCA service +resulting in an appropriate wrapper and proxy being generated for this service +interface. Both method bodies and headers are generated in the given output +directory. The processing of a <reference/> element is the same except +that only a proxy header and implementation are generated. </p> + + + + + +<h2>Outline Design: How it Works</h2> + + + +<p>The basic approach is to scan in the XML files by first +creating a DOM document tree of them and then recursively rifling through the DOM +with some generic code in the XMLFileActorClass by default this processing will +build up a map which maps the XPath location of attributes to their values. +Additionally subclasses can add to a “handlers map” which maps from the name of +a particular element to an object that implements the DomNodeHandler interface. +If the XMLFileActor code comes across any element that has an equivalent handler +in the handler map the objects handleNode method will be called. </p> + +<p>Typically the DomNodeHandler’s handle node interface will +use XPath to pull out the parameters that it is interested in from the +parameters map that is being built up by the generic code. </p> + +<p>This design was chosen as the Java level specified for the +original implementation did not have direct XPath query of XML data but it was +known that this would be available in Java 1.5 onwards. The design allows the +DOM and parameters map handling to be replaced in the future with JRE 1.5 code +with less impact on the rest of the code.</p> + + + +<p>The processing leads to the parsing of the C++ interface +files using the org\apache\tuscany\sca\cpp\tools\common package. This results +in a Headers object</p> + +<p>that contains a List of Signature objects, each one +representing a function prototype found in the header. </p> + + + +<p>We are aiming to get all the semantic data we want to use +into a DOM document (this represents the model of our input data) and then use +XSLT to create the 4 different views of this data:</p> + +<p>Proxy C++ header</p> + +<p>Proxy C++ body</p> + +<p>Wrapper C++ header</p> + +<p>Wrapper C++ body</p> + + + +<p>So we prepopulate the DOM with parameter data that comes +from the XML files and then iterate through the Signatures that are returned +from the C++ header parser transferring the useful data into the DOM. </p> + + + +<p>We than use 4 XSLT stylesheets to generate the C++ output +files as required. </p> + +</div> + +</body> + +</html> |