.Grove—— .Net下的ORM框架

The .NET ORM Architecture（.Net ORM 架构）

一、Grove描述

Grove是为.Net项目开发而设计的一个组件。Grove ORM Development Toolkit包含包含Grove和Toolkit两部分内容，Grove基于.Net框架，支持多数据，提供标准的拖曳、三层及多层的开发模式。

二、Grove工具包

Grove工具是一个基于.Net开发环境的附件，它能够从数据源直接查看到实体类与XML描述。例如单一对象或者关系对象（互相联系的对象），这里的几个抓图屏幕显示了它的一些描述。

三、The ObjectOperator

The ObjectOperator 与数据进行通信，它使用 AppSettingManager 来设置数据源，如设置数据库服务器的连接字符串。The ObjectOperator 使用Attributes决定在数据源中的字段与表与一个对象成员的映射关系，即字段与表做为一个持久性对象来使用与从数据源中返回一个对象成员属性。

The ObjectOperator 可能使用一个存在连接字符串来构造，或者你必须确保在当前项目的Web.Config文件中的ConfigurationSettings存在AppSettings节点，并设置Key属性值为"DBConnString",Value值为一个正确的连接字符串。

下面的例子显示了ObjectOperator的创建：

 

[System.Configuration.ConfigurationSettings.AppSettings["DBConnString"];]

ObjectOperator oo=new ObjectOperator();

 

[Custom Connection String]

ObjectOperator oo=new ObjectOperator("Server=localhost;Uid=sa;Pwd=sa;Database=sample");

 

ObjectOperator提供了下列方法,主要功能是从一个数据源中返回对象,或者返回给数据源对象。

Method	Description
Insert	Insert an object into the data source
Update	Update an object
Remove	Delete an object from the data source
RemoveChilds	Delete child objects
Retrieve	Returns an object from the data source
RetrieveChilds	Returns child objects from the data source
GetDataReader	Returns an IDataReader from the data source
GetObjectSet	Returns a collection of object values
GetObjectSource	Returns a DataSet which contain the data source of the object
GetCount	Returns a records count of the data source
BeginTranscation	Begins a transaction at the data source, if transactions are supported by the data source.
Commit	Commits the current transaction.
Rollback	Rolls back the current transaction.

 

四、The ObjectQuery

这ObjectQuery被用来帮助ObjectOperator从数据源中获得对象，例如，ObjectOperator需要它来得到一个“QueryString”而加以执行，ObjectQuery使用Attributes关键字决定当前对象引用单表或多表。

一个ObjectQuery对象的构造，通过传递一个对象类型或一个过滤字符串给ObjectQuery的构造函数，详细过滤定义，参考Filter syntax （过滤语法）。例如，下面的ObjectQuery搜索所有State值等于“WA”的Customer对象。

ObjectQuery query=new ObjectQuery(typeof(Customer),"this.State='WA'");

为返回对象的所有数据类型，指定一个空的字符中作为你的过滤条件，如下例子：

ObjectQuery query=new ObjectQuery(typeof(Customer),"");

这Filter 允许你在关系对象中使用“Contains”关键字定义字查询，你可以查询出存在定单数据超过50的

所有Customer对象。

ObjectQuery query = new ObjectQuery(typeof(Customer),”Order.CustomerID.Contains(this.CustomerID)”);

query.DeclareSubset(typeof(Order),”Order.Quantity>50”);

五、The FilterExpression（过滤表达式）

这FilterExpression 是一个可扩展的过滤，即FilterExpression允许你偏离ObjectQuery来为一些操作构造许多复杂的条件，例如通过自定义条件来更新一个对象。

一个FilterExpression的创建，通过传递一个对象类型或传递一个过滤字符串给ObjectQuery的构造函数。

例如下面的FilterExpression定义了一个State等于“WA”的所有“Customer类型”的对象的过滤表达式。

FilterExpression filterex = new FilterExpression(typeof(Customer),”this.State=’WA’”);

这Filter 允许你在关系对象中使用“Contains”关键字定义字查询，你可以查询出存在定单数据超过50的所有Customer对象。

 

FilterExpression filterex=new FilterExpression(typeof(Customer),"Order.CustomerID.Contains(this.CustomerID)");
filterex.DeclareSubset(typeof(Order),"Order.Quantity>50");

有时，我们需要更新一个对象的属性，而不更新其它属性。例如，仅仅需要更新Customer对象中State属性值，通过自定条件，如下所示：

ObjectOperator oo=new ObjectOperator();
oo.Update(typeof(Customer),filerex,"this.Status=1");

这个例子意思是将定单数量（Order）大于50的所有客户（Customer）的“State”的值设为1。

Persisting Objects （持久性对象） 

一、Mapping Object Properties（映射对象属性）

         这Grove ORM architecture 要求每一个持久性对象包含一个属性，这个属性值表示一个来自数据源的表的名字，此表名标示符在Object Mapping (对象映射)中用DataTable属性关键字来表示。

当从一个数据源中映射过来时，这PK（主键字段）需要一个属性，来表示此字段为主键字段，例如，

[KeyField("CustomerID")]
public int CustomerID{get; set;}

如果这PK Field(主键字段)不唯一，你必须确保这“KeyType”是“UniquelType.OtherDefinition”，下面的例子表示了字段类型是一个数据不唯一的String(字符串)类型。

[KeyField("Field Name",KeyType=UniqueIDType.OtherDefinition)]
public string PropertyName{get; set;}

并且，这PK field也可以使用ForeignKeyField属性来表示来自数据源的一个字段名（外键）。、

[DataTable("Orders")]
public class Order
{
    [ForeignKeyField("CustomerID")]
    public int CustomerID{get; set;}
}

另外，其它字段也需要一个名为DataField的属性来表示来自数据源的表的字段。

[DataField("Field Name")]
public type PropertyName{get; set;}

当将数据源（表）映射成为对象时，你需要量将the .NET framework data provider data types 映射成为NET framework data types。

下面的表显示了.NET Framework type与Microsoft SQL Server, OLE DB, and ODBC.的比较。详细信息请参考.NET Framework Developer's Guide。

注意：在.NET Framework data provider data types下的Null值被取代为DBNull.Value。

.NET Framework Data Provider for SQL Server

SQL Server type	.NET Framework type
bigint	Int64
binary	Byte[]
bit	Boolean
char	String Char[]
datetime	DateTime
decimal	Decimal
float	Double
image	Byte[]
int	Int32
money	Decimal
nchar	String Char[]
ntext	String Char[]
numeric	Decimal
nvarchar	String Char[]
real	Single
smalldatetime	DateTime
smallint	Int16
smallmoney	Decimal
sql_variant	Object *
text	String Char[]
timestamp	Byte[]
tinyint	Byte
uniqueidentifier	Guid
varbinary	Byte[]
varchar	String Char[]

.NET Framework Data Provider for OLE DB

OLE DB type	.NET Framework type
DBTYPE_I8	Int64
DBTYPE_BYTES	Byte[]
DBTYPE_BOOL	Boolean
DBTYPE_BSTR	String
DBTYPE_HCHAPTER	Supported through the DataReader
DBTYPE_STR	String
DBTYPE_CY	Decimal
DBTYPE_DATE	DateTime
DBTYPE_DBDATE	DateTime
DBTYPE_DBTIME	DateTime
DBTYPE_DBTIMESTAMP	DateTime
DBTYPE_DECIMAL	Decimal
DBTYPE_R8	Double
DBTYPE_ERROR	ExternalException
DBTYPE_FILETIME	DateTime
DBTYPE_GUID	Guid
DBTYPE_IDISPATCH *	Object
DBTYPE_I4	Int32
DBTYPE_IUNKNOWN *	Object
DBTYPE_NUMERIC	Decimal
DBTYPE_PROPVARIANT	Object
DBTYPE_R4	Single
DBTYPE_I2	Int16
DBTYPE_I1	Byte
DBTYPE_UI8	UInt64
DBTYPE_UI4	UInt32
DBTYPE_UI2	UInt16
DBTYPE_UI1	Byte
DBTYPE_VARIANT	Object
DBTYPE_WSTR	String
DBTYPE_UDT	not supported
DBTYPE_VARNUMERIC	not supported

.NET Framework Data Provider for ODBC

ODBC type	.NET Framework type
SQL_BIGINT	Int64
SQL_BINARY	Byte[]
SQL_BIT	Boolean
SQL_CHAR	String Char[]
SQL_DECIMAL	Decimal
SQL_DOUBLE	Double
SQL_GUID	Guid
SQL_INTEGER	Int32
SQL_LONG_VARCHAR	String Char[]
SQL_LONGVARBINARY	Byte[]
SQL_NUMERIC	Decimal
SQL_REAL	Single
SQL_SMALLINT	Int16
SQL_TINYINT	Byte
SQL_TYPE_TIMES	DateTime
SQL_TYPE_TIMESTAMP	DateTime
SQL_VARBINARY	Byte[]
SQL_WCHAR	String Char[]
SQL_WLONGVARCHAR	String Char[]
SQL_WVARCHAR	String Char[]

下面的代码，表示一个简单的一个映射关系：

[DataTable("Customers")]
public class Customer
{
    int customerID;
    string customerName;
    int parentID;
    ....
    [KeyField("CustomerID")]
    public int CustomerID
    {
        get{return this.customerID;}
    }
    [DataField("CustomerName")]
    public string CustomerName
    {
        get{return this.customerName;}
        set{this.customerName=value;}
    }
    [ForeignKeyField("ParentID")] 
    public int ParentID
    {
        get{return this.parentID;}
        set{this.parentID=value;}
    }
}

二、Persisting Object Data（持久性对象数据）

ObjectOperator 为每一个对象提供了基本的持久性方法，比如insert、insert, update, delete以及从一个数据源返回一个对象，或者通过RetriveChilds,GetObjectSet等方法来获得一个相关的对象。

因此，程序员可以扩展这些方法为更多条件的选择，下面的代码显示了它的用法。

[DataTable("Customers")]
public class Customer
{
    int customerID;
    ...
    ArrayList orders=null;
    [KeyField("CustomerID")]
    public int CustomerID
    {
        get{return this.customerID;}
    }
    public ArrayList Orders
    {
        get{
            if(orders==null && customerID>0)
                orders=(new ObjectOperator()).RetrieveChilds(typeof(Order),customerID)
            return orders;
        }
    }
}

下面的例子给出了一些基本的用法：

[persist a new object ]
Customer c=new Customer();
c.CustomerName="rainbow co.";
oo.Insert(c);

[update an object]
c.CustomerID=1000;
c.CustomerName="rainbow-co.";
oo.Update(c);

[update an retrieved object]
Customer c=(Customer)oo.Retrieve(typeof(Customer),1000);
c.CustomerName="rainbow.co"
oo.Update(c);

[update an object with new regulation]
Product p=(Product)oo.Retrieve(tyoeof(Product),guidString);
p.ProductID=newGuidString;
oo.Update(p,"this.ProductID=guidString");

Note the existing KeyField type is UniqueIDType.OtherDefinition,and need to update that.

[update objects perproty without other properties ]
oo.Update(typeof(Customer),"this.CustomerID<1000","this.Status=2");

Note update status to 2 for customer objects with id small than 1000.

[delete an object]
oo.Remove(c);

[delete related child objects]
int customerID=1000;
oo.RemoveChilds(typeof(Order),customerID);

Note the Order object must be contain a ForeignKeyField attribute for the FK field(CustomerID

三、Retrieve Object Data（返回一个对象数据）

ObjectOperator提供了极其丰富的方式，通过ObjectQuery来返回一个对象或结果集合，详细信息请查看Query for objects。

下面的例子显示了它的基本用法：

[return an existing object]
Customer c=(Customer)oo.Retrieve(typeof(Customer),1000);

[return a related child collection]
ArrayList orders=oo.RetrieveChilds(typeof(Order),c.CustomerID);

[return a related child collection through ObjectQuery]
ArrayList orders=oo.GetObjectSet(new ObjectQuery(typeof(Order),"this.CustomerID="+c.CustomerID));

[return DataSet]
EntityData orders= oo.GetObjectSource(new ObjectQuery(typeof(Order),"this.CustomerID="+c.CustomerID));

Note EntityData is an object extends the DataSet from the System.Data namespace

四、Grove Transaction(事务)

这Grove 架构支持基本的事务处理方法,通过ObjectOperator对象下的BeginTransaction、Commit和Rollback方法。如果你的数据源支持事务，你可以使用这些方法。或者你也可以有选择支持isolation level(隔离级别), 通过从System.Data命令空间里使用IsolationLevel 枚举值。如果你不使用Isolation level，缺省使用ReadCommitted事务级别。

注意：引用System.Data命名空间。

oo.BeginTranscation();
try{
      oo.Insert(c);
      oo.Commit();
}
catch{
      oo.Rollback();
}

Querying for objects

一、Mapping Relation Object Properties

Grove 架构支持映射多表到一个对象——关系对象被用来做更复杂的查询，关系对象映射制授权你在两表之间指定连接类型，即你可以有选择地使用inner join、left outer join 、right outer join或者full join为一个属性，被用在表间的映射关系。

在映射时，关系必须包含一个成员，显示结果名（执行返回一个数据集）并指定FROM子句,在此成员的属性BeginWithTable中没有FROM关键字。下面的代码表明了怎样将多表映射成为一个关系对象，从数据源中选择需要返回的字段为这个对象。

[RelationTable("PersonRelationQuery",BeginWithTable="Person")]
public class PersonInfo
{
      [RelationReflect("Person","Address",JoinType=TableJOINType.LEFTOUTERJOIN)]
      [RelationField("Id","PersonID")]
      public string Relationship_1
      {
            get{return "[Person].[Id]=[Address].[PersonID]";} 
      } 
      int _Id;
      [DataField("Id",TableName="Person")]
      public int PersonId
      {
            get{return this._Id;}
            set{this._Id=value;}
      }
      string _Name;
      [DataField("Name",TableName="Person")]
      public string PersonName
      {
            get{return this._Name;}
            set{this._Name=value;}
      }
      string _Street;
      [DataField("Street",TableName="Address")]
      public string StreetInfo
      {
            get{return this._Street;}
            set{this._Street=value;} 
      }
}

Grove Toolkit中Relation Query Builder能够帮助你，随意映射。

二、Creating Object Queries

Object queries通过创建一个ObjectQuery 对象实例指定。关于ObjectQuery的更多细节，请查看The Object Query Overview.。

[no filter query]
ObjectQuery query=new ObjectQuery(typeof(Customer),"");

[filter query]
ObjectQuery query=new ObjectQuery(typeof(Customer),"this.State='WA'");

[object oriented syntax filter]
ObjectQuery query=new ObjectQuery(typeof(Customer),"this.State='WA' && this.Country=='USA'");

[sub-set with filter query]
ObjectQuery query=new ObjectQuery(typeof(Customer),"Order.CustomerID.Contains(this.CustomerID)"); query.DeclareSubset(typeof(Order),"Order.Quantity>50");

[sub-set without filter query]
ObjectQuery query=new ObjectQuery(typeof(Customer),"PersonInfo.PersonId.Contains(this.CustomerID)");
query.DeclareSubset(typeof(PersonInfo));

ObjectQuery允许用户使用AddCandidate方法来定义使用数据库函数，如COUNT、SUM、MAX、MIN等，下面例子显示了它们基本用法。

[count query]
ObjectQuery query=new ObjectQuery(typeof(Customer),"this.CustomerName<>''");
query.AddCandidate("this.CustomerID.size()");

NOTE the same as use query.AddCandidate("*.size()");

[sum query]
ObjectQuery query=new ObjectQuery(typeof(Person));
query.AddCandidate("this.Age.sum()");

[maximum query]
ObjectQuery query=new ObjectQuery(typeof(Person));
query.AddCandidate("this.Age.max()");

[minimum query]
ObjectQuery query=new ObjectQuery(typeof(Person));
query.AddCandidate("this.Age.min()");

[average query]
ObjectQuery query=new ObjectQuery(typeof(Person));
query.AddCandidate("this.Age.avg()");

四、Returning Objects

IDataReader reader=oo.GetDataReader(new ObjectQuery(typeof(Customer),""));

ArrayList customers=oo.GetObjectSet(new ObjectQuery(typeof(Customer),""));

EntityData result=oo.GetObjectSource(new ObjectQuery(typeof(Customer),""));

五、Using Filter

IDataReader reader=oo.GetDataReader(new ObjectQuery(typeof(Customer),"this.State='WA'"));

关于更多信息，请查看The ObjectQuery and The FilterExpression。

六、Using Sub-set for queries

ObjectQuery允许你定义子集查询，即可以使用“IN”或“NOT IN”来查询，需要使用Contains关键来。

[syntax]
Object.Property.Contains(this.Property)

Note NOT IN query need contain "!" before the head.

ObjectQuery query=new ObjectQuery(typeof(Customer));
query.Filter="Order.CustomerID.Contrains(this.CustomerID)";
query.DeclareSubset(typeof(Order),"Order.Quantity>50");
ArrayList customers=oo.GetObjectSet(query);

七、Filter Syntax

Filter是ObjectOperator被用来查询对象一个查询语言，Filter允许你使用标准面向对象语言的关系操作符来查询对象。在一个查询中你可以遍历对象的关系，也可以使用标准的面向对象关系操作符进行复杂的值比较。

Operator	Description
!, not	Used to perform a Boolean operation on a single value. For example: !Order.CustomerID.Contains(Customer.CustomerID)
<, >, <= , >=	Used to compare one value to another. For example: Order.Quantity >= 12
=, !=, <>, = =	Used to compare exact values. For example: Customer.Country = 'USA' and Customer.Region != 'WA'
and, &&	Used to perform a logical junction. For example: Customer.Country = 'USA' and Customer.Region = 'WA'
or, ||	Used to perform a logical disjunction. For example: Customer.LastName = 'Smith' or Customer.LastName = 'Jones'

八、Order String（排序字符）

Order String 允许你在返回对象时控制排序。

[desc]
ObjectQuery query=new ObjectQuery(typeof(Customer),""); 
query.OrderString="this.CustomerID desc";

[multi order condition]
query.OrderString="this.CustomerName,this.GetDate desc"