破宝

ajaxnet4j beta Releases -- A Java Implementation of Ajax.NET Professional Library

上周在 sourceforge 申请了项目，昨天刚刚得到批准。现在正式发布 ajaxnet4j 的第一个 beta release！

请访问 SourceForge 站点：http://ajaxnet4j.sourceforge.net （Under Construction ...）

P.S. ajaxnet4j 是 Ajax.NET Professional 的一个 Java 实现。Ajax.NET Professional 是 .NET 平台下第一个、也是截至目前最流行的免费 Ajax 库之一。

posted on 2006-09-19 14:05:00 by percyboy  评论(5) 阅读(5582)

好消息：Ajax.NET Professional open-sourced 及 ajaxnet4j 即将发布

前面帖子中提到过的 ajaxnet4j 终于可以发布了。因为 ajaxnet4j 的事情，一直尝试联系 Ajax.NET Professional 的作者 Michael Schwarz。但似乎 Michael 近来的工作很忙，我发给他的 mail 以及在他博客上的留言都石沉大海。

直到前天，Michael 在他的博客中说，他开始把代码向 CodePlex 站点上转移，准备将 Ajax.NET Professional 的代码变成 open source 的！（Ajax.NET Professional @ CodePlex）

今天下午下班的时候，又去看了一下，兴奋的看到 Michael 上传上来的第一个版本，还有它的 Licence，居然是 MIT Licence（类似 BSD）！

真是个好消息！

在 Ajax.NET Professional 新的 Licence 许可下，我的 ajaxnet4j 包也可以发布了！我想这个周末之前，我就可以把它整理一下发布了。

P.S. ajaxnet4j 是我翻译的 Ajax.NET Professional 的 Java 版本。

善意提醒：最初的 Ajax.NET 库在去年某个时间，分成了两个版本：

一个是 Michael 维护的这个被称作 Professional 的版本，由 Michael 自己维护、发布，可以免费使用（包括商业使用），但禁止修改后的版本重新发布。这个版本从今天开始，使用了 MIT Licence，允许自由修改并发布，只需要保留原有作者信息即可。

还有一个版本是被称作 BorgWorX 的 Ajax.NET 库。这个库在原有基础上，添加了许多 Ajax 风格的 ASP.NET 控件。这个库早在去年就已经是 open sourced 了。它有两套 Licence 机制：一套接近 GPL，即如果采用这个库，你的代码也必须公开源代码。一套是商业 Licence，一个商业 Licence，需要花费 300 欧元。

如果你计划采用 BorgWorX Ajax.NET 这个库，请注意它的 Licence 和 Ajax.NET Professional 是不同的。

先来看看几个简单的 ajaxnet4j Samples 吧！

posted on 2006-09-13 20:04:00 by percyboy  评论(12) 阅读(7172)

NDoc Reloading: Kevin 留给我们的 NDoc 2.0 Alpha

在 ndoc 的论坛上，有一个国外的朋友提供了一个信息：一个德国的站点上有一个 NDoc 2.0 Alpha 版本：

http://www.kynosarges.de/NDoc.html

据说这个版本是 Kevin 放弃开发之前，留下来的最后一个版本，提供了对 2.0 的支持，以及很多新的 features。不过很可惜的是，这个原本内部交流的 Alpha 2.0 版，没有附带源代码，只有 exes/dlls。而且只要无法联系上 Kevin，这份源代码就没有人可以得到了。

我使用 Ninputer 的 VBF 类库 初步测试，泛型支持看起来还不错，还支持 .NET 2.0 文档中新增的 J# 语法块，整体效果似乎不错！如果你只需要英文的文档，建议你试试这个版本。

其中包含的一份 ReadMe 文件描述了其新增的功能，有几项看起来很 cool 的功能，比如新增的 inheritdoc 标签，QA Log，Intellisense 文档引擎（用于在产品发布前，对编译器生成的 /doc XML 文件“瘦身”，删除其中多余的标签，删除其中对 private 成员的注释等等。比如 .NET Framework SDK 中那个 6.87MB 的 mscorlib.xml 文件“减肥”后，只剩下 203KB。），GUI 采用了 2.0 中新增的 Visual Studio 样式的菜单和工具条，等等。

因为无法得到源代码，既不能作为 NDoc Reloading 项目的起点，也不能翻译汉化。不过其中的一些 features 有可能在将来合并到 NDoc Reloaded 项目中来。

P.S. 今天访问不了 SourceForge.net 站点。经过我近期的观察，在公司一直访问没有问题，在家里则 80% 时间无法访问。公司用的是中国电信的网络，家里用的是中国网通的网络。在 Google 搜索“sourceforge 封杀”，会立刻让 Google “死”掉几分钟；在百度搜索这几个字，则看到了众多网友的抱怨。看来应该是网通单方面屏蔽了访问。

posted on 2006-09-10 17:00:00 by percyboy  评论(10) 阅读(6339)

NDoc Reloading: 泛型与反射（补）

（回过头看了一下前面写的那篇随笔，发现确实很晕糊，至少文章里面只涉及了“泛型”，并没有涉及“反射”，题目是不确切的。所以写这一篇补充一下反射的东西。）

以下面的代码为例：

1。对该类所属的程序集（dll 或 exe）进行反射，可以得到表示泛型类 Abc 的 Type 对象 typeAbc。（对 Assembly.GetTypes 得到的 Type 数组枚举循环）

2。对于上一步得到的 typeAbc，IsGenericTypeDefinition 属性值应该是 true，按照 .NET Framework SDK 类库文档的样式（MSDN），对于泛型类型（准确地讲是“泛型类型定义”），在左侧目录树中、在类型页的天头，应该显示为“Abc 泛型类”。

3。在类型的首页中的“语法”块中，需要以 C#, VB.NET 等语言表示出该泛型类 Abc 的具体定义，即包含的每一个 parameter。使用 typeAbc.GetGenericArguments 方法，得到一个 Type[]。数组中的每一个 Type 代表一个泛型参数，既可能是形参 parameter，也可能是实参 argument。但是对于 Abc 来说，它是泛型类型定义，所以得到的每一个 Type 都应该是 parameter。泛型类型定义 Abc 只有一个形参，所以那个数组长度为1，唯一的一个 Type 假定用变量 typeParameter 存储。

4。对于上一步得到的 typeParamter，其 IsGenericParameter 属性值应为 true，其 Name 属性值就是该形参的名字“U”。

5。代码中，这个形参 U 具有两个约束条件，即1）必须是引用类型；2）必须实现 IComparable 接口。下面我们需要使用泛型得到这两个约束。

我们上次提到了五种泛型约束条件，需要分为两组，使用两种不同的方法才能得到。

5.1。typeParamter.GenericParamterAttributes 属性值是一个允许按位组合（具有 FlagsAttributes 属性）的枚举类型，查看 GenericParameterAttributes 枚举的文档可以得知，通过这个属性值，我们可以判断出 typeParameter 所代表的泛型形参 U，是否具有：1）引用类型约束（C# 代码写作 where U : class 的情形）；2）非空值类型约束（C# 代码写作 where U : struct 的情形）；3）默认构造函数约束（C# 代码写作 where U : new() 的情形）。

5.2。typeParameter.GetGenericParameterConstraints 方法得到一个 Type[]，该数组中的每一个 Type 代表泛型形参 U 所具有的1）基类约束或裸约束，2）接口约束。对于我们的实际例子，typeParameter 调用该方法得到一个长度为 1 的 Type 数组，这个数组中的唯一一个 typeConstraint 对象（代表实际代码中的 IComparable 约束条件），其 IsClass 属性为 false，说明它是一个接口约束。（这里，typeConstraint 其实就等于 typeof(IComparable)。）

总结上面的反射步骤为下图：

接下来简单写一下对于 Abc 泛型类中 Xyz 属性的反射过程：

1。同上面的1。

2。typeAbc.GetProperties 方法得到 PropertyInfo 的数组，循环每一个 PropertyInfo。假定变量 propertyXyz 存储 Xyz 属性的那个 PropertyInfo。

3。propertyXyz.PropertyType 属性可以得到、表示该属性类型的 Type 对象：typePropertyType。（对比实际代码可以知道，此 Type 对象是一个泛型类型，是一个开放构造类型，而且有嵌套现象。）

4。对 typePropertyType 类型，调用其 GetGenericTypeDefinition 方法得到其基础类型，可以知道它是一个 System.Collections.Generics.Dictionary  泛型类型。

5。然后对 typePropertyType 执行类似前面的步骤 3、4： GetGenericArguments 得到 typeArg1 和 typeArg2 两个 Type 组成的数组。

6.1。typeArg1 是一个比较普通的类型（IsGenericType = false），可以确定出 Dictionary 泛型类型的第一个实参 string。

6.2.1。对于 typeArg2，虽然 IsGenericType = false，但因为 IsArray = true，首先确定它表示一个数组。对于数组类型，需要调用 GetElementType 方法取得数组元素的类型 typeArg2ArrayElement。

6.2.2。typeArg2ArrayElement.IsGenericType = true，需要重复步骤 4、5、6，分别确定其泛型定义是 System.Collections.Generics.List。稍微特殊的是，唯一的那个泛型参数（实际代码中的那个 U），其 IsGenericParameter = true，它并不是一个确定的类型，而是一个 parameter。

（点击这里下载完整的示意图形，Excel 格式）

posted on 2006-09-10 15:51:00 by percyboy  评论(2) 阅读(6163)

NDoc Reloading: 泛型与反射

NDoc Reloading 首先面对的课题就是 .NET 2.0 中新增的泛型类型、泛型方法、可空类型等新增功能。由于可空类型应该可以算作泛型类型的一个特例，这里就不再多说了。

对于泛型类型，在 Type.IsGenericType 属性的 .NET 文档中，微软告诉我们一些术语，这里简单说明一些：

1）泛型类型定义（Generic Type Definition），就是最初定义该泛型类型的那个类型，比如 List<T>，Dictionary<TKEY, TValue> 这些类型。

2）上述这些类型括号中的这些 T, TKey, TValue 是泛型类型形参（Parameter）。

3）在实际运用 List<T> 或者 Dictionary<TKEY, TValue> 时，总是需要将这些 Parameters 指定为特定的类型，比如 List<String>, Dictionary<String, int>，则这些处于 Parameter 位置上的类型（string, int），就是泛型类型实参（Arguments）。

4）如果泛型类型定义中的所有 Parameters 都被替换为 Arguments 的话，就被称为封闭构造类型；

5）否则，只要还有任何一个 Parameter 没有被替换，就是开放构造类型。

泛型方法，与泛型类型类似，也有类似的几个术语。（参见 System.Reflection.MethodBase.IsGenericMethod 的文档中）

在研究这个问题之前，我从来没有区分过 Parameter 和 Argument 这两个英语词，都认为是“参数”，这次总算明白，Parameter 是“形参”，Argument 是“实参”。我认为搞清楚形参和实参，对理解较复杂的泛型是很重要的。.NET Framework SDK 的文档在这方面做的不够好，很多地方都翻译为“参数”，有时就需要对照英文原文来区分到底是 Parameter 还是 Argument。

上面所说的都是简单的情形。复杂的情况比如说嵌套：对于一个 Dictionary<TKey, TValue>，TKey 指定为 string，TValue 指定为另一个 List<T> 类型，就构成了一个嵌套的 Dictionary<String, List<T>>。

再比如说，Parameter 的相对性：这点不太好理解。比如 Type.GenericParameterPosition 属性中给出个这个例子：

public class B<T, U> { }
public class A<V>
{
    public B<V, X> GetSomething<X>()
    {
        return new B<V, X>();
    }
}

其中的红色部分 B<V, X>，V 的 GenericParameterPosition = 0，因为它是其所属的泛型类 A<V> 的第一个形参；X 的 GenericParameterPosition 也 = 0，因为它是其所属的泛型方法 GetSomething<X> 的第一个形参。而 X 对于泛型方法 GetSomething<X> 来说，其实是一个“已经确定了的”类型。

关于泛型，还需要考虑约束的问题，每一个泛型形参，可以有五种类型的约束约束，即：class，struct，new(), 基类型约束，接口约束，裸约束。（详见 C# 语言参考）其中裸约束可以认为是基类型约束的一个特例。

NDoc 的工作原理大体是：先对程序集进行反射，收集所需要的信息，生成一个中间 XML 格式；然后交给 XSLT 转换为 HTML 页面。

网络中目前有几个 NDoc 修改版，试图解决对泛型的支持（比如：Jonas 的版本），但基本上都是在原有 XML 格式的基础上，作了一些 HACK。可以说只能应付简单意义的泛型类型，不能应对实际运用中可能出现的复杂情形。

为了从根本上全面支持泛型，就必须修改这个 XML 格式，让它在每个角落都支持泛型。在这个 XML Scheme 里面，我首先添加了一个名为 type 的 Complex Type，如下图所示：

以我目前的“想象力”，这个图应该可以包容 99.99% 可能出现的情况了吧？

好了，先写这么多，找到了 Ninputer 的 VBF 类库。这个库中大量使用了泛型，而且 Ninputer 的注释也比较完备。我将用这个类库作为检验 NDoc 是否全面支持泛型的测试实例。另外，我也在阅读 Ninputer 的泛型“专题”，不断的矫正自己的思路。

posted on 2006-09-07 21:29:00 by percyboy  评论(2) 阅读(6332)

NDoc Reloading ...

我关于 BuildProvider 的系列介绍还没有写新的文章，是因为我最近在研究 NDoc 的代码，已经将核心部分的代码理清了思路。然后我做了一个决定：捡起 Kevin 丢下的接力棒，将 NDoc 进行下去！

我的一个短期计划是：在十一假期之后的一个时间，发布第一个 Beta 2.0 版本，在这个版本中，预定的 features 大致如下：

1）文档引擎：暂时缩编为 XML 和 MSDN 两种，以便于集中精力。

2）.NET 2.0 支持：希望实现对泛型类型和泛型方法的全面支持，对可空类型的支持等。

3）全球化：NDoc 现有的版本很少考虑全球化的问题，此次整理将梳理核心代码，将区域化文本提取到资源文件中。第一个发布版本可能只有英语，但已经 ready to localize。（如果进展顺利、时间许可的情况下，也可能在第一个发布版本中就同步发布简体中文资源。）

较远期的计划：

1）文档引擎方面：

将主要完善 XML 和 MSDN 两种文档引擎。其中，MSDN 文档引擎，将同时支持 .NET 1.x / 2.0 / Mono 三种类库文档样式；另一方面，同时支持网页，HTML Help 1.x （*.CHM）和 Microsoft Help 2 三种输出格式。

其他的文档引擎，将交给其他有兴趣的开发者维护。如果没有足够的关注，则可能会被废弃。

2）实现在 .NET 1.x / 2.0 / Mono 不同平台下的编译；

3）全球化支持，将包括两层含义：

一方面是程序界面的全球化，一方面是文档样式（比如那些静态文本等）的全球化。希望支持九种语言：en （英语）, fr （法语）, de （德语）, it （意大利语）, es （西班牙语）, ko （朝鲜语）, ja （日语）, zh-CHS （简体中文）, zh-CHT （繁体中文），分别对应 .NET Framework SDK 所支持的九种本地化版本。当然，这个愿望还需要其他国家/地区的开发者来完成。

4）其他需要完善的细节。（比如 NDoc 当前版本对数组的支持不够好，等等）

此项目在 SourceForge.net 站点注册，项目名定为 NDoc Reloaded （嗯，现在还在 Reloading，呵呵）。如果可以的话，请给我一些鼓励和耐心：

http://sourceforge.net/projects/ndoc-reloaded/

http://ndoc-reloaded.sourceforge.net/

由于换工作的原因，没能按原定计划完成第一个版本，请各位原谅！

posted on 2006-09-05 23:16:00 by percyboy  评论(20) 阅读(6736)