2016/05/28 - Apache Tuscany has been retired.

Overview

Service Data Object (SDO) and Service Component Architecture (SCA) are the basic building blocks in Service Oriented Architecture (SOA). SDO is the way of representing data in SCA. As the applications using SOA have back-end data representation in different formats like Database, File System, XML Based Data, etc., there is a need to provide a mapping between these data representations and SDO. C++ RDB DAS (Data Access Service for Relational Database) is the effort to suffice this mapping requirement for Relational Database.

Function Description

RDB DAS provides 2 major capabilities:-
1) Execute SQL Queries and return result as a graph of Data Objects.
2) Reflect changes made to a graph of Data Objects back to the database.
It also supports explicit CUD SQL statements execution against database.
Unable to render embedded object: File (rdbDAS.gif) not found.

Architecture

This section describes the overall architecture of C++ RDB DAS. The details are elaborated in Design Details. Also, for details of different DAS Configuration settings, refer to Configuration Schema(config.xsd).

DAS functions based on external Configuration. This configuration can be specified using file or can be programmatically build by the caller, using Config interface.

Design follows a factory pattern to create DAS instance. DAS instance contains Connection, Config and Commands.

The Connection can either be passed from caller or can be created using the Configuration information(not implemented yet). It is used for all the database operations done in that DAS instance and also for controlling transactions.

Commands hold all the commands from Configuration file and also the ones that are created programmatically on the fly. The Command is implemented using different inherited classes like Read/Insert/Update/Delete/OptimisticWrite with root parent class CommandImpl. More details on different classes will be in Design Details.

Config holds the reference for Configuration associated with the DAS instance and contains all details as mentioned in Configuration Schema (config.xsd).

Caller has 2 (and some other) main APIs available in DAS instance to use the Commands getCommand(name) and applyChanges(Data Object)

1. getCommand(name) is typically used to retrieve the Command (SQL String) available from Config. SQL String. User calls executeQuery() on this Command and based on whether it is CUD/Read operation. executeQuery() will return a root DataObject or a null DataObject.
2. applyChanges(Data Object) is the way to process a SDO DataObject and SDO ChangeSummary to create SQL UPDATE statement to be executed against database. More details on SDO integration are in Design Details.

User Interface

DAS exposes a set of interfaces to end user.

• DASFactory uses different options to produce DAS instance using Factory pattern.
  Method Summary

  apache::das::DAS	createDAS(apache::das::rdb::ConnectionPtr connection)	Creates a DAS based on the provided connection
  apache::das::DAS	createDAS(apache::das::Config config)	Creates a DAS based on the provided config object
  apache::das::DAS	createDAS(apache::das::Config config, apache::das::rdb::ConnectionPtr connection)	Creates a DAS based on the provide config object and connection

• DAS Interface to call APIs for DAS instance.
  Field Summary

  static apache::das::rdb::DASFactoryImpl

  getFactory()

  Method Summary

  void	applyChanges(commonj::sdo::DataObjectPtr root)	The change history is scanned and modifications to the graph of data objects are flushed to the database.
  apache::das::rdb::CommandPtr	createCommand(std::string sql)	Creates a Command based on the provided SQL statement
  apache::das::rdb:: CommandPtr	getCommand(std::string name)	Gets the named command from this factory's inventory

• Command Used to execute read / write (CRUD) on database.
  Method Summary

  commonj::sdo::DataObjectPtr

  executeQuery()

  Performs the function defined by the command and return the results in the root DataObject

• ConfigImpl is used to load configuration for RDB DAS instance from a XML file. A instance of this class can be empty or can load information from a XML file.
  Constructor Summary

  apache::das::rdb::ConfigImpl()	creates an empty Config object
  apache::das::rdb::ConfigImpl(std::string xmlFilePath)	creates a Config object based on data read from the specified XML file

  Method Summary

  apache::das::rdb::Table&	addTable(std::string tableName)	create a Table object with the specified table name, adds it to the Config  object and returns a reference the created Table object
  void	addCommand(std::string commandName, std::string sqlStatement)	add a command on the Config object
  Relationship	addRelationship(java.lang.String parentName, java.lang.String childName)
  Relationship	addRelationship(java.util.Vector parentNames, java.util.Vector childNames)
  Command	addSelectCommand(java.lang.String name, java.lang.String sql)
  Table	addTable(java.lang.String name, java.lang.String typeName)
  Command	addUpdateCommand(java.lang.String name, java.lang.String sql)
  void	addUpdateStatement(Table table, java.lang.String statement, java.lang.String parameters)
  Config	getConfig()
  void	setDataObjectModel(java.lang.String dataObjectModel)

• Converter A lightweight Table-column <--> DataObject-property converter framework. Converters allow a user to insert a transformation between a column's value and its destination DataObject property's value. For example, by default, a VARCHAR column will be represented as a String in its corresponding DataObject property. A user could insert a converter that transforms the VARCHAR value to an Integer. If this is done then although the column returns character data, the DataObject property will be an Integer
  Method Summary

  java.lang.Object	getColumnValue(java.lang.Object propertyData)	Transform the columnData object to a new value and possibly new type
  java.lang.Object	getPropertyValue(java.lang.Object columnData)	Transform the columnData object to a new value and possibly new type.

• Pager An iterator-like interface to conveniently move through chunks of data. The idea is that a Pager works with a read Command. The read command returns a large amount of data and the client wants to work with chunks of it at a time. So the Pager is created on the command and each call to next returns the next chunk of data.
  Method Summary

  DataObject	getPage(int page)	Return a specific identified page
  DataObject	next()	Get the next page of data
  DataObject	previous()	Get the page prior to the last page returned

• GraphMerger is utility class implementation (no interface), to provide functions for flexibly managing DataObjects.
  Constructor Summary

  GraphMerger()

  Method Summary

  void	addPrimaryKey(java.lang.String key)
  DataObject	emptyGraph(Config config)
  DataObject	merge(DataObject primary, DataObject secondary)
  DataObject	merge(java.util.List graphs)

Class Diagram

Class Diagram

Design Details

Major classes are described here at high level to show how these fit in the complete picture. For
methods/members details please refer to javadoc from binary distribution at Downloads.

DASFactoryImpl Expose methods to create DAS instance from Config or Connection or both.

DASImpl The sole instance of DAS existing for one DAS runtime. It contains MappingWrapper, JDBC Connection and a Map of all DAS Commands. To create appropriate instances of CommandImpl, DASImpl, scan's each Config Command for attribute kind, and based on that required instance of CommandImpl is added to the map. Connection from DataSource or Database Driver Manager both are supported. releaseResources() method allows external caller to close JDBC Connection when it is supplied by the caller.Provides methods to get/create DAS Commands and applyChanges(changed DataObject) to reflect DataObject changes to Database.

MappingWrapper Wrapper over DAS Config. Provides various get/set methods for all different elements in DAS Config.

ConnectionImpl Contains JDBC Connection, and whether it is managed by DAS/caller and also whether Database platform support auto-generated key column values.

BaseCommandImpl Parent class for all other CommandImpl classes. Contains MappingWrapper. setConnection() method to associate ConnectionImpl with each DAS Command.

ApplyChangesCommandImpl Extends BaseCommandImpl. Contains ChangeSummarizer. It is used to load DataObject's ChangeSummary and for each change, Generator classes (UpdateGenerator, DeleteGenerator) are called to form appropriate SQL Statement with parameters, which is executed against the Database.

CommandImpl Extends BaseCommandImpl and implements DAS Config's <Command>. So, in effect it is parent class for all explicit CRUD Commands. It contains Statement, Parameters and ResultSetShape.

WriteCommandImpl Extends CommandImpl. Parent for CUD. If SELECT(Read) is attempted, exception is thrown.

DeleteCommandImpl Extends WriteCommandImpl.

InsertCommandImpl Extends WriteCommandImpl. Supports Database generated keys.

UpdateCommandImpl Extends WriteCommandImpl.

OptimisticWriteCommandImpl Extends UpdateCommandImpl. Supports OCC feature. Here by design when a CollisionParameter's value is attempted to change more than once, the CollisionParameter does not allow its value change (as during first setValue(), flag indicating that value is changed is set). So, the attempt results in no database rows getting changes. On this condition exception is thrown as Update Collision is occurred.

ReadCommandImpl Extends CommandImpl. Used for explicit SELECT. Support's DAS feature, ResultDescriptor. If CUD is attempted, exception is thrown. Supports paging. When Query is executed (executeQuery()), the JDBC ResultSet is converted into DataObject Graph and returned to caller.

SPCommandImpl Extends ReadCommandImpl for StoredProcedure call. Method executeQuery() is used when the stored procedure returns ResultSet and method execute() is used when the stored procedure does not have any return ResultSet.
Parameters hold both IN and OUT parameters.

PagerImpl Holds ReadCommandImpl, page size and current page index. Implements next(), previous(), getPage(index) methods. In each based on current page index and page size, the ReadCommandImpl is executed with start and end boundaries set.

ChangeFactory This class is used during DAS.applyChanges(). With changed DataObject and ChangeSummary, required type of ChangeOperation instance is created (like DeleteOperation, UpdateOperation). This instance of ChangeOperation holds appropriate CommandImpl, which in itself holds the Parameters. Thus for a given DAS Config and Connection, ChangeFactory is used to propagate DataObject changes to Database via CommandImpl.

ChangeSummarizer Main function of this class is load Changes based on root DataObject of applyChanges() Command MappingWrapper is used to sort the ChangeOperations in Changes.

Changes Contains DeleteList, InsertList, Update List pertaining to one applyChanges() command.

DeleteList Maintains ordered/unordered list of DeleteOperations. If DAS Config defines any Relationships, MappingWrapper aids in forming Delete Order for all the Tables undergoing DeleteOperation, based on Parent-Child relationships. If Delete Order is available, DeleteList forms a List following appropriate Referential Integrity. Otherwise no order is maintained.

InsertList Maintains ordered/unordered list of CreateOperations. If DAS Config defines any Relationships, MappingWrapper aids in forming Insert Order for all the Tables undergoing InsertOperation, based on Parent-Child relationships. If Insert Order is available, InsertList forms a List following appropriate Referential Integrity. Otherwise no order is maintained.

UpdateList As UpdateOperation happens on single Table, there is no reason for sorting based on any Referntial Relationships. So, this class is just a wrapper on ArrayList.

BaseGenerator Parent class for Delete/Update/InsertGenerator. If in DAS Config, any Table Column specifies a ColumnConverter class, BaseGenerator, returns a new instance of this class.

DeleteGenerator Extends BaseGenerator. Based on Table and DAS Config, DELETE statement is generated with Primary Keys in WHERE clause. Using this, DeleteCommandImpl is instantiated. For Parameters in DeleteCommandImpl ColumnConverter is considered if present.

InsertGenerator Same as DeleteGenerator. Here Database Key value generation is also considered.

UpdateGenerator Extends BaseGenerator. In UPDATE statement WHERE clause Primary Keys are considered as well as Default OCC policy is considered. Also check is implemented for any violation for Foreign Key relationships. Parameters in UpdateCommandImpl consider ColumnConvert as appropriate. OCC attributes in DAS Config for <Column>, viz. managed and collision are considered in SET and WHERE clause formation respectively.

ChangeOperation Abstract parent class for Create/Delete/UpdateOperation. It contains WriteCommand, DatabaseObject and any generated ID.

DeleteOperation Extends ChangeOperation. Uses SDO's ChangeSummary based OldValues as in the DataGraph , deleted objects have lost their settings.

CreateOperation Extends ChangeOperation, makes use of Generated ID.

UpdateOperation Extends ChangeOperation and makes use of generated ID.

DatabaseObject Wraps DataObject. If a field is FK, it will return value from parent. It also sets the Database generated value in primary key property of DataObject.

RowObjects Holds a Map of TableName->DataObject. It uses relationship information to associate these DataObjects to form DataGraph .

GraphBuilderMetadata Class that form Metadata for forming DataObjects based on MetaData available in JDBC ResultSet. It uses DAS Config, ResultSet and ResultSetShape to form a Collection of ResultMetaData. It is used in ResultSetProcessor and thus further in RowObjects.

ResultSetProcessor This class is used to transform data in ResultSet into set of inter-related DataObjects. It contains TableRegistry, GraphBuilderMetadata and DataObjectMaker. Using GrapbBuilderMetadata and the JDBC ResultSet, it forms
ResultSetRow , then form RowObjects and connects related DataObjects using Relationship information from RowObjects to form the completed DataGraph.

DataObjectMaker Forms DataObject based on TableData. It is used in ResultSetProcessor for this.

TableRegistry Base Interface for Single/MultiTableRegistry.

SingleTableRegistry No functionality.

MultiTableRegistry Implements TableRegistry. Used when converting JDBC ResultSet of SQL SELECT into DataObjects.

DefaultConverter Implements Converter. In case of Blob database column type, returns byte[] for the column value when mapping from database data to property value.

ResultMetaData Holds complete ResultSet related metadata of the Query result- ResultSet, ColumnConverters, MappingWrapper, SDO Type Names, SDO Property Names, ResultSetShape for the ResultSet, Map containing Table Type > Column Property (equivalent to Database Table>Column). It provides various get methods on these members.

ResultSetRow A ResultSetRow is used to transform a single row of ResultSet into a set of DataObjects. It uses TableData as a intermediate place to keep Database Data for a Row , which is later used to form DataObject. It holds a List of all Table Data for the current row. This class is used in ResultSetProcessor.

TableData Holds single JDBC row for a Table and its Columns - tableName, list of PKs, Map of ColumnName->Data, if table has PK. Is used by DataObjectMaker to form DataObject based on Table Row.

ResultSetTypeMap Provides mapping from sql.Types to SDO Type. Used in ResultSetShape to populate SDO Type[] for all columns present in ResultSet.

FactoryRegistry Maintains registry of ChangeFactory. There is one FactoryRegistry for on DAS Config and Connection. It maintains a Map with entries of each SDO Type against ChangeFactory for current DAS Config+Connection.

ParameterImpl Holds values required for representing SQL statement/StoredProcedure parameter like name, index, value, SDO Type and columnConverter. Can have direction IN/OUT/IN-OUT. IN is default. OUT/IN-OUT is only in case of Stored Procedure.

ManagedParameterImpl Extends ParameterImpl. Expected to be integer or BigDecimal type, else exception is thrown. setValue() returns oldValue+1.

CollisionParameter Extends ParameterImpl. Design restricts setting value in CollisionParameter only once.

Parameters Maintains lists of parameters (used in SQL statements), IN/OUT parameters (used in stored procedures).

ResultSetShape This is an alternative to use ResultSetMetaData of the Query result. It can be used when some platforms like Oracle do not fully support MetaData. For a given SQL Query, this holds schemaName, tableName, columnName, SDO Column Type for each column in ResultSet. It has 2 constructors, one uses JDBC's ResultSetMetaData to form ResultSetShape and another uses DAS Config supplied ResultDescriptor to form ResultSetShape.

Statement Holds SQL String, JDBC connection, JDBC PreparedStatement and also state information whether the current statement is used by Pager.

SDODataTypeHelper Provides mapping between SDO's Type and JDBC's sql.Types.

SDODataTypes Uses SDO's TypeHelper to get SDO Type for given string.

QualifiedColumn Maintains schemaName, tableName and columnName for a Table's Column.

RelationshipWrapper Wrapper for DAS Config's <Relationship>. Only one method to return Collection of all FKColumns in a Relationship.

TableWrapper Wrapper on DAS Config's <Table>. Provides various get methods to get values of different elements and attributes within <Table>.

ConfigUtil Uses SDO's XMLHelper to load DAS Config Data Model in memory.

DataObjectUtil Provides utility methods for SDO DataObject like copying one DataObject into another, restoring Old Values of a DataObject using its SDO's ChangeSummary.

Configuration Schema(config.xsd)

Complete DAS Configuration follows.
Convention Element <attribute> Child Element

Scalability Aspects

Java RDB DAS has exposed User Interfacefor end user. Other than that, from design perspective, many major DAS classes do not have associated interfaces and by design are tightly coupled with SDO and Database. It needs further enhancement on this line, especially when more DAS flavors are coming up as mentioned in Future. As DAS is a bridge between SOA based applications and backend Data Sources, the interfaces with SOA and Data Source need to be flexible. E.g. SDO/Some Other mechanism should be pluggable when using DAS as well as different technologies based Data Sources can be supported like XML files, LDAP based file system and so forth. Work is in-progress on this front.

Future

DAS is implemented in Java and C++ and both are integrated with SDO and support Relational Database based Data Source. There are other flavors of DAS coming up like LDAP DAS, XQuery DAS etc. These implementations will provide different ways to interface with the backend data source as their names suggest.

Samples

There are a couple of samples distributed to demonstrate working examples of using different DAS features. See User Guide/Samples for more details.

Terminology and Useful Links