dorado 5 快速入门 v1.1.doc

DORADO 5 快速入门 V1.1DORADO 5快速入门V1.1-初级培训教程-BSTEK2007年6月1.前言52.下载以及安装72.1.配置Java运行环境72.2.配置JAVA_HOME环境变量72.3.下载并解开dorado5开发包112.4.安装dorado5112.5.运行范例132.6.相关资源163.创建dorado工程173.1.创建工程173.2.配置数据源193.2.1.配置datasource.xml193.2.2.copy hsql.jar223.2.3.连接测试233.2.4.修改setting.xml文件234.制作登录界面254.1.概述254.2.视图模型配置254.2.1.添加视图模型对象254.2.2.添加dataset对象264.2.3.添加AutoForm284.2.4.添加label和button314.2.5.AutoForm引入label和button344.2.6.添加RPCCommand对象354.2.7.添加视图模型实现类374.3.JSP设计404.4.功能增强444.4.1.快捷键处理444.4.2.验证成功或失败的处理465.制作主框架界面495.1.主界面说明495.2.开发步骤505.2.1.新建视图模型505.2.2.添加菜单对象505.2.3.新建MenuBar525.2.4.新建OutlookBar545.2.5.创建JSP565.2.6.预览595.2.7.添加菜单连接功能606.组织结构维护636.1.部门维护636.1.1.简述636.1.2.新建视图模型646.1.3.创建数据集（Dataset）656.1.4.创建数据表格（DataTable）706.1.5.创建分页导航条(PagePilot)716.1.6.创建数据导航条(DataPilot)726.1.7.创建自动表单（AutoForm）736.1.8.创建数据更新命令（UpdateCommand）756.1.9.创建按钮对象(Button)776.1.10.特别说明796.1.11.创建JSP836.1.12.查看效果846.2.员工信息维护876.2.1.简述876.2.2.步骤一：添加视图模型886.2.3.步骤二：定义员工记录集896.2.4.步骤三：添加基本的组件916.2.5.步骤四：添加自定义部门下拉框976.2.6.步骤五：创建员工维护界面的JSP1076.2.7.步骤六：功能完善1096.2.8.步骤七：Excel数据导出1116.3.综合管理1156.3.1.简述1156.3.2.实现1156.3.3.组件添加1256.3.4.浏览页面效果1417.发布工程1437.1.打包1437.2.发布1447.3.发布成功与否校验1448.附录1478.1.工程配置参数说明1478.2.HSQL数据库介绍1478.2.1.简介1478.2.2.使用HSQL数据库1478.2.3.hsql使用参考1488.3.视图模型基本概念以及实现类说明149第 153 页 共 153 页第一章 前言1. 前言DORADO5是BSTEK公司推出的一种展现中间件技术，BSTEK借助于自己在J2EE领域的长期经验积累，以及对AJAX技术的敏锐把握和创造性的使用之后，持续的在展现中间件领域推出自己的品牌产品，其中DORADO5是继EXTRA3,DORADO4之后的又一个里程碑式的产品，它把人们引入了WEB2.0时代。当今更多的业务系统选择Brower/Server架构，日益复杂的业务需求使Web界面与交互操作便捷也越来越复杂，而带来一个两难选择。一方面，此时用户已习惯享受随时随地通过浏览器访问并操作业务系统这种便利，而提出操作体验的更高要求，特别是用户经常以之前使用过的C/S版的软件系统的体验为基准，抱怨B/S系统难用，进而造成用户满意度下降。另一方面开发者在实现交互性复杂的用户界面时，往往需付出极其繁重的、低效而重复的劳动，进而造成开发周期长、开发成本过高。或者牺牲开发成本来保持用户满意度，或者牺牲用户满意度来保持开发成本，面对这个两难选择似乎只能取其一，而随着dorado 5版本的推出，出现了一个新解：提高用户满意度同时降低开发成本，快速响应需求变化。dorado音，英文指旗鱼、剑鱼，天文学中为剑鱼座，是海洋里游得最快的大型鱼类，时速可达120公里以上，它极其迅速而优雅地畅游于蓝色的海洋中。用dorado来命名产品的寓意是：Web应用开发迅速，Web应用程序优雅而交互性极强。dorado是下一代web应用的引擎平台，有效增进Web应用的用户体验与交互效率，并大幅提升开发效率。基于dorado可以快速创建Rich Internet Application与AJAX应用，使B/S应用保留C/S应用的优势。dorado 填补了J2EE架构中表述业务交互的架构空白，以标准化自动化的作业方式，低成本、快速实现业务交互层（包括用户界面，人机交互，界面与后台交互等）的用户需求，快速响应需求变化，同时提高用户业务操作的效率。近两年来，在AJAX技术的推波助澜之下，dorado5的开发者群体也在日益扩大。本书通过一个实际的项目引领初学者快速的了解和掌握dorado编程。相信对于初学者有很好的参考价值和指导意义。由于编撰的工作量很大，在文档后的很长一段时间内我们仍会尝试不断的对其进行完善和补充。所以，当您有部分疑问无法从本文中找到答案时，您可以关注一下对此文档的后续更新。或者您对本文档的有任何意见或建议，也请通过与我们联系。阅读群体本书属于dorado快速入门系列中的第一本，适合于初次接触dorado的技术人员的自习，也可用于正式的教学，通过本书的学习可以使技术人员初步掌握dorado的基本开发和使用技巧，从而可以快速的搭建小型项目，对于在校的学生来说也可以通过本书的基本dorado技术的积累完成自己的毕业设计和帮组小型私营企业快速的实现信息化建设。对于小型项目的开发和在校学生的使用建议申请BSTEK的1CPU免费计划，详情请登陆BSTEK的官方网站：/以及参看BBS说明：87/bbs/forums/show/10.page 第二章 安装2. 下载以及安装2.1. 配置Java运行环境通过如下地址获取JDK开发包：/javase/downloads/index_jdk5.jsp将下载的开发包解压缩到本地非中文名称的目录中，如本机的D:/java/jdk/1.5：2.2. 配置JAVA_HOME环境变量打开我的电脑的属性窗口：切换到高级标签页并选择环境变量按钮：在系统环境变量列表中选择新建按钮：设定新增的变量名为JAVA_HOME并设定其变量值为JDK的安装目录。本范例为：D:javajdk1.5。JDK目录如下图：2.3. 下载并解开dorado5开发包通过如下的地址获取dorado5的开发包：87/download/dorado/dorado5.zip将下载的zip文件解压缩到本地非中文名称的目录中，如本机的D:/java/develop/dorado5：2.4. 安装dorado5在确保系统已经配置过JAVA_HOME的前提下，并双击运行dorado 5开发包中的setup.bat文件，该文件进行dorado5开发包的文件初始化工作。（特别声明：绿色食品，setup.bat的所有操作都是针对开发包所在的目录作初始化工作，不会对该目录之外的内容进行修改。）首先会打开一个命令控制台，要你确认是否执行初始化的工作：按任意键继续初始化工作：这时候系统会在桌面上自动的生成一个dordo5 studio的快捷启动图表，并在控制台中出现让你选择是否直接启动dorado的集成开发环境，也就是dorado5的studio。以下统称studio。如果选择y并按回车键确认打开studio，可以看到下图：该图的最上方窗体的标题表示当前Studio的版本信息，如本例为：Dorado studio 5.0 061229.1512含义为5.0版本，06年12月29号15:12分打包。另外我们还可以在当前的studio中出现一个默认的工程：doradosample。该范例由BSTEK默认提供，用以作产品特性的一个综合展示。当然也包含一些开发技巧在里面。可以参考学习。2.5. 运行范例选择下图studio中的红圈包含的按钮启动服务：服务启动后可以在上图的最下方，也就是studio中的日志信息控制台中可以看到dorado服务启动的监测信息：dorado Starting Service. . .dorado Using JDOM 0.9 as XML processordorado Configure loader: mon.fileloader.PathFileLoaderdorado Configure root: D:/dorado5/sample/homedorado Source loader: mon.fileloader.PathFileLoaderdorado Source root: D:/dorado5/sample/srcdorado Loading setting.xml.dorado Initializing Logger.dorado Initializing Performance Moniter.dorado Loading user-config.xml.dorado Loading mapping/global.map.xml.dorado Loading mapping/dorado.map.xml.dorado Loading mapping/sample.map.xml.dorado Initializing Velocity Service.dorado Initializing Connection Pool.dorado Testing Connection doradosample.dorado Initializing Module Manager.dorado Service Started!dorado Version: dorado-5.0 070319.1843 (Unregistered)这是dorado工程启动时的一个自检过程，如果在第一行代码：dorado Starting Service. . .与倒数第二行代码之间：dorado Service Started!没有任何异常信息，就表示该项目启动已经正常。Studio自带的doradosample在服务启动后会自动利用系统默认的浏览器打开该项目的首页，如下：上图中右下角的四个图标表示目前版本的dorado可以支持的浏览器类型。接下来你就可以花点时间快速预览一下doradosample中的例子，尤其需要观看系统中的文字部分，如下图的红圈内容：通过快速的查看doradosample中的例子以及上图中红圈部分中包含的文字说明我们可以快速的感受dorado的产品特效，以及部分的开发理念。2.6. 相关资源目前学习dorado可以获得的主要相关资源如下：BBS：87/bbs技术支持电话：86-21-64260839（上海）86-10-51292870（北京）官方网站：主要技术文章：文档下载地址开发包的doc目录中开发包的doc目录中87/download/dorado/dorado5UserGuide.zip87/download/dorado/dorado5ComponentsGuide.zip 87/download/dorado/dorado5PerformanceGuide.zip 第三章 创建工程3. 创建dorado工程快速的浏览过doradosample之后，接下来就该实际体验一下整个开发过程了，本文接下来的章节我们按照一个小型的HR项目开发过程，逐步展示dorado的开发方式。3.1. 创建工程打开Dorado Studio，在File菜单中，选择Create a New Project。得到如下的向导视图:图表 1选择合适的保存路径（注意不要将项目保存到中文目录下），并在文件名中输入hr，点保存(本机为D:DoradoDemohr)。出现项目创建向导。图表 2在向导窗口的Main标签页中我们可以设置Local Home, Source Home , WebRoot Path, Server, Port ,Web Application几个参数（通过编辑框后面的快捷按钮修改）。可以根据需求对Project参数进行修改。不过对于第一次使用本系统的你来说直接OK即可。向导窗口参数的详细说明参考附录一：工程配置参数说明。其他标签页的配置建议默认取值。点ok，接下来Studio会自动创建工程。最终界面如下：3.2. 配置数据源项目建立后，接下来配置数据源。3.2.1. 配置datasource.xml双击打开工程树节点Configures下的datasource节点，系统会打开数据源配置界面，如下图。图 1单击add按钮增加一个数据源。命名为hrJDBC。图表 3选择OK按钮进入下一步，接下来配置数据源hrJDBC的参数。图表 4在这个实例中，我们使用hsql作为数据库(hsql是一个文件型的数据库，相关说明参考附录二：HSQL数据库介绍)，并把Dorado Sample中的数据库移植过来使用。本机的做法为：拷贝dorado开发包安装目录中sampledata目录到d:DoradoDemohr目录下,并将data/hsqldb中的所有文件名修改为hr,扩展名不变：hrJDBC参数设置的说明：参数说明Name数据源名称，本例为hrJDBCDialect数据源使用的方言，本例为com.bstek.dorado.data.dialect.HSQLDBDialectDriverJdbc Driver配置，本例为com.hsqldb.jdbcDriverUrl数据库位置设定，本例为jdbc:hsqldb:file:D:/DoradoDemo/hr/data/hsqldb/hrUser数据库登录用户名，本例为saPassword数据库登录密码，本例为空DB CharSet数据所采用的编码格式，本例为空在该配置中尤其注意设置Url参数的路径位置为你本机demo数据库的路径。参数填写完毕后，点ok。我们可以看到一个新的数据源已经建立好了。【图表 5】图表 63.2.2. copy hsql.jar接下来验证配置好的数据源是否已经可用。由于dorado在启动时会自动的检查datasource.xml中配置好的数据源，我们可以利用这一特性测试数据源配置是否正确。保存所有的修改之后，选择菜单Project下的Start Up Service启动studio集成的服务。注意看studio下方的控制台信息，我们可以看到如下的异常信息：mons.dbcp.SQLNestedException: Cannot load JDBC driver class org.hsqldb.jdbcDriver, cause: java.lang.ClassNotFoundException: org.hsqldb.jdbcDriver该错误表示系统加载时无法找到org.hsqldb.jdbcDriver文件，我们找到dorado开发包的安装目录，在sample/web/web-inf/lib目录下找到hsqldb.jar文件。这是HSQL数据库数据链接专用的JDBC驱动包，我们需要将它放在新建工程hr的web/web-inf/lib下，本机为D:/DoradoDemo/hr/web/web-inf/lib。3.2.3. 连接测试由于前面我们启动了服务，并在数据连接时发生了错误。现在我们选择菜单Project下的Shut Down Service首先关闭当前已经启动的系统服务，并重新选择Start Up Service启动服务，来测试数据库链接是否成功。服务启动之后，如果我们可以在启动日志中看到如下的信息：dorado Testing Connection hrJDBC.如果看到这个日志输出，说明系统测试hrJDBC数据源已经成功。另外一种测试方法是我们在服务启动之后，选择datasource配置界面中的hrJDBC数据源，并单击该界面中的Validate按钮来验证，如果数据源配置正确则会弹出成功的窗口。如下图：图表 73.2.4. 修改setting.xml文件为了方便以后的开发，我们需要把hrJDBC数据源配置到项目树的configures节点下的setting配置文件中。双击打开setting文件，并在其第一个配置参数中设定它的value值为hrJDBC：该属性用以设定当前工程中的默认数据源为hrJDBC。图例：图表 8第四章 登录界面4. 制作登录界面4.1. 概述在实际开发这个项目的基本功能页面之前，我们需要先设计这个项目的登录界面。界面效果如下:实现思想：利用AJAX技术通过dorado的RPCCommand组件完成登录验证。并根据验证结果由RPCCommand负责页面的跳转或显示错误信息提示。4.2. 视图模型配置4.2.1. 添加视图模型对象首先，在src中添加目录combstekdoradodemohr，并在hr目录下新建Login视图模型，视图模型添加办法如下：图表 9选择hr并打开右键菜单，选择new中的View图标。并将该View命名为Login。视图模型的详细说明参考附录三：视图模型基本概念说明以及视图模型实现类说明。4.2.2. 添加dataset对象在Login视图模型中的Datasets节点下创建一个FormDataset（dsLogin）来保存用户登录时输入的用户名和密码信息，添加方法如下，选择datasets节点，并利用左侧的快捷按钮选择第四个dataset快捷按钮：图表 10该快捷按钮会自动在datasets节点下添加FormDataset类型的Dataset对象。我们修改新增的dataset的id为dsLogin。并展开dsLogin节点，选择Fields节点，利用快捷按钮添加两个新的Field对象。快捷按钮如下：新加的field对象的属性设置分别为用户名id和密码 pwd,数据类型(dataType)都设置为string。最终结果如下：图 24.2.3. 添加AutoForm选择controls节点对象，并利用左侧快捷工具栏上的快捷按钮添加AutoForm组件：将新增的AutoForm对象的id属性修改为frmLogin。并设定frmLogin的Dataset属性为dsLogin。frmLogin的基本属性设置如下：图表 11保存前面所作的修改之后，利用AutoForm提供Auto Create Elements快捷菜单自动导入dsLogin中的信息，方法如下，选择frmLogin对象，并打开右键菜单，找到Auto create elements：图表 12该菜单会自动的利用dsLogin的字段生成其内部元素，展开frmLogin对象，可以看到一个元素，这是自动生成的对象，我们设定自动生成的FormGroup的columnCount属性为“1”，title属性为“登录”。如下图：图表 134.2.4. 添加label和button重新选择Controls节点，并利用左侧的快捷按钮添加label组件，如下：增加一个label组件，并设定id为labelDesc,text属性为“* 用户名 : admin 密码 : admin”。同上方式添加一个Button组件，如下：并设定新增按钮的id为btnLoing,width为60px,value为“登录”。添加后系统效果如下：4.2.5. AutoForm引入label和button下一步我们利用AutoForm的容器功能，使将新增的两个组件对象引入到AutoForm中。选择frmLogin的节点，并利用快捷按钮添加两个Custom Element：设定新增的两个Custom Element的属性如下:图表 14其中的controlId属性分贝设定为btnLogin，labelDesc，使得这两个自定义的元素与前面添加的Label以及按钮绑定。4.2.6. 添加RPCCommand对象增加一个RPCCommand（cmdLogin），设置method属性为loginRPC,表示该Command要调用的远程方法名为loginRPC。如下图:图表 15在Studio的Login视图模型中选择编辑界面下方的标签页Events Inspector切换到事件视图:选择cmdLogin对象，并选择右侧的事件列表中的beforeExecute事件：图表 16双击打开事件编辑器，并从dsLogin中取出用户名id和密码pwd放到cmdLogin的parameters中。var id = dsLogin.getValue(id);var pwd = dsLogin.getValue(pwd);command.parameters().setValue(id,id);command.parameters().setValue(pwd,pwd);前面我们把输入参数（用户名和密码）保存在RPCCommand中，并设定按钮对象(btnLogin)的command属性为cmdLogin。其他属性设定如下图：图 3这样按钮被单击时，按钮会自动地执行cmdLogin的命令，并执行beforeExecute方法实现参数赋值操作，并利用Dorado提供的远程方法调用与服务器交互，下一步我们就是要在服务器定义一个java类，接受该远程调用并实现登陆验证。4.2.7. 添加视图模型实现类切换到Properties Inspector标签页，并选择Login视图模型的根节点，并利用右键的快捷菜单生成ViewModel的实现类，命名为LoginViewModel。图 4选择Options中的Sample_RPC_Method，点ok。这样向导会自动的在com.bstek.dorado.demo.hr中生成LoginViewModel.java文件，并同时修改Login视图模型的clazz属性为com.bstek.dorado.demo.hr.LoginViewModel，使的新增的java类与Login视图模型相关联：该类在dorado中的术语是视图模型实现类。基本概念参考附录三：视图模型基本概念以及实现类说明。在新生成的视图模型实现类中将Sample_PRC_Method方法名称修改为loginRPC。然后通过下列代码实现用户名和密码的验证。代码示范：public void loginRPC(ParameterSet parameters, ParameterSet outParameters)throws Exception /从输入参数中取出用户名和密码String user = parameters.getString(id);String password = parameters.getString(pwd); /验证用户名和密码 if (StringHelper.isNotEmpty(user) if (!dorado.equals(password) throw new Exception(password failure !); else throw new Exception(ID failure !); loginRPC方法通过该函数得参数parameters获取cmdLogin发送过来用户登录时输入的id以及pwd信息。该处的用户名以及密码校验我们采用比较简单的判断处理。实际开发可灵活变通。4.3. JSP设计登录逻辑处理完成之后，还需要生成登录的JSP页面。下面我们利用视图模型提供的JSP生成向导生成登陆页面，方式如下：确保在视图模型处在Properties Insppector标签页上：Login视图模型中选中view（根节点），点左边的工具按钮（Generate a sample JSP）图 5出现生成JSP的向导窗口：图 6选择JSP的生成位置，我们选择web，点ok确定。图 7进入上图所示的布局选择对话框，使用默认选择，点ok按钮。此时系统会自动生成JSP页面，代码如下: JSP中通过如下的代码使它与我们创建的Login视图模型建立关联关系：删除标签，并调整JSP的页面布局如下: 其中的Layout为dorado提供的辅助布局的标签对象，该标签对象的详细说明可以参考。利用project菜单项下的Stut Down Service菜单停止当前的服务,并利用project菜单项的Start Up Service重新启动服务。在浏览器地址中输入:http:/localhost:8180/hr/login.jsp得到如下的界面：图 8这样我们就完成了一个简单的登录界面制作。4.4. 功能增强为了使登录界面的使用更为人性化，下面我们再来处理一些细节，比如：登陆界面支持快捷键处理：l 如输入用户名和密码之后按回车就直接执行登录操作；l 登录失败弹出错误提示信息；l 登陆成功就进入系统主界面；4.4.1. 快捷键处理下面我们利用编辑框的onKeyDown事件实现回车登陆：onKeyDown事件在DHTML中的解释为：当用户按下键盘按键时触发。下面我们直接获得frmLogin的编辑框，并定义onKeyDown事件，同时判断键盘码是否为13，表示回车事件，如果为回车事件则执行登陆RPC命令。AutoForm拥有自动生成界面元素的机制，这些界面元素细化到最终就是一些编辑框和label或按钮对象。上例中frmLogin中的pwd对象，最终在页面上生成的是一个id为：frmLogin_editor_pwd的编辑器。在这儿我们可以看到AutoForm生成界面编辑器的命名规范：AutoForm的ID+”_editor_”+element的name在Login视图模型中选中view（根目录），切换到事件视图：在View节点对应的事件列表中找到onLoad事件，并双击打开该事件的事件编辑器：其中加入如下的代码，用以给密码编辑框增加一个onKeyDown事件。/frmLogin_editor_pwd为密码编辑框对象frmLogin_editor_pwd.onKeyDown = function(event) /当按下回车键时 if (event.keyCode = 13) /调用postRecord()将编辑框中的数据更新到dsLogin中 dsLogin.postRecord(); /执行RPCCommand cmdLogin.execute(); 4.4.2. 验证成功或失败的处理用户登录成功后需要转到系统的主页面，失败后则要给出提示。切换到Login的Events Inspector视图中：选择cmdLogin对象，并找到事件列表中的onSuccess事件，双击打开事件编辑器，在其中增加跳转代码：/命令执行成功后进行页面跳转window.location.href = hr/main.jsp;失败后给出错误提示，该怎么处理呢？其实前面我们已经在视图模型的实现类(com.bstek.dorado.demo.hr.LoginViewModel)中的loginRPC方法的验证逻辑中处理过了，我们再次查看代码：如果用户名验证失败，则在loginRPC方法中直接抛出Exception，并在构造参数中设定自定义的异常信息：throw new Exception(ID failure !);界面执行效果如下：图 9Dorado自动地将用户自定义的异常信息在客户端抛出。如果密码验证失败，则也抛出一个自定义的Exceptionthrow new Exception(Password failure !);如果后台抛出Exception，则前台自动会弹出抛出的异常信息。 图 10第五章 制作主界面5. 制作主框架界面5.1. 主界面说明本系统的主界面功能菜单设计如下：系统人事管理报表管理查看我的信息分公司信息查询以及维护员工报表打印修改密码部门信息查询以及维护退出员工信息查询以及维护综合管理主界面中的界面风格如下：页面的最上方为菜单工具栏（MenuBar），左侧为OutlookBar样式的菜单。MenuBar与OutlookBar中显示的是上方菜单表格中的菜单。当用户点击某个菜单项的时候，系统会自动地将相关页面在右侧框架区域中出现。5.2. 开发步骤5.2.1. 新建视图模型在com.bstek.dorado.demo.hr目录下新建一个View用来作主框架页面（命名为Main）。创建方式参考Login视图模型的创建。5.2.2. 添加菜单对象选择controls节点，并添加Menu对象：修改新增的menu对象的id为menuHr，并在内部增加一系列的菜单项。菜单项的基本属性说明如下：属性说明name菜单的名称，请不要使用中文或特殊符号命名label菜单项会使用该属性作为显示菜单标题显示icon用于定义菜单项的图标，通过这个属性指定一个图标资源的URL效果如图：【图 11】图 11以下为menuHr的配置代码：5.2.3. 新建MenuBar选择controls节点，并添加Menu对象：将新增的MenuBar对象的id修改为menubarHr，并设定menu属性为menuHr。其他属性设置如下图：5.2.4. 新建OutlookBar选择controls节点，并添加OutlookBar对象：设定新增的OutlookBar的属性为outlookbarHr并设定menu属性为menuHr。【图 12】 图 125.2.5. 创建JSP到此为置止，主框架的大部分元素都完成了，下一步利用视图模型提供的JSP生成向导自动生成JSP页面。确保在视图模型处在Properties Insppector标签页上：Main视图模型中选中view（根节点），点左边的工具按钮（Generate a sample JSP）生成JSP：图表 17在JSP生成向导界面中：选择web目录，并单击旁边的New Folder按钮生成新的目录，命名为hr，并选中新增的hr目录，单击OK按钮，在hr目录下生成新的JSP页面： 下面我们利用dorado提供的布局管理器实现页面的快速布局:在标签的上方添加空行，并在光标定位在这个空行的时候。双击右侧的X-insert面板中的Layout(Border).并调整OutlookBar与MenuBar的位置:调整之后代码如下: 代码中新增了iframe对象frameHr，后面的各个菜单的功能界面将会在frameHr中打开。其中welcome.html为一个欢