DAO使用手册.doc

使用手册机 密 文件编号：使 用 手 册DaoFramework起 草 部 门：研发中心管 理 部 门：品管部撰 写 人：张神龙审 核 人： 批 准 人： 发 布 日 期： 编号章节名称修订内容简述修订日期修订前版本号修订后版本号修订人批准人1张神龙修订页目 录1功能简介42DAOConfig.xml文件的配置43系统的运作过程73.1系统如何初始化73.2上层应用如何执行任务74常规操作举例84.1select操作84.1.1在配置文件中如何配置84.1.2在程序中如何操作84.2insert操作94.2.1在配置文件中如何配置94.2.2在程序中如何操作104.3delete操作114.3.1在配置文件中如何配置114.3.2在程序中如何操作：124.4update操作124.4.1在配置文件中如何配置124.4.2在程序中如何操作135特殊操作如何做155.1如何对BLOB和CLOB字段进行读写操作155.2如何执行事务175.2.1使用事务执行器按批处理方式执行事务175.2.2上层应用使用DAO事务185.3如何执行PROCEDURE205.4上层应用如何使用DataSet类和DataRow类来取值215.5上层应用在外面使用通过DAO获取的数据库连接时的注意事项226原始接口函数说明236.1IBaseDAO函数说明236.2IDAO函数说明246.3DAOResult函数说明267样例程序287.1配置文档287.2源程序321功能简介实现通用的系统DAO任务执行程序框架，为应用系统的DAO层提供服务。具体原理就是：将所有的DAO层的操作根据其最终结果的类型细分为原子任务TASK（SELECT-查询任务，DELETE-删除任务，INSERT-插入任务，UPDATE-更新任务），每个任务的SQL语句全部配置在CONFIG文件中，框架程序读取CONFIG文件中配置的任务，调用底层的JDBC程序操作物理数据库，最终完成任务，返回执行结果。具体提供以下功能：1 传入任务的CONFIG文件给框架，完成任务初始化。2 上层应用系统传入任务的具体ID和参数给框架，框架根据配置的任务参数执行任务。任务分为以下几种类型：、SELECT任务：最终结果是查询，得到一个结果集合。、DELETE任务：最终结果是删除。、INSERT任务：最终结果是插入。、UPDATE任务：最终结果是更新。3 返回任务执行结果。2DAOConfig.xml文件的配置 !- 说明app-charset=” 外部调用者的字符集ISO8859_1, GB2312, UTF8” db-charset=” 数据库的字符集ISO8859_1, GB2312, UTF8”,输入输出的字符集 2003-12-22 LHY新增- 数据库名唯一标识，如：jdlsdb 数据库连接通道jdbc:根据下面配置的参数通过JDBC获取数据库连接;appserver：根据DATA_SOURCE参数通过应用服务器连接池获取连接;jdls：根据JDLS_CONNECTION_POOL参数通过交大龙山连接池(PoolConfig中配置的ConnectionPool)获取连接 数据库连接JDBC驱动如：oracle.jdbc.driver.OracleDriver 数据库连接URL如：jdbc:oracle:thin::1521:JdlsEtax 数据库用户名如：jdls 数据库用户口令如：123 应用服务器的数据库连接DATASOURCE如：JDLSDataSource JDLS数据库连接池名称如：JdlsPool 数据库描述如：电子申报数据库 任务名称程序调用执行唯一标识，如：Zzsybnsr 任务对应的数据库名为poolconfig.xml文件中配置的数据库名称，如：ctais如要了解详细信息，请参照poolFramework， 任务类型select ,insert,delete,update 是否按照批处理执行true,false 该功能已经作废 具体的执行任务体类名，如果不为空则调用该类执行此任务，如果为空，说明使用通用执行体执行 任务描述如：增值税一般纳税人申报表的导, SQL语句名称如：WBJK_SB_ZZS_JXSE SQL语句类型query,update,procedure insert into xtgl_jsxxb (roleid, rolename, bz) values (?, ?, ? ) SQL语句中的参数类型列表，用“，”号分割，如果为空则全部默认为STRING类型 SQL语句描述 注意事项：针对task的NAME属性：task的NAME必须是唯一的。如果加载的是一个文件夹，那么它不是指在这个文件夹下的某一个.xml文件另唯一，而是指在整个文件夹下的所有xml文件中唯一。针对clause的”repeat”属性:具体SQL语句，具有一个REPEAT属性，如果为TRUE则证明有多个相同语句重复执行，默认为FALSE。如果为“true”,应该这样操作：比如你要让这个操作重复执行3次，则需要给这个task传3套参数。insert into table (user password) values (?, ? ) 在程序中参数应该这样组织：ArrayList alParam1 = new ArrayList();ArrayList alParam2 = new ArrayList();ArrayList alParam3 = new ArrayList();ArrayList alParams = new ArrayList();ArrayList alParam= new ArrayList();alParam1.add(a1);alParam1.add(b1);alParam2.add(a2);alParam2.add(b2);alParam3.add(a3);alParam3.add(b3);alParams.add(alParam1);alParams.add(alParam2);alParams.add(alParam3);alParam.add(alParams);/这条语句必不可少将参数传到任务中去：daoResultUpdate = dao.update(taskName, alParam);针对批处理：只要将true就可以使该任务按批处理方式执行针对transaction的说明：transaction在配置中已经失效，与配置文件中的transaction配置无关3系统的运作过程3.1系统如何初始化1AppConfig.xml中加载DAOConfig文件，配置如下：说明：1)aram-value中的DAOConfig为相对于AppConfig.xml文件的路径名。如果要加载的不是DAOConfig文件夹，而是具体的.xml文件，则可以进行调整，如：DAOConfig123.xml2)置中，除了parm-value是可变的外，其它一律严格不变。3)进行编程时，一般是通过服务器来加载配置文件的，如果要单独调试一个.xml文件而不通过服务器，也可以使用：DAOManager test= DAOManager.getinstance(“.xml文件路径”) 来加载这个”.xml”文件（可以参照样例程序）在系统启动的时，架构加载StartupFramework，,即解析AppConfig.xml文件，将该文件中所配置的内容加载到内存中。因此， DAOConfig文件夹下的所有文件都已被加载到内存中。3.2上层应用如何执行任务当执行某个任务时，在程序中执行如下操作：IDAO dao = (IDAO) DAOFactory.getInstance().getDao(IDAO);daoResultUpdate = dao.update(zxjlfbinsert, alParam);那么，将到内存中找zxjlfbinsert这样一个task，找到后将参数列表传给这个task, 调用底层的JDBC程序操作物理数据库，最终完成任务，返回执行结果。4常规操作举例 下面通过对四种业务类型的实际操作来讲解一下在具体的操作中台前幕后要做的工作4.1select操作4.1.1在配置文件中如何配置 fbwhCheck callcenterdb select false false 检查发布文号 fbwhCheck query select fbwh from yw_dhzczlb where fbwh=? 检查发布文号 4.1.2在程序中如何操作在程序中必须做以下事情:1）引入相应的包: import .jdls.foundation.dao.*;2）获取dao的实例: IDAO dao = (IDAO) DAOFactory.getInstance().getDao(IDAO); 3）参数的组织: ArrayList paramOfList = new ArrayList(); ArrayList paramOfDao = new ArrayList(); paramOfList.add(fbwh); paramOfDao.add(paramOfList);4）任务执行语句:DAOResult daoResultOfFbwh= dao.select(fbwhCheck,paramOfDao);此时的fbwhCheck与配置文件中的task的NAME节点中配置的相同.因此能够找到DAOConfig.xml文件中的相应的任务,传入参数列表,对物理数据库进行操作, 最终完成任务，返回执行结果到daoResultOfFbwh。 5）返回结果的处理:对于select语句，它查询出来的将是一组ArrayList的结果 If(daoResultOfFbwh.isSuccess() if (daoResultOfFbwh.getFirstSqlResultList().size()0) outmap.put(error,该发布文号已经存在,请确认!); this.getClientCommand().setOutPutDataMap(outmap); else /作发布文号的插入操作else/返回错误4.2insert操作4.2.1在配置文件中如何配置 zxjlfbinsertcallcenterdbinsertfalsetrue发布咨询记录zxjlfbinsertupdateinsert into yw_dfbwtb (pressproblemid, wtlylx, wtlx, wtlxxl, wtzt, wtxxms, hdfj, twfj, dfyj, organid, yyproblemid, shstatus, action, fbr, fbsj ) values (?, 003, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, INSERT, ?, ? ) 发布咨询记录4.2.2在程序中如何操作 在程序中必须做以下事情:1）引入相应的包: import .jdls.foundation.dao.*;2）获取dao的实例: IDAO dao = (IDAO) DAOFactory.getInstance().getDao(IDAO); 3）参数的组织: ArrayList params=new ArrayList(); ArrayList param = new ArrayList(); Params(pressproblemid); Params(wtlx);Params(wtlxxl);Params(wtzt);Params(wtxxms);Params(hdfj);Params(twfj);Params(dfyj);Params(organid);Params(yyproblemid);Params(fbr);Params(fbsj);param(params);有时候参数还可以从其它查询的结果取得，如：Parmas.add(daoResultid.getFirstSqlResultFirstCell()另外，此时要加载的参数，配置文件中的?以及配置文件中的参数在个数和顺序上都必须保持一致4）任务执行语句:DAOResult daoResultUpdate = dao.update(zxjlfbinsert, alParam);此时的zxjlfbinsert与配置文件中的task的NAME中配置的相同.因此能够找到DAOConfig.xml文件中的相应的任务,传入参数,对物理数据库进行操作, 最终完成任务，返回执行结果。 5）返回结果的处理: If(daoResultUpdate.isSuccess()/插入成功 /返回成功页面else/返回错误4.3delete操作 4.3.1在配置文件中如何配置在配置文件中配置其实都差不多只是将任务类型，sql语句的类型以及clause语句中的具体语句变换就可以了如下：deletePfdByIdcallcenterdbupdate/deletefalsefalsedeletePfdByIdupdatedelete from yw_pfd where pfdid=? 删除某派发单 说明：任务类型为：delete或update都可以;4.3.2在程序中如何操作：在程序中必须做以下事情:1）引入相应的包: import .jdls.foundation.dao.*;2）获取dao的实例: IDAO dao = (IDAO) DAOFactory.getInstance().getDao(IDAO); 3）参数的组织:参数的组织和其它业务类型一样，均为两层的结构，第一层是将所有参数封装到一个ArrayList中，第二层是将第一层的ArrayList封装到ArrayList中4）任务执行语句:DAOResult daoResultOfFbwh= dao.select(deletePfdById ,paramOfDao);此时的fbwhCheck与配置文件中的task的NAME中配置的相同.因此能够找到DAOConfig.xml文件中的相应的任务,传入参数,对物理数据库进行操作, 最终完成任务，返回执行结果。 5）返回结果的处理:If(deletePfdById.isSuccess()/返回成功页面 else/返回错误4.4update操作 4.4.1在配置文件中如何配置在配置文件中配置其实都差不多只是将任务类型，sql语句类型和clause语句中的具体语句变换就可以了如下：cancelPfdcallcenterdbupdatetruetruecancelFwjlupdateupdate yw_fwjl set status=99 where pfdid=? 更新活动问题表相关字段 4.4.2在程序中如何操作 在程序中必须做以下事情:1）引入相应的包: import .jdls.foundation.dao.*;2）获取dao的实例: IDAO dao = (IDAO) DAOFactory.getInstance().getDao(IDAO); 3）参数的组织:参数的组织和其它业务类型一样，均为两层的结构，第一层是将所以有参数封装到一个ArrayList中，第二层是将第一层的ArrayList封装到ArrayList中4）任务执行语句:DAOResult daoResultOfFbwh= dao.update(cancelPfd ,paramOfDao);此时的cancelPfd与配置文件中的task的NAME中配置的相同.因此能够找到DAOConfig.xml文件中的相应的任务,传入参数,对物理数据库进行操作, 最终完成任务，返回执行结果。 5）返回结果的处理: If(deletePfdById.isSuccess()/返回成功页面 else/返回错误补充：DAO任务传入参数说明 所有类型任务的传入主要业务参数都是ArrayList类型，他里面的元素为具体的参数ArrayList类型,个数和顺序与任务中配置的SQL语句的个数与顺序保持一致。参数ArrayList内部的元素为STRING类型，具体的个数和顺序与任务当前SQL语句中“?”号的个数和顺序保持一致。示意图如下：任务ArrayListTASK参数ArrayList 1（？号个数）SQL CLAUSE 1(select * from aa where bb=? And cc=?)参数ArrayList N（？号个数）SQL CLAUSE N(select * from aa where bb=? And cc=?)对于select类型的任务，如果要分页则还需要传入分页显示的参数信息，如：SQL CLAUSE1 中要加入分页信息，则可以在ArrayList1中加入两个参数，一个是每页行数，另一个是当前页号组织参数的时候，除了自己通过ArrayList来组织参数之外，还可以使用参数生成器来组织参数，其使用方法如下：1） IDAO接口中增加了方法getDAOParamGenerator()提供获取生成器2） DAOParamGenerator中的getDAOParam()：获取生成的最终参数3） DAOParamGenerator中的addFirstSqlParam(Object param)：增加第一个SQL的传入参数param4） DAOParamGenerator中的addSqlParam(int index,Object param)：增加index（从0开始）个SQL的传入参数param在程序中调用样例如下： IDAO dao = DAOManager.getInstance(c:DAOConfig); DAOParamGenerator dAOParamGenerator=dao.getDAOParamGenerator(); dAOParamGenerator.addFirstSqlParam(liuhongyu); dAOParamGenerator.addFirstSqlParam(510602733411296); DAOResult drs = dao.update(task1,dAOParamGenerator.getDAOParam();DAO任务传出参数说明所有类型任务的传出业务参数都是DAOResult类型，该类型提供以下方法：u isSuccess()方法：判断任务执行是否成功。u getError()：如果任务执行失败,则返回详细的错误信息。u getResultValue()：如果任务是select时才有效，返回类型为ArrayList，其元素为Integer类型（含义是：当前SQL语句查询结果的最大记录数），个数和顺序与任务中配置的SQL语句的个数与顺序保持一致。u getResultList：如果任务是select类型的，则返回查询结果集，其他类型该方法无意义。查询结果集具体类型为ArrayList类型，他里面的元素为具体的二维结果集表ArrayList,个数和顺序与任务中配置的SQL语句的个数与顺序保持一致。二维结果集表ArrayList内部的元素又为ArrayList类型，个数为具体的记录行数，该记录行ArrayList内部的元素为STRING类型，个数为具体的结果集的列。示意图如下：返回ArrayListTASK返回ArrayList 1（二维结果集）SQL CLAUSE 1(select * from aa where bb=? And cc=?)返回ArrayList N（二维结果集）SQL CLAUSE N(select * from aa where bb=? And cc=?)如何获取和使用SELET结果集对应的元数据DAOResult中有以下方法提供获取元数据对象：1） getDAOResultMetaDataList():获取所有SQL的元数据对象集合，类型为ArrayList2） getSqlResultSetMetaData(int index): 获取第INDEX（从0开始）处的SQL结果元数据对象，返回类型为ResultSetMetaData。调用样例如下：获取第一条SQL结果集的元数据列名： String names = drs.getSqlResultSetMetaData(0).getColumnNameArray(); for (int i = 0; i names.length; i+) System.out.println(namesi); 5特殊操作如何做这里的特殊操作主要是指对clob,blob字段的操作、事务的操作、存储过程的操作、dataSet和dataRow的操作等下面一一介绍5.1如何对BLOB和CLOB字段进行读写操作 LOB（large object）中我们用的比较多的主要有两种CLOB和BLOBCLOB是字符型LOB,主要存储文本信息,最长为4G，在J2EE程序中,比如网页的textarea中的字符信息比较长，Varchar2字段类型不能满足时，我们就得用CLOB数据类型; BLOB字段是二进制LOB，主要存储二进制数据，最长为4G，在J2EE程序中，一般类似于图片和文件的保存。当然也有另一种方法，就是把图片和文件保存在硬盘上，数据库中只保存图片的链接地址和文件在服务器上的路径。如果遇到文件和图片比较重要时还是需要保存到数据库中.为什么要把操作LOB字段称为一种特殊操作呢？主要是因为这种字段的操作跟其它的普通字段有所有同主要体现在：1LOB数据不能像其它类型数据一样直接插入（INSERT）。插入前必须先插入一个空的LOB对象，CLOB类型的空对象为EMPTY_CLOB()，BLOB类型的空对象为EMPTY_BLOB()。之后通过SELECT命令查询得到先前插入的记录并锁定，继而将空对象修改为所要插入的LOB对象，插入的时候，可以以流的形式写入2LOB读出的时候，它的返回类型和常规字段有所不同下面一一介绍CLOB、BLOB字段的读取和更新：1)读取CLOB、BLOB，和其他的SELECT没有区别，对于CLOB字段返回STRING型，对于BLOB字段返回BYTE类型，样例配置如下：select_clob_blobjdlsdbselectfalsefalseselect_clob_blobqueryselect id,clob,blob from test_clob_blob 2)更新CLOB、BLOB，和其他的UPDATE区别在于：一条更新操作需要配置两个语句（一个UPDATE、一个SELECT），而且需要配置CLOB、BLOB参数类型，在调用的时候对于CLOB字段对应的？传递STRING类型，对于BLOB字段对应的？传递BLOB类型，样例配置如下：update_clob_blobjdlsdbinsertfalsetrueupdate_blob_clobaaaaaaupdateupdate test_clob_blob set clob=?, blob=? where id=?select clob, blob from test_clob_blob where id=? for update CLOB,BLOB,String,String处理CLOB和BLOB字段的更新操作 insert into studenttest (xh,name,sex,age,address,yw,sx,yy,py)values(?,?,?,?,?,?,?,?,?) select py from studenttest where xh=? for update注意事项：含有CLOB,BLOB字段时，sql语句的结构将发生变化，如之间红色标记的部分在PARAMETER_TYPE_LIST中的参数类型的个数和类型必须与前面的？一一对应UPDATE_CLAUSE, SELECT_CLAUSE所操作的必须是同一张表5.2如何执行事务 所谓事务是用户定义的一个操作序列，这些操作要么全做要么全不做,是一个不可分割的工作单位。比如银行要进行转账，就必须把加钱和减钱的操作放到一个事务中去做，在我们的架构中，有如下两种方式来执行事务5.2.1使用事务执行器按批处理方式执行事务为了方便多个任务一起以一个事务方式执行，设计了DAOTransactionExecutor类，专门用来执行多个任务事务，主要方法如下：就提供了DAOTransactionExecutor类，专门用来执行多个任务事务，主要方法如下：1） IDAO中增加了获取事务执行器的方法getDAOTransactionExecutor()2） DAOTransactionExecutor中的addTask(String taskName, ArrayList param)：用来添加任务到事务执行队列中3） DAOTransactionExecutor中的setDatabaseName(String databaseName)：设置在那个数据库上执行，如果不设置，则默认为TASK配置中对应的数据库4） DAOTransactionExecutor中的execute(String databaseName)：在特定数据库上执行事务5） DAOTransactionExecutor中的execute()：执行事务（数据库是前面通过setDatabaseName设置的或者TASK配置中对应的数据库）调用样例如下： IDAO dao = DAOManager.getInstance(c:DAOConfig);/getExecutor DAOTransactionExecutor dte = dao.getDAOTransactionExecutor(); /add task1 DAOParamGenerator dAOParamGenerator=dao.getDAOParamGenerator(); dAOParamGenerator.addFirstSqlParam(liuhongyu); dAOParamGenerator.addFirstSqlParam(510602733411296); dte.addTask(task1,dAOParamGenerator.getDAOParam(); /add task2 dAOParamGenerator=dao.getDAOParamGenerator(); dAOParamGenerator.addFirstSqlParam(刘红玉); dAOParamGenerator.addFirstSqlParam(001); dte.addTask(task2,dAOParamGenerator.getDAOParam(); /execute DAOResult drs = dte.execute(); System.out.println(drs.isSuccess();说明：该操作方式只适合于增，删，改操作，对于查询操作无效5.2.2上层应用使用DAO事务（1）、DAO事务原理：具体实现模仿标准事务的实现机制，主要是对于连接的管理上，在开始事务时获取一个有效的连接，将该连接在事务区间内与当前执行线程绑定，在事务区间内所有的数据库操作都使用该连接来完成，直到事物执行结束（COMMIT或ROLLBACK）为止，事物执行结束后会自动将连接释放。IDAO提供了以下接口方法供上层应用调用： /* * 开始一个数据库databaseName上的DAO事务,处理超时设置为永久,事务隔离级别设置为:TRANSACTION_READ_COMMITTED * param databaseName * throws Exception */ public void beginTransaction(String databaseName) throws Exception; /* * 开始一个数据库databaseName上的DAO事务 * param databaseName * param timeout 超时设置 */ public void beginTransaction(String databaseName,int timeout) throws Exception; /* * 结束一个DAO事务处理 * param databaseName * param commit 提交还是回滚 */ public void endTransaction(String databaseName,boolean commit) throws Exception;特别注意：A、在系统中beginTransaction与endTransaction必须成对出现，否则会出现连接没有释放，事务没有提交的情况。B、在beginTransaction与endTransaction之间可以使用DAO层的任何方法执行数据库操作，也可以自己单独获取连接执行操作（这种情况下，请千万别修改连接的autocommit属性，也别自己去COMMIT）C、整个事务是在endTransaction时进行COMMIT或ROLLBACK的，中间过程不能进行。（2）、标准代码片段如下： dao = (IDAO) DAOFactory.getInstance().getDao(IDAO); try dao.beginTransaction(jdlsdb); /启动一个事务 catch (Exception ex2) System.out.println(无法启动事务); return ;/应该返回 boolean succ =false;/业务执行失败的标志 try succ = example_insert() & example_repeat_update() & example_phase