diff options
Diffstat (limited to 'sdo-cpp/trunk/doc/DesignNotes.htm')
| -rw-r--r-- | sdo-cpp/trunk/doc/DesignNotes.htm | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/sdo-cpp/trunk/doc/DesignNotes.htm b/sdo-cpp/trunk/doc/DesignNotes.htm new file mode 100644 index 0000000000..f6d532a4cd --- /dev/null +++ b/sdo-cpp/trunk/doc/DesignNotes.htm @@ -0,0 +1,259 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<!-- + 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 http-equiv="Content-Type" content="text/html;charset=utf-8"> + <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"> + + <meta name="robots" content="noindex,nofollow"> + <title>Tuscany SDO for C++ Design Notes</title> + +</head> +<body dir="ltr" lang="en"> +<div id="page" dir="ltr" lang="en"><!-- start page --> + +<h1 id="title">Tuscany SDO for C++ Design Notes</h1> +<div id="content" dir="ltr" lang="en"> +<a id="top"></a> +<p>See the 'live' verson of these notes at <a HREF="http://wiki.apache.org/ws/Tuscany/TuscanyCpp/DesignNotes">http://wiki.apache.org/ws/Tuscany/TuscanyCpp/DesignNotes</A> +<h2 id="head-780571e8917285d0f0c1ebae03ade69ebb3fe51a">1. Logging</h2> + +<p>Logging is not mentioned in the V2.01 specification, however, a +rudimentary logging capability is provided in the current +implementation, using three classes. </p> +<ul> +<li><p> LogWriter </p> +<ul> +<li style="list-style-type: none;"><p>This defines an abstract class with a single <strong>log</strong> method. </p> +</li> +</ul> +</li> +<li class="gap"><p> DefaultLogWriter </p> +<ul> +<li style="list-style-type: none;"><p>Instantiates <strong>LogWriter</strong> implementng a <strong>log</strong> method that writes to <strong>cout</strong> </p> +</li> +</ul> +</li> +<li class="gap"><p> Logger </p> +<ul> +<li style="list-style-type: none;"><p>A class with a static pointer to a <strong>Logwriter</strong> object. When the class is loaded the pointer is initialized to a reference to an instance of <strong>DefaultLogWriter</strong>. <strong>Logger</strong> provides its own <strong>log</strong> and <strong>logArgs</strong> methods that use the <strong>log</strong> method of <strong>DefaultLogWriter</strong> </p> +</li> +</ul> +</li> +</ul> +<p>In the current implementation, logging is seldom used. </p> + +<h2 id="head-7290fb54a6fb6ba18c63fd8a5cd6790051a515fc">2. Conversion from C style strings to C++ style strings</h2> + + +<h2 id="head-507cb2b48b05cbdfcdb3d687945efc737433c25f">3. Debugging the XML parser</h2> + +<p>SDO uses the SAX parser provided by libxml2 (<a rel="nofollow" href="http://xmlsoft.org/index.html"><img src="DesignNotes_files/moin-www.png" alt="[WWW]" height="11" width="11"> http://xmlsoft.org/index.html</a>) +to parse XML documents (and therefore XSD documents also). The SAX +parser uses a callback mechanism to report XML events to its caller. +These callback routines are supplied to the parser using a struct of +type xmlSAXHandler, called SDOSAX2Handler that is defined in +SAX2Parser.cpp. However, since libxml2 is written in C and operates +with no knowledge of objects or classes, it is necessary to bridge the +gap between libxml2's C-style call back mechanism and the objects that +comprise SDO. This is done as follows. </p> +<p>The file SAX2Parser.cpp defines (C style) functions for all the +callback routines required by libxml2. Looking through that file, it is +clear that many of those functions, such as sdo_internalSubset(), are +empty, meaning that SDO will simply ignore that particular event if it +is reported by libxml2. Where a callback function is not empty, the +active contents usually take the form of a call such as </p> +<p>(SAX2Parser*) ctx)->startDocument() </p> +<p>This call is forwarding the event reported by libxml2 to a method within a parser object created by SDO. </p> +<p>To understand this, we have to step back a little. A client of +libxml2 initiates the parse of an XML instance by calling the +xmlSAXUserParseFile() function. This function takes three parameters. +The first is the struct containing the list of callback functions (ie +SDOSAX2Handler) and the third is the name of the XML file to parse. The +second parameter is of type <strong>void*</strong> and is not used by +libxml2 directly. However, it is passed to every callback functon that +libxml2 calls as part of this parse to supply them with whatever +context information it represents. In Tuscany SDO that context is in +fact a pointer to an object that implements the appropriate parsing of +the file and these objects are instances of one of two classes, both of +which are derived from a common base. The base class is SAX2Parser, and +that defines virtual methods to handle events returned by libxml2. (In +fact it defines methods for that subset of the events that SDO will +use.) The two concrete classes are SDOSAX2Parser and +SDOSchemaSAX2Parser. The former is used when parsing XML instance +documents and the latter when parsing XML Schema Definitions. Both +classes re-implement the methods that process SAX events to handle them +in the appropriate way for either XML or XSD. </p> +<p>Therefore, the overall process for parsing an XML or XSD input +document and generating the corresponding data object or meta data +structures in SDO as follows. </p> +<p>1. Create an instance of SDOSAX2Parser for parsing XML instance +documents or an instance of SDOSchemaSAX2Parser for parsing an XSD +document. </p> +<p>2. Pass the address of the SAX2Parser object just created to libxml2 +as the context parameter of the xmlSAXUserParseFile() function. </p> +<p>3. As the parse unfolds, libxml2 will use the SDOSAX2Handler struct +to call the callback function that is appropriate for each event that +it is reporting. These will be C functions in SAX2Parser.cpp </p> +<p>4. Many of those functions will simply return having done nothing +because SDO has no interest in that particular event. However, when a +SAX event is of interest, the C callback function will use the context +parameter that libxml2 has supplied to it (ie the address of a +SAX2Parser object) to call the method on that object that corresponds +to the current SAX event. </p> +<p>Simple. </p> +<p>To watch the parsing of a file as it unfolds there are three broad +options. If the file is an XSD then place breakpoints on the methods of +SDOSchemaSAX2Parser. If it is an XML instance then set breakpoints on +the methods of SDOSAX2Parser. If it could be either, then place +breakpoints on the C functions that are named in SDOSAX2Handler and +that are found in SAX2Parser.cpp </p> + +<h2 id="head-c0ac7aae89a380ef5b343dc5ebc99b721000ad93">4. Modifying the SDO Build to use the Apache stdcxx Standard C++ library</h2> + +<p>stdcxx is an implementation of the C++ Standard Library provided by Apache. The website is at <a rel="nofollow" href="http://incubator.apache.org/stdcxx/"><img src="DesignNotes_files/moin-www.png" alt="[WWW]" height="11" width="11"> http://incubator.apache.org/stdcxx/</a>. </p> +<p>To build SDO using stdcxx rather than the native C++ library on +Windows, the following modifications to the Microsoft Visual Studio +.NET 2003 build environment are necessary. We assume that a source +extract of stdcxx is already available in a directory called +C:\Tuscany\stdcxx-4.1.3 (based on the version number of the current +release at the time of writing). We also assume that debug and release +versions of this library have been built in directories called +C:\Tuscany\stdcxx-4.1.3\Debug and C:\Tuscany\stdcxx-4.1.3\Release. The +process for building these is described here <a href="http://wiki.apache.org/ws-data/attachments/Tuscany%282f%29TuscanyCpp%282f%29DesignNotes/attachments/HowToBuildStdcxxForTuscanySDO.txt">HowToBuildStdcxxForTuscanySDO.txt</a> </p> +<p>1. Define an environment variable, STDCXX_HOME to identify the root of the source extract tree ie C:\Tuscany\stdcxx-4.1.3 </p> +<p>This is not strictly necessary but is convenient given how often we will refer to that location. </p> +<p>2. Add the stdcxx include directories to the appropriate search path. These directories are </p> +<ul> +<li style="list-style-type: none;"><p>$(STDCXX_HOME)\include </p> +<p>$(STDCXX_HOME)\include\ansi </p> +<p>and either </p> +<p>$(STDCXX_HOME)\Debug\include\15d - for a debug build </p> +<p>or </p> +<p>$(STDCXX_HOME)\Release\include\12d - for a release build </p> +</li> +</ul> +<p>For MSVC 7.1 these should be appended to the list found in +Configuration Properties -> C/C++ -> General -> Additional +Include Directories </p> +<p>3. Add environment variable definitions. These variables are </p> +<ul> +<li style="list-style-type: none;"><p>_RWSTD_USE_CONFIG </p> +<p>_RWSHARED </p> +<p>and _RWSTDDEBUG for a debug build </p> +</li> +</ul> +<p>4. Add the stdcxx library directory to the appropriate search path. This directory is </p> +<ul> +<li style="list-style-type: none;"><p>$(STDCXX_HOME)\Debug\lib - for a debug build </p> +<p>and </p> +<p>$(STDCXX_HOME)\Release\lib - for a release build </p> +</li> +</ul> +<p>For MSVC 7.1 these should be appended to the list found in +Configuration Properties -> Linker -> General -> Additional +Library Directories </p> +<p>5. Add the stdcxx library name as a dependency. The library name is </p> +<ul> +<li style="list-style-type: none;"><p>stdlib15d.lib - for a debug build </p> +<p>and </p> +<p>stdlib12d.lib - for a release build </p> +</li> +</ul> +<p>For MSVC 7.1 these should be appended to the list found in +Configuration Properties -> Linker -> Input -> Additional +Dependencies </p> + +<h2 id="head-feededf8be9c9caa8efe879e11523875c15f44ce">5. Discriminated Types</h2> + +<p>Prior to the changes introduced in revision 502599, in response to +JIRA TUSCANY-546, the C++ implementation made extensive use of C style +macros, particularly in DataObjectImpl.cpp. This code had been +motivated by the requirement for SDO to process a variety of different +data types (integer, float, string etc) in very similar ways. +Unfortunately, while macro code makes it easy to clone behaviour by +instantiating the macro for different datatypes, it has several +disdavantages. By far the most serious is the impossibility of +debugging code that has been generated by the macro preprocessor, +closely followed by the fact that most non-trivial macros are difficult +to read and understand. These twin problems lead onto the common result +that macro generated code is often inefficient. </p> +<p>TUSCANY-546 remedies these problems by introducing a new class, +SDOValue, defined in SDOValue.cpp and SDOValue.h. This class consists +fundamentally of a union of all the possible data types that SDO must +accommmodate, together with an enumerated type that identifies which +particular data type is stored in the current object. The union and +enumeration are themselves defined in DataTypeInfo.cpp and +DataTypeInfo.h. </p> +<p>Not surprisingly, SDOValue provides constructors to initialise an +SDOValue object from any of the primitive data types. There are also +retrieval methods that will extract a primitive value from an SDOValue, +converting as necessary (and throwing an exception for those +conversions that are impossible). For the most part these methods are +straightforward. The only slight complications arise when dealing with +primitives that are strings of characters. There are three such data +types - </p> +<p>String: This is a null terminated sequence of single byte +characters. It corresponds to the C notion of a string, and the C++ +std::string class. </p> +<p>WideString: This is a null terminated sequence of double byte +characters. In C++ this might be represented by the std::wstring class, +although in this implementation it is represented in the C fashion, +using a pointer to a null terminated sequence of wchar_t elements. </p> +<p>ByteArray: A sequence of bytes that is not terminated by a null character. An associated length value is therefore required. </p> +<p>SDOValue objects represent such values with pointers to other +objects or allocations of memory, therefore, copy operators and +destructors must allow for the need to copy or delete the items that +are at the far end of these pointers. </p> +<p>From then on, the general strategy is straightforward. All methods +that are part of the SDO external interface must be preserved. However, +as far as possible, other methods that used to be replicated (by macro +expansion) for each different datatype, are replaced by a single method +that works with SDOValue objects. Where it is necessary to work with +the actual primitive data type explicitly, this is normally done via a +switch statement. The external methods that were previously generated +by macro expansion are replaced by explicit code that is little more +than a veneer that converts between the SDOValue that is used +internally and the primitive data type that is required by the public +interface. Numerous examples of this appear in DataObjectImpl.cpp, the +getBoolean and setBoolean methods being typical. </p> +<p>Code to convert between the various primitive data types is already +available in the TypeImpl class. However, this is not ideal since a) as +coded it is dependent on the TypeImpl class, even though that isn't +strictly necessary and therefore b) it tends to bloat the already large +TypeImpl class. The SDOValue code provides it's own conversion methods +in the SDODataConverter class. The intention is to migrate all +conversions in SDO to the methods in that class, however, that +transition is not yet complete. </p> +<a id="bottom"></a> + +</div> +<p id="pageinfo" class="info" dir="ltr" lang="en">last edited 28.02.2007 13:24:53 by <span title="blueice2n1.uk.ibm.com">GeoffWinn</span></p> +</div> <!-- end page --> + +</body></html>
\ No newline at end of file |