SonghaySystem(::)

• Songhay Home
• Privacy Policy
• Send Mail to Us

Songhay.NET: An Overview of the Songhay Data Namespace

This document summarizes the design goals and designer intentions behind the Songhay.Data namespace, written in C# for .NET 2.0.50727. This namespace provides all Songhay System applications access to DBMS data. It is the core of the Songhay System Data Access Framework. This small framework does not recognize the problem of mapping relational data to .NET objects in larger frameworks like NHibernate or LLBLGen. This framework is a rendition of a fraction of what’s in the DataContext in LINQ. It is best to place the purpose for this framework in the context of moving out of SQL 2000 DTS and going straight to managed code (veering away from the gigantic, official replacement for DTS, SQL Server Integration Services).

The characteristics of the Songhay.Data namespace are governed by these strong words:

• Activity
• Common

The strong word Activity implies there are ‘activities’ associated with data. These activities operate under a contract by the interface IDataActivityAssembly, defining the Data Activity Assembly. The XML configuration of the Data Activity Assembly is de-serialized into the DataAccessConfiguration class—specifically, its array of DataAccessItem objects. The DataAccessItem allows the Data Activity Assembly to load components implementing the ICommandHandler interface when needed. It follows that these two interfaces, IDataActivityAssembly and ICommandHandler, define an actor and a receiver—a primal, input-output system for data access.

The strong word Common indicates support for the System.Data.Common namespace. This is a move toward supporting the widest range of data stores possible based on the assumption that Microsoft (and the Mono team) will continue to invest in the System.Data.Common namespace—and, in fact, Microsoft would use assets in this namespace to support LINQ and the Entity Framework “under the hood.”

As a courtesy—to warn early and often—it must said that the Songhay.Data namespace prioritizes XML-over-HTTP scenarios. This immediately means that the “data set” in this space will, by default, be the XPathDocument.

The Songhay.Data.DataAccessConfiguration Class

The XML configuration of the Data Activity Assembly is defined by the composite, DataAccessConfiguration partial classes. Since this is composed of partial classes, most of the members of this class are generated by the XML Schema Definition Tool (Xsd.exe).

DataAccessConfiguration()	The constructor of this class takes a parameter that specifies an XML file, valid for the schema in DataAccessConfiguration.xsd.
DataAccessItem[]	An array of DataAccessItem (see below).
GetDataAccessItem()	Uses an anonymous delegate to return a DataAccessItem based on the specified DataAccessItem.Name or the static overload is used to load a DataAccessItem from the specified XML file and XPath Query.

The Songhay.Data.DataAccessItem Class

The DataAccessItem composite of partial classes provides the information needed to access data. A DataAccessConfiguration object contains one or more of these items. Multiple items of type DataAccessItem available at the command line or on a Web server provide a flexible, simple way to associate many procedural activities with many data stores.

Connection[]	An array of Songhay.Data.Connection. Zero or more Songhay.Data.Connection objects are used to provide data store connection information.
DisplayName	The human-readable name of the DataAccessItem.
GetConnection()	Uses an anonymous delegate to return a Songhay.Data.Connection based on the specified Connection.Name.
GetNameValuePair()	Uses an anonymous delegate to return a Songhay.Data.NameValue pair based on the specified NameValue.Name.
Name	The unique name of the DataAccessItem. This value is used in one of the overloads for DataAccessConfiguration.GetDataAccessItem() (see above).
NameValuePair[]	An array of NameValuePair. Zero or more NameValuePair objects can be used to provide parameters for DataAccessItem. These provide the means to “hard code” a relatively generic data activity to a specific problem domain.
Path	The path to the Data Activity Assembly used for data access.
TypeName	The fully-qualified, type name of the Data Activity Assembly used for data access. This type must implement the IDataActivityAssembly interface (see below).

The Songhay.Data.Connection Class

Songhay.Data.Connection objects are used to provide data store connection information.

ConnectionString	A valid connection string.
DisplayName	The human-readable name of the connection.
Name	The unique name of the connection. This value is used for DataAccessItem.GetConnection() (see above).
InvariantProviderName	The ADO.NET invariant provider name for a System.Data.DbConnection. For SQL Server, the name is "System.Data.SqlClient".

The Songhay.Data.NameValuePair Class

NameValuePair objects can be used to provide parameters for DataAccessItem. These provide the means to “hard code” a relatively generic data activity to a specific problem domain.

Name	The unique name of the pair. This value is used for DataAccessItem.GetNameValuePair() (see above).
Value	The value of the pair.

The Songhay.Data.Activity.IDataActivityAssembly Interface

The IDataActivityAssembly interface defines the execution contract for Data Activity assemblies. The Data Activity Assembly cannot run in this framework without implementing this contract.

Execute()	This method is used to run or execute the Data Activity Assembly based on the specified DataAccessItem (see above).
Log	This property contains all of the runtime messages generated and captured for this class.
WriteLog	This event, with delegate EventHandler<OnWriteLogEventArgs>, fires when the writing the latest entry into the transformation log. The type OnWriteLogEventArgs is shown with IDataActivityAssembly above.

The Songhay.Data.Activity.DataActivityAssembly Class

The DataActivityAssembly class implements the IDataActivityAssembly interface. This is a “base” class for a Data Activity that provides event-logging support for the System.Data.Common.DbConnection.

Execute()	Implements member of IDataActivityAssembly interface (see above).
Log	Implements member of IDataActivityAssembly interface (see above).
WriteLog	Implements member of IDataActivityAssembly interface (see above).
CnnStateChange()	Handles the DbConnection.StateChange() event, calling WriteToLog().
WriteToLog()	Takes message data from the Data Activity and fires the WriteLog event.

The Songhay.Data.Common.CommonDbms Static Class

The CommonDbms class provides generic procedures for data access.

Close()	Attempts to close the specified System.Data.Common.DbConnection and dispose of it. This method should be used rarely because using blocks wrap a new DbConnection and automatically close and dispose.
DoCommand()	Executes the specified statement for the specified System.Data.Common.DbConnection. This member returns the integer value of the records affected by the statement. An optional Dictionary<String, Object> can be supplied for a parameterized statement (see Songhay.Data.Common.CommonParameter).
GetAdapter()	Returns a System.Data.Common.DbDataAdapter based on the specified invariant provider name. When an optional connection string and a SELECT statement are provided, the DbCommandBuilder is used to generate DeleteCommand, InsertCommand and UpdateCommand commands.
GetConnection()	Returns a System.Data.Common.DbConnection based on the specified invariant provider name and connection string.

The Songhay.Data.Common.CommonParameter Static Class

The CommonParameter class provides a few static helper members for System.Data.Common.DbParameter.

GetParameter()	Returns a DbParameter based on the specified DbCommand, parameter name and value (this is optional). You have the option of supplying DbType, Int32 parameter size, ParameterDirection, String source column, DataRowVersion and a Boolean indicating whether the source column is Nullable. This is for the appeasement of DataSet design patterns.
GetParameters()	Returns an array of DbParameter based on the specified DbCommand and a Dictionary<String, Object> of parameters.

The Songhay.Data.Common.CommonReader Static Class

The CommonReader class provides a few static helper members for System.Data.Common.DbDataReader.

GetReader()	Returns a DbDataReader based on the specified DbConnection and query. You have the option of supplying a Dictionary<String, Object> of parameters (with a timeout value in seconds) in addition to the query. You also have the option of supplying an ambient DbTransaction object for scenarios not using TransactionScope.
GetXPathDocument()	Returns an XPathDocument based on the specified DbCommand query and (local) document element name. You have option of specifying a (local) row element name as well. Instead of a DbCommand query, you can specify a DbConnection and query string. You can also use an existing DbDataReader as well.

The Songhay.Data.Common.CommonScalar Static Class

The CommonScalar class provides a few static helper members for System.Data.Common.DbDataReader. This defines the ‘Common Scalar’ as a string representation of relational data. This is deliberately designed to take advantage of SQL Sever 2005 queries like this:

DECLARE @xml XML

SET @xml = (SELECT * FROM MyTable FOR XML AUTO, ELEMENTS, ROOT('RootElement'))

SELECT @xml
                  

This pattern emerges from the problem documented in “SQL Server 2005 PROBLEM: Using the ADO.NET DbCommand.ExecuteScalar() Method Truncates at 2033 Characters.”

GetString()

Returns a well-formed XML string based on the specified DbConnection, query and a Boolean indicating whether to emit an XML message for an empty set. You have the option of supplying a Dictionary<String, Object> of parameters in addition to the query. This member is used in XML-over-HTTP designs serving AJAX clients.

The Songhay.Data.ICommandHandler Interface

The ICommandHandler interface defines how a data access layer should accept external commands and respond to these commands. This interface was built to handle primitive XML-over-HTTP communication as lightweight alternative to formal SOAP-based implementations.

The use of this interface and an ASP.NET *.ASHX page, for example, is a very agile way to get an AJAX server up and running for vendor-agnostic HTTP clients.

DoCommand()

Returns an XPathDocument based on the specified Songhay.Data.DataCommandInput structure (shown above). One DataCommandInput structure can take generic argument which specifies the type of the POST data. The other DataCommandInput structure does not accept POST data as it is used for GET operations.

This document was last reviewed on Monday, August 20, 2007 at 02:16 PM PDT.

Copyright© 2008 by Bryan D. Wilhite All rights reserved. No part of this material may be used or reproduced in any form or by any means, or stored in a database or retrieval system, without prior written permission of the publisher except in the case of brief quotations embodied in critical articles and reviews. Making copies of any part of this material for any purpose other than your own personal use is a violation of United States copyright laws.

The information provided by Bryan D. Wilhite at kintespace.com is provided “as is” without warranty of any kind. In no event shall Bryan D. Wilhite or any of his affiliates be liable for any damages whatsoever including, but not limited to, direct, indirect, incidental, consequential, loss of business profits or special damages due to material published by Bryan D. Wilhite or any of his affiliates.