1 files changed, 89 insertions, 0 deletions
diff --git a/sdo-cpp/branches/sdo-cpp-pre2.1/doc/CommittersGuide.txt b/sdo-cpp/branches/sdo-cpp-pre2.1/doc/CommittersGuide.txt
new file mode 100644
index 0000000000..fb22cbf06d
--- /dev/null
+++ b/sdo-cpp/branches/sdo-cpp-pre2.1/doc/CommittersGuide.txt
@@ -0,0 +1,89 @@
+
+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.
+
+
+
+Tuscany SDO Committers Guide
+============================
+
+All classes should be in the commonj/sdo namespace.
+
+The Tuscany SDO codebase consists of a number of abstract classes representing the SDO API. These
+are accompanied by a set of classes whose names end in Impl, which are the implementations of the
+API. For example the DataObject API is represented by the DataObject class, and implemented by
+the DataObjectImpl class. 
+
+When pointers to classes are handed out by the library, they are really pointing at instances of
+the Impl class, but the application must not make that assumption.
+
+DataObjects and DataFactories inherit from a base class which maintains a reference count on 
+itself (RefCountingObject). The pointers handed out are really classes holding a pointer to
+the object, such that they can contribute to the reference count when copied. These RefCountingPointers
+must not be deleted, they dispose of the underlying object when the reference count drops to
+zero.
+
+There is trace commented out of RefCountingObject, which can count and report the references. It is
+particularly useful to check that all instances are cleared at the end of a program run.
+
+The API for metadata consists of the DataFactory, Property and Type classes. All Properties and Types
+handed out to the client are const, so setting up the modifying the types is done using APIS of the
+data factory.
+
+The process of creating types is usually done by loading them from XSD, but can also be performed 
+by using the data factory. Properties and Types may both be defined, but the data factory 'locks'
+itself as soon as the first DataObject is created. It does this because at that point it needs to 
+resolve the type hierarchy, and perform validation. For consistency a Type may not be modified once
+an instance has been created.
+
+A data object contains properties, which are of a particular Type, however the API allows access to
+all properties using any of the methods. getString() may be called on a Boolean property etc. The
+conversion is attempted by the Type class, and either throws an exception or passes back a converted
+value according to the tables in the specification.
+
+The get/set APIs of DataObject are supplied by a set of macros in DataObjectImpl.cpp. These are 
+duplicated for string and non-string, and also make it hard to debug effectively. They will be 
+removed and replaced by methods in the future. For now, the easiest way to debug them is to be 
+aware that each eventually calls the private no-params method, so for example all the getString(...)
+methods eventually call getString().
+
+The internal string handling is partially working with the SDOXMLString class, and partially still uses
+allocated char* buffers, these will be replaced by SDOXMLStrings in the future.
+
+The parsers for XML are absed on the SAX2Parser class, but the bulk of the processing is done by the
+startElementNS and similar methods in the SDOSchemaSAX2parser and SDOSAX2Parser classes. These are called
+back by the libxml2 library, and build a picture of the information which it then decoded by the XSDhelper
+or XMLHelper class into metadata or data.
+
+There are easy targets for improvements of performance, particularly in DataObject and parsing of XSD
+input, here is a list of a few that I can think of:
+
+DataObject frequently maps from Property to index, and this could be re-organized to avoid most of these.
+
+The allocation of space for property values could in most cases be dropped - its usually s fixed size
+element.
+
+The use of DataObject as a means of storing lists of primitives is not optimal, and should be replaced.
+
+The ChangeSummary class holds the previous value of any property when it is changed. At present, for many-
+valued properties, it holds the entire list as it was before an addition. This could just keep a record of
+the changes, and only save the old list when serializing.
+
+Parsing the XSD loops though types checking that all substitutes are covered, it would be good to
+replace this.
+
+  
+\ No newline at end of file