Cwin1.0用户手册第一部分：介绍与快速起步

Cwin 是什么？

Cwin 的全称为 Core Window ，开发基于 JDK1.5 。其实到目前为止，这个项目还远远够不上用 Core 来修饰。对于已有系统， Cwin 是一个便捷实用的 CRUD 插件。可以嵌入在任何支持 Servlet 的 Java Web 应用中。对于中小型应用而言， Cwin 可作为系统的基础架构。 Cwin 可以大大减少简单繁杂的劳动，从而将精力放在核心业务的开发上来。因为使用 Cwin 完成功能将不需要编写任何的代码 (XML 配置除外 ) 。

Cwin 的核心概念是 Window 。那么，什么是一个 Window 呢？比如一个 User 的查询与编辑功能就可以配置为一个 Window 。这个 Window 将可以完成 User 的 CURD 操作。包含查询、排序、分页展示、验证等等完备的功能。

Cwin 的目的

Cwin 的目的，为了使 Java 的 Web 开发人员能从简单繁杂的劳动中解脱出来。比如单表操作、简单的基础数据维护操作、数据查询操作。我们都知道这些功能都很简单，但是麻雀虽小，五脏（ CRUD 四个操作、加上验证、分页、查询等等）俱全，这些工作是系统中是很让人头疼的部分，因为大部分代码都在 COPY 或者使用代码生成器生成。开发人员哼哧哼哧弄完之后还得对功能进行各种测试。而 Cwin 力图使这些操作完全地自动化。事实上，现在 Cwin 已经可以在不写入任何代码的情况下自动配置好这些功能。

Cwin 的来源

项目最早可追朔到 2006 年 9 月份，现在的源码中还有些代码就是从那时积累起来的。当时我想如果能生成数据表的 CRUD 界面，给我们的业务人员使用，这样就可以不用为每一张表提供一套操作页面了。就像一个数据库工具一样，可以编辑里面的数据。但这个项目最终无疾而终。在 07 年初的一个项目中，涉及到了一个新的领域，这样有许多基础表数据需要录入。让我为每一张表都提供几个界面来做数据录入工作吗？我的天哪，这是一项非常困难的工作，枯燥乏味并且时间也不允许。于是我把以前的代码找出来，做了些修改，就开始用上了。这个时候这些代码生存在 Spring|Struts|Hibernate 的框架中间。使用 DI 与 Action 配置可以简单地提供扩展性。

从 08 年开始，面对的是 JSP/Servlet 经典组合开发的系统。经常会有改动，大部分是后台管理操作：简单的 CRUD 与简单的查询表格展示。系统提供了代码生成器，但其功能很有限。为了使用生成的代码，改动量相当大。于是我再一次陷入到这种困境当中。但我也没有想过要使用我以前的代码来完成这些工作，原因有两点：一是我的代码嵌入在 SSH 的框架组合中，无法单独把某个部分拿出来使用。二是工作确实挺忙，没有时间来整理，甚至忘了有这么个项目挂在 GoogleCode 上。

直到有一天我突然想起我还有这个项目没有维护。于是找回这个项目，跑起来。无意间注意到了一个大问题： Spring 与 Hibernate 组合的 Web 工程在我的电脑足足花了 20 秒才启动完毕。这与 JSP/Servlet 的项目启动时间 3 秒以内是无法相比的。忽然我有点不喜欢这个东西（ SSH ）。

恼于这一点，后来我认为我找到了一个不错的点子：以 Servlet 方式提供 CURD 的支持！这样可以大大地减少对其它框架的依赖。而且可以嵌入到现有的 WEB 应用系统中，这将是一个不错的卖点！而开发过程中服务器的重启只需要花费很少的时间，这个最初的目的，也达到了。这是 2008 年 7 月。将代码改为基于 SERVLET ，代码做了太多的修改，也花费了很多的时间。

Cwin的将来

Cwin并没有多大的野心，简单将是自始至终追求的原则。在下一个版本(1.1)中会考虑加入一些常用的Widget，比如说树形结构。也许还需要为查询结果加入导出到Excel的功能。
嗯，或许有一天，会有一个简单的CMS作为一个Cwin的衍生项目出现。或许......谁能知道呢？因为在前面，大家都有美好的生活。

Cwin 的特点

<!---->1． <!---->使用简单：表与字段定义在一个 XML 文件中。通过 ID 访问。

<!---->2． <!---->功能全面：对 HTML 控件全面的支持： Cwin 支持大部分的 HTML 控件配置与在线编辑器 (fckeditor) 的配置、文件上传。

<!---->3． <!---->自动的输入检查。验证条件可以比较灵活地配置。即使您不设置任何的条件 Cwin 也会根据数据库的字段属性进行输入检查。

<!---->4． <!---->灵活性： Cwin 可以使用 URL 对每一个页面单独进行引用。 Cwin 支持动态 URL 的配置。这样 Cwin 中配置的 Window 也可以通过 URL 得以嵌入在其实比较复杂的功能中。

<!---->5． <!---->贴心小特点：

<!---->A.      <!---->对于 Value-Desc 方式的值。比如用户表的用户类型字段。 Cwin 在表格展示时自动展示为 Desc 而不是得对照数据字典才能慬的 Value 。

<!---->B.      <!---->Window 可以 动态接收参数作为 window 的条件与默认值。比如我们现在有一个 Window ： user 。现在我需要有一个功能，按用户类型编辑用户。就可以加入参数 类似 userType=value 。即可。

<!---->C.     <!---->Cwin 支持系统变量的插入。默认的系统变量只有一个： _CWIN_SYS_TIME （系统时间）。我们在 Window 　 user 中可以使用到他。因为 user 的 CreateTime 需要记录系统时间。 modifyTime 也需要记录修改时间。如果用户有其它的系统变量，比如操作人。那么用户将需要扩展 Cwin 的一个类。覆盖某个方法即可。

<!---->D.     <!---->Cwin 多种的列输出配置， hidden （面对长字段可以隐藏不在表格中展示，因为表格装不下那么长）， pop （面对长字段，可以让经以 POP 方式跳出来）， link ：可以通过此列链接到其它的功能，这个功能非常地实用。 None ：在表格中不显示此列，比如主键列。

<!---->E.      <!---->Cwin 统一地管理各种与此下拉列表与 HTML 控件。从此不必在各个页面之间 COPY 下拉列表了。也不必 COPY 各个字段的验证代码了。

<!---->F.      <!---->如果您使用 Cwin 。那么 Cwin 的配置文件可以作为一份不错的数据库文档。因为修改的每一个字段都必须修改配置文件才能得到体现。这样，这份文档总是最新的！

<!---->6． <!---->较小的对第三方组件的依赖性，可以作为 WEB 开发的开发插件来使用。

Cwin 的依赖包：　

Jabsorb ：如果需要使用配置引用控件功能。

Commons-upload ：如果需要使用文件上传功能）。

Fckeditor ： ( 如果需要使用在线编辑器 ) 。

Slf4j ：（ Fckeditor 的日志工具，也是 Cwin 的日志工具）

Cwin 包含的组件

Cwin 包含的独立发布的组件有三个：

<!---->1.      <!---->DbAss ：数据库助手工具类包。支持 JDK1.5 以上。

DbAss 是一个强大的使用泛型的 JDBC 工具包。包含了通用的分页查询方案与基于注释的事务管理方案。一个通用的 DAO 提供了许多不错的数据库操作方法。对于一般应用而言，这个通用 DAO 已经够用了。目前版本支持的数据库有： Oracle, MSSQL,MySql,PostgreSql 。

详情请查看本手册的 DBASS 部分。

<!---->2.      <!---->JavaScript 验证与表单验证 API 。特点是实用、体积小、不依赖于任何第三方 API 。

<!---->3.      <!---->JavaScript 日期选择器。特点是实用、体积小、不依赖于任何第三方 API 。

Cwin 的不足之处

1. 由于 Cwin 的界面全部是自动生成。这样对界面要求比较高的场合就不大适用。 Cwin 的样式全部在一个 CSS 文件中，可以通过 Window 的一个属性来替换 CSS 。但这也有一定的限制。 因为这个版本的 CSS 可以改变其样式，而难以改变其布局与装饰。但从另一方面而言，需要美工来开发页面的事情总不能轻而易举地完成。 Cwin 到目前为止还没有一个较好的模板机制来解决这个问题。

所以就目前而言， Cwin 用于对界面要求不高的应用。是非常有帮助的。

2.Cwin 目前不支持组合主键。所以不能用于使用组合主键的表。

快速起步

下载 Cwin

可以在这个页面下载到最新的 Cwin 版本：

http://code.google.com/p/cwin/downloads/list

 

建议您下载 cwin_all_1.0.zip

解压之后您可以看见有两个文件夹。一个是 cwin ，一个是 dbass 。我们可以抛开 dbass 不管，因为他只是一个独立的组件。 Cwin 中包含了 dbass 。当然如果您想使用 DBASS ，可以查看手册的 DBASS 部分。

打开 cwin 文件夹。

Cwin 目录中是 Cwin 要用到的 WEB 内容与配置。

depends_lib 目录中是 Cwin 依赖的 jar 包。

 

将 Cwin 集成到系统中

<!---->1． <!---->将 cwin 目录 Copy 到您的 WEB Content 目录下，如果很巧。您的 WEB 工程中已经有了 Cwin 文件夹。那么为了防止冲突，请您为 Cwin 换个名字。比如 Corewin 。请记住新名字，因为新名字将要在配置中进行指定。

<!---->2． <!---->将 lib 下的 cwin_all.jar 与 Depend_lib 下的依赖包 Copy 到您的 Web-INF 目录下。这样就完成了集成的第一步。接下来是配置。

配置

web.xml CwinServlet 与相关 Servlet 的配置。

<!-- 初始 Servlet CwinServlet -->
	<servlet>
		<servlet-name>Cwin</servlet-name>
		<servlet-class>cn.antia.cwin.CwinServlet</servlet-class>
		<init-param>
			<param-name>web_directory</param-name>
			<param-value>cwin</param-value>
		</init-param>
        <init-param>
            <param-name>mapping_url</param-name>
			<param-value>cwin</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
	</servlet>
    <!-- JSON_RPC Servlet -->
    <servlet>
		<servlet-name>JSONRPC</servlet-name>
		<servlet-class>org.jabsorb.JSONRPCServlet</servlet-class>
		<init-param>
			<param-name>gzip_threshold</param-name>
			<param-value>200</param-value>
		</init-param>
	</servlet>
    <!-- FCKEditor ConnectorServlet -->
	<servlet>
		<servlet-name>Connector</servlet-name>
		<servlet-class>
			net.fckeditor.connector.ConnectorServlet
		</servlet-class>
		<load-on-startup>1</load-on-startup>
	</servlet>
    <servlet-mapping>
		<servlet-name>JSONRPC</servlet-name>
		<url-pattern>/JSON-RPC</url-pattern>
	</servlet-mapping>
    <servlet-mapping>
		<servlet-name>Cwin</servlet-name>
		<url-pattern>/cwin</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Connector</servlet-name>
		<url-pattern>
			/cwin/fckeditor/editor/filemanager/connectors/*
		</url-pattern>
	</servlet-mapping>

 

       您已经将 cwin 目录重命名，那么您需要在 CwinServlet 的配置上指定您的目录。否则这一段配置不需要修改。

       Servlet 的映射将处理 /cwin 的请求。

       如果您需要 Fckeditor 的支持，请保留 FCKEditor ConnectorServlet 的配置。

       如果您需要 Jabsorb 的支持，动态引入定义在字段中的属性，请保留 JSONRPC 的配置。

       将以上配置 Copy 到 web.xml 中即可。

       请注意：如果您将 cwin 重新命名，请将修改 JSONRPC Servlet 的 URL 映射 (/cwin/fckeditor/editor/filemanager/connectors/*) 的 cwin 改为新名。

       如果您重新指定了 CwinServlet 的映射 URL ，请同时将 CwinServlet 的参数 mapping_url 改为新名。

数据源配置

在 cwin.jar 中找到一个 dbass.properties 的文件。因为 Cwin 就是由它来定义数据源的。实际上这是属于 DBASS 组件的配置。不过这对于您来说都没什么关系。工程跑起来了就大功造成了。配置文件有以下的选项与配置说明。

dbtype: 数据库类型，支持 mysql,oracle,mssql,postgre

dataSource: 数据源，可以有两种配置方式可以选择。一种是使用 JNDI 配置的数据源，另一种是使用 cwin 提供的数据源的属性进行配置：

dataSource   :      JNDI 　中的数据源，如果配置了此项，以下关于数据源的配置将无效。

driver            :      JDBC 　驱动

user              :      用户

password      :      密码

url          :      URL ，数据库连接串

maxIdle  :      最大空闲连接

maxWait :      最大等等时间

maxActive     :      最大活动的连接

 

相信对于 Java 的 Web 开发人员来说，这个配置文件实在太熟悉了，我也就不多说。配置完以后将其放回 jar 包就算配置完成了。

体验 Cwin

赶紧启动您的工程吧。好了，启动成功了吗？

如果您的数据库中已经有表比如。 User 。

如果您的 CwinServlet 映射 URl 与 Tomcat 或是 Resin 端口没有过修改，那么您可以使用类似下面的 URL 来查看您的 User 表。

http://localhost:8080/cwin/cwin?_CWIN_ID=user

回车试试，看到了什么？是不是眼前一亮呢？好了，恭喜您，走上了 Cwin 的第一步。如果您仅仅是在看文档，那么我来告诉您吧。浏览器上展示了一个表数据浏览窗口。

<!----><!----><!---->

 

现在，为了能使我们共同来了解 Cwin ，请您用下面的 SQL ，来创建一张新的表 user_demo 。开始 Cwin 之旅。

注意：本文档的示例数据库为 mysql5.0

CREATE TABLE `user_demo` (

  `id` int(11) NOT NULL auto_increment,

  `login_name` varchar(20) NOT NULL,

  `email` varchar(80) NOT NULL,

  `password` varchar(255) NOT NULL,

  `type` varchar(255) NOT NULL default '1',

  `create_time` datetime default NULL,

  `intro` varchar(255) default NULL,

  PRIMARY KEY  (`id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8;

 

现在，将我们的地址栏换成

http://localhost:8080/cwin/cwin?_CWIN_ID=user_demo

好了，如果您已经看到效果了，我们来看看 cwin 目录下的 config 文件夹，找到 table.xml 。看到了吗，我们的页面就是在这里定义的。

下一章，我们将进入 Cwin 的配置第一部分，讲到查询与排序、输入与输出、主键生成等等的配置：深入 Table 的配置。

哦，对了。请您看看 cwin 目录下的 demo 文件夹。本手册的 Sql 与 JSP 都在那里面了。