diff options
Diffstat (limited to 'sca-cpp/tags/cpp-sca-20060405/tools/scagen/docs/api/org/apache/tuscany/sca/cpp/tools/services/package-summary.html')
| -rw-r--r-- | sca-cpp/tags/cpp-sca-20060405/tools/scagen/docs/api/org/apache/tuscany/sca/cpp/tools/services/package-summary.html | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/sca-cpp/tags/cpp-sca-20060405/tools/scagen/docs/api/org/apache/tuscany/sca/cpp/tools/services/package-summary.html b/sca-cpp/tags/cpp-sca-20060405/tools/scagen/docs/api/org/apache/tuscany/sca/cpp/tools/services/package-summary.html new file mode 100644 index 0000000000..7d4ef0c594 --- /dev/null +++ b/sca-cpp/tags/cpp-sca-20060405/tools/scagen/docs/api/org/apache/tuscany/sca/cpp/tools/services/package-summary.html @@ -0,0 +1,364 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!--NewPage--> +<HTML> +<HEAD> +<!-- Generated by javadoc (build 1.4.2) on Tue Nov 29 10:12:01 GMT 2005 --> +<TITLE> +org.apache.tuscany.sca.cpp.tools.services (SCA for C++ Tools) +</TITLE> + +<META NAME="keywords" CONTENT="org.apache.tuscany.sca.cpp.tools.services package"> + +<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../../../stylesheet.css" TITLE="Style"> + +<SCRIPT type="text/javascript"> +function windowTitle() +{ + parent.document.title="org.apache.tuscany.sca.cpp.tools.services (SCA for C++ Tools)"; +} +</SCRIPT> + +</HEAD> + +<BODY BGCOLOR="white" onload="windowTitle();"> + + +<!-- ========= START OF TOP NAVBAR ======= --> +<A NAME="navbar_top"><!-- --></A> +<A HREF="#skip-navbar_top" title="Skip navigation links"></A> +<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> +<TR> +<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> +<A NAME="navbar_top_firstrow"><!-- --></A> +<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> + <TR ALIGN="center" VALIGN="top"> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> + <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <A HREF="#main"><FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../serialized-form.html"><FONT CLASS="NavBarFont1"><B>Serialized</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> + </TR> +</TABLE> +</TD> +<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> +</EM> +</TD> +</TR> + +<TR> +<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> + <A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/common/package-summary.html"><B>PREV PACKAGE</B></A> + NEXT PACKAGE</FONT></TD> +<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> + <A HREF="../../../../../../../index.html" target="_top"><B>FRAMES</B></A> + <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> + <SCRIPT type="text/javascript"> + <!-- + if(window==top) { + document.writeln('<A HREF="../../../../../../../allclasses-noframe.html"><B>All Classes</B></A>'); + } + //--> +</SCRIPT> +<NOSCRIPT> + <A HREF="../../../../../../../allclasses-noframe.html"><B>All Classes</B></A> +</NOSCRIPT> + +</FONT></TD> +</TR> +</TABLE> +<A NAME="skip-navbar_top"></A> +<!-- ========= END OF TOP NAVBAR ========= --> + +<HR> +<A NAME="main"></A> +<H2> +Package org.apache.tuscany.sca.cpp.tools.services +</H2> +<div class=Section1> + + +<P> +<B>See:</B> +<BR> + <A HREF="#package_description"><B>Description</B></A> +<P> + +<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> +<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> +<TH ALIGN="left" COLSPAN=2><FONT SIZE="+2"> +<B>Interface Summary</B></FONT></TH> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/DomNodeHandler.html" title="interface in org.apache.tuscany.sca.cpp.tools.services">DomNodeHandler</A></B></TD> +<TD> </TD> +</TR> +</TABLE> + + +<P> + +<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> +<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> +<TH ALIGN="left" COLSPAN=2><FONT SIZE="+2"> +<B>Class Summary</B></FONT></TH> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/ComponentDomNodeHandler.html" title="class in org.apache.tuscany.sca.cpp.tools.services">ComponentDomNodeHandler</A></B></TD> +<TD>This class will do the required processing for the <component>element of a + sca module or fragment file.</TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/ComponentTypeFileHandler.html" title="class in org.apache.tuscany.sca.cpp.tools.services">ComponentTypeFileHandler</A></B></TD> +<TD>The purpose of this class is to specialise the map of XML element handlers + for a XXX.componentType file that is used by the XMLFileActor</TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/DirectoryScanner.html" title="class in org.apache.tuscany.sca.cpp.tools.services">DirectoryScanner</A></B></TD> +<TD> </TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/DomHandler.html" title="class in org.apache.tuscany.sca.cpp.tools.services">DomHandler</A></B></TD> +<TD>The purpose of this class it to provide a generic class that can handle both + a DOM and a DOM node.</TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/GenericDomNodeHandler.html" title="class in org.apache.tuscany.sca.cpp.tools.services">GenericDomNodeHandler</A></B></TD> +<TD> </TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/LittleClass.html" title="class in org.apache.tuscany.sca.cpp.tools.services">LittleClass</A></B></TD> +<TD>This class is just a convenient application class that is loaded in order to + get the application class loader.</TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/ModuleOrFragmentFileHandler.html" title="class in org.apache.tuscany.sca.cpp.tools.services">ModuleOrFragmentFileHandler</A></B></TD> +<TD>The purpose of this class is purely to specialise the handler map to one with + a specific ComponentDomNodeHandler.</TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/ReferenceDomNodeHandler.html" title="class in org.apache.tuscany.sca.cpp.tools.services">ReferenceDomNodeHandler</A></B></TD> +<TD>The purpose of this class is to process a <reference>element in a + componentType file and then trigger a call to the method in ServicesGenerator + to process the interface header file</TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/Scagen.html" title="class in org.apache.tuscany.sca.cpp.tools.services">Scagen</A></B></TD> +<TD>This is the main top level class.</TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/ServiceDomNodeHandler.html" title="class in org.apache.tuscany.sca.cpp.tools.services">ServiceDomNodeHandler</A></B></TD> +<TD> </TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/ServicesGenerator.html" title="class in org.apache.tuscany.sca.cpp.tools.services">ServicesGenerator</A></B></TD> +<TD>This class is the main class that handles the function that parses a C++ + interface header file into a DOM that holds all the semantic information + about the interface - method names, parameters and return values.</TD> +</TR> +<TR BGCOLOR="white" CLASS="TableRowColor"> +<TD WIDTH="15%"><B><A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/services/XMLFileActor.html" title="class in org.apache.tuscany.sca.cpp.tools.services">XMLFileActor</A></B></TD> +<TD>The purpose of this abstract class is to provide a home for the standard + processing that is involved in turning a XML file into an internal DOM.</TD> +</TR> +</TABLE> + + +<P> +<A NAME="package_description"><!-- --></A><H2> +Package org.apache.tuscany.sca.cpp.tools.services Description +</H2> + +<P> +<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> +<P> + +<P> +<HR> + + +<!-- ======= START OF BOTTOM NAVBAR ====== --> +<A NAME="navbar_bottom"><!-- --></A> +<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> +<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> +<TR> +<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> +<A NAME="navbar_bottom_firstrow"><!-- --></A> +<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> + <TR ALIGN="center" VALIGN="top"> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> + <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <A HREF="#main"><FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../serialized-form.html"><FONT CLASS="NavBarFont1"><B>Serialized</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> + <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> + </TR> +</TABLE> +</TD> +<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> +</EM> +</TD> +</TR> + +<TR> +<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> + <A HREF="../../../../../../../org/apache/tuscany/sca/cpp/tools/common/package-summary.html"><B>PREV PACKAGE</B></A> + NEXT PACKAGE</FONT></TD> +<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> + <A HREF="../../../../../../../index.html" target="_top"><B>FRAMES</B></A> + <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> + <SCRIPT type="text/javascript"> + <!-- + if(window==top) { + document.writeln('<A HREF="../../../../../../../allclasses-noframe.html"><B>All Classes</B></A>'); + } + //--> +</SCRIPT> +<NOSCRIPT> + <A HREF="../../../../../../../allclasses-noframe.html"><B>All Classes</B></A> +</NOSCRIPT> + +</FONT></TD> +</TR> +</TABLE> +<A NAME="skip-navbar_bottom"></A> +<!-- ======== END OF BOTTOM NAVBAR ======= --> + +<HR> + + <i>Copyright 2005 The Apache Software Foundation and Copyright IBM Corp. 2005 All Rights Reserved</i> +</BODY> +</HTML> |