轻巧J2EE框架Mantis使用手册.doc

Mantis 2.0 使用手册目 录Mantis 2.0 使用手册1一、系统架构4二、配置文件说明6三、后台开发指南10四、前台页面开发指南11五、缓存12六、国际化131.修改init.xml文件132.在cache.xml中增加国际化资源的定义133.编写jsp页面144.例子145.注意14七、方法拦截14八、权限管理15九、后台线程16十、后台Socket 服务17十一、附录A171.util.Chart类说明：172.util.CSV类说明：193.Util.Mail类说明：204.Util.Upload类说明：205.Util. MSChart类说明：(客户端需要Office的ActiveX插件)226.Util.ChartManagement类说明：237.Util.ClientInfo类说明：268.Util. StringUtils类说明：279.Util. Component类说明：2810.Util. AESUtil类说明：2811.Util. ImageUtils类说明：2912.Util.ByteConvert类说明：2913.Util.FileUtils类说明：2914.Util. Validator类说明：2915.Util. AjaxUtil类说明：30十二、附录B341.如何在PerformGet或PerformPost中获得Connection变量342.如何实现MVC方式353.一个缺省的包含权限的Servlet：354.一个无数据库连接的Servlet：37十三、附录C381.bean:message382.bean:write383.解析DBResult结果384.bean:result395.bean: get406.bean: equal407.bean: notequal408.bean: param419.bean: base43一、 系统架构该系统需要JDK1.4或以上版本的支持，其中该系统的核心在于ActionServlet这个类，在做应用的时候，所有的Servlet都应从该类中继承，通过ActionServlet类的继承，我们就可以实现数据库连接、日志管理、错误管理，权限和SQL语句的解析，而不必自己亲自书写JDBC的操作语句。其中该类需要init.xml初始化文件的支持，有关初始化文件的详细信息，请查看下一章，另外，在数据库连接部分，由于使用了JDBC2.0的规范，所以在加载数据库的时候需要JDBC2.0的支持。有关该类的详细信息可以查看下图和相关的JavaDoc文件。其实ActionServlet是对用户透明的，任何开发者都不必关心ActionServlet的内部结构，而真正关心的是DBResult这个类，该类位于com.TrulyTech.mantis.result包中，开发者在书写JSP页面的时候就可以直接从这个类中获得相关的查询信息。下图为该类的UML类图：二、 配置文件说明配置文件位于web-host/WEB-INF/init.xml中，即与web.xml位于同一目录中，该配置文件决定整个Web应用的运行状态，以下为一个init.xml的例子：$webmultitrue3neworacle.jdbc.OracleDriverjdbc:oracle:thin:03:1521:gwjfmantismantisGBKtruetrue50100010MySQL0falsefalsefalsefalse/err.jsp/timeout.jsp/connection.jsp/alert.jspfalse UserID Permission Languagetrue trueactiondofalsenative100upload2147483648smtp.TrulyTsmtp.TrulyTtrueadmin admin trueresourceMessagezh_cnerror.badcommanderror.permissiondenytrue20002demo.ThreadProcesstrue99991010demo.SocketProcessfalse5000$rpt键值描述logFilePrefix日志文件的物理路径，不含扩展名, 系统会自动增加log为扩展名; 如果已$开始，则将该日志文件写在Web应用中的确WEB-INF目录里logFileTypeSingle-日志文件为单个文件 multi-日志文件为多个文件,一天产生一个文件Screenlog是否将日志输出到屏幕（true/false）LogLevel日志记录等级(0-不记录 1-错误信息 2-一般信息 3-详细信息)LogType记录方式（New-每次覆盖 Append-每次继续前次的日志写）JDBCClassJDBC驱动的类名称JDBCURLJDBC驱动的URL地址UserNameDatabase用户名PasswordDatabase用户口令CharsetDatabase字符集Unicode是否使用Unicode编码ConvertCharset是否进行字符集转换FetchSize一次查询记录的数量SQLCacheCacheExecute的缓存大小MaxRows查询的最大记录数PageSize确省每页的记录数，当request中没指定len的大小，则取该确省值Pagination处理分页机制 Oracle/MySQL/JDBCQueryTimeout查询超时时间（秒）isResponseErr错误信息是否通过标准的http头输出 (HTTP 500)isResponseAlert提示信息是否通过标准的http头输出 (HTTP 403 / HTTP 401)isResponseTimeout超时信息是否通过标准的http头输出 (HTTP 408)isResponseConnection数据库连接错误信息是否通过标准的http头输出 (HTTP 505)ErrPageURL错误页的相对地址TimeoutURL页面超时页的相对地址ConnectionURL数据库连接超出错误的相对地址AlertURL提示页的相对地址MetaData是否获取每个字段的信息（是否是必录项、长度）Session-UserIDSession中存储用户ID的对象标志Session-PermissionSession中存储权限的对象标志Session-LanguageSession中存储语言的对象标志HasPermission当Session中存储权限的对象为空时,是否返回权限允许 (true/false)isAudit是否写操作员日志Action-Tag判断动作的标志符，用于权限控制Action- Prefix后台调用函数的前缀，通过该参数可以配置支持不同的数据库，例如oracle的前缀为ora, SQL Server的前缀为sqlisConnectPool是否使用数据库连接池（JDBC2.0）PoolProvider连接池提供者（tomcat，weblogic，native）当为native时，则使用内部连接池MaxConnection最大连接数，当使用内部连接池该参数才生效，如果超过最大连接数，则返回nullDataSource连接池的JNDI名称Upload文件上传路径 (相对Web应用的地址)UploadMaxSize上传文件最大的大小TempPath临时文件上传路径SMTPServerSMTP服务器地址SMTPAuthSMTP是否需要认证SMTPUserSMTP认证用户名SMTPPwdSMTP认证用户口令International是否是国际化的应用(true/false)InternationalResource国际化的cache表名,对应与cache.xml中的定义DefaultLanguage缺省语言,当浏览器的语言在数据库中无定义,则选择该语言Key-BadCommand非法命令对应国际化资源的Key名Key-PermissionDeny权限非法对应国际化资源的Key名HasBackgroundThread是否启动后台线程(true/false)ThreadInterval后台线程刷新时间(ms)ThreadProcessClass后台线程处理类的类名BackgroundThreadNum后台线程线程数HasBackgroundSocket是否有后台Socket ServerSocketPortSocket端口号MaxProcessThreadSocket最大处理线程数MaxWaitSocket并发请求等待个数 （后台Socket最大并发请求数为MaxProcessThread+ MaxWait）SocketProcessClassSocket请求处理类HasCluster是否是在Cluster环境下部署MultiCastIP多播地址MultiCastPort多播端口RptTemplatePath报表模版的路径,如果第一个字符为$,则表示为WEB-INF中的相对路径三、 后台开发指南所有的Servlet都应从ActionServlet继承，主要实现：protected String PerformGet(HttpServletRequest request,HttpServletResponse response,SQLParser Parser) throws Exception和protected String PerformPost(HttpServletRequest request,HttpServletResponse response,SQLParser Parser) throws Exception这两个方法，分别对应doGet和doPost方法，其中Parser是SQL解析器。其中返回值为String类型，是页面跳转的URL,如果无跳转，则返回”。Parser主要用于SQL语句的解析，分为：1. SQLExecute：用于执行Insert和Update操作。2. QuerySingle：用于仅返回一条记录的查询语句，返回String类型, 如果没有数据，则返回null。3. QueryExecute：用于返回多条记录的查询语句，返回DBResult对象。4. PageExecute：用于返回多条记录的分页查询语句，返回DBResult对象。其中页面参数用_Name表示，返回多条的页面参数用_*Name表示，而对于Session中的对象用!Name表示。例如：Parser.SQLExecute(insert into employee(id,name,age,sex,job,operid) values (_id, + _name,_age,_sex,_job,!UserID);Parser.SQLExecute(delete from employee where id=_*id); DBResult Result=Parser.QueryExecute(select id,name,age,sex,job from employee where + name like %_query% and operid=!UserID order by id); String ret=Parser.QuerySingle(select count(*) from employee where id=_id); 注：1.通过Stmt对象，开发人员也可以不通过解析器执行相关的数据库操纵，但注意日志的记录：Statement stmt= Parser. Parser.getStatement();logWriter.log(1,e.toString() + ( + this.getClass().getName() +); 2. 同样，开发人员也可以重载doPost和doGet方法进行运算，比如运行存储过程，但同样要注意日志的记录和数据连接的获得，有关数据库连接的获得如下所示：java.sql.Connection conn=Parser.getConnection();3.所有异常都应该抛出，由Framework统一处理。四、 前台页面开发指南前台开发主要是JSP开发，开发量主要体现在对DBResult的解析和分页显示上。对于分页显示，第一个查询除了相关的查询条件外，还需要作为没页的显示个数，而无须显示Page信息。注：如没有隐含字段len，则系统默认为10。对于DBResult的解析如下所示：%for (int i=0;i a href=javascript:popWindow(/multiservlet?ID=&action=view) 而对于下一页，上一页的URL地址已经在DBResult中保存了，何以通过如下语句取出：a href=/multiservlet 首页a href=/multiservlet 上一页a href=/multiservlet 下一页a href=/multiservlet 尾页input type=text name=page size=2 value=五、 缓存可以将一些只读的SQL缓存起来以提高访问效率。Cache定义文件位于web-host/WEB-INF/cache.xml中，即与web.xml位于同一目录中，该配置文件提供了一些cache查询(只读)的定义，以下为一个cache.xml的例子：select id,name from employeeselect operid,password from operatorselect language_ID,key,msg from resourceMessage这样在后台就可以通过：DBResult Result=CacheManager.getCache(operator);也可以通过参数读取，例如如下例子是从operator对象中获得第0列等于admin的结果：Result=Result.getValue(Result,0,admin);通过方法CacheManager.refresh(employee);可以强制对缓存对象进行刷新，其中employee为缓存的对象名。注: 必须通过Parser.getConnection或者连接，然后调用Conn.Commit()提交后才可以调用CacheManager.Refresh，这样才能正确获得Cache数据，因为refresh与本身的Action不在一个事务当中，同时，如果是在Cluster环境下，该方法会通过多播向每个接点的服务器上发送同步Cahce的指令。如果不在Cluster环境下，则可以简单调用CahceManager.refresh(:employee”,Parser.getConnection)来刷新Cache,这个方法与Action是在同一个事务当中的，因此不需要提前先Commit.六、 国际化1. 修改init.xml文件将International参数设置成true然后非分别配置参数：Session-LanguageSession中存储语言的对象标志International是否是国际化的应用(true/false)InternationalResource国际化的cache表名,对应与cache.xml中的定义DefaultLanguage缺省语言,当浏览器的语言在数据库中无定义,则选择该语言Key-BadCommand非法命令对应国际化资源的Key名Key-PermissionDeny权限非法对应国际化资源的Key名2. 在cache.xml中增加国际化资源的定义select language_ID,key,msg from resourceMessage其中必须与init.xml中的InternationalResource参数对应下面的SQL语句，第一列为语言ID,第二列为Key，第三列是相应的信息，请注意顺序。3. 编写jsp页面在开始处增加将字符集改为UTF8， 并使用自定义标签并将缺省字符集合该为在使用资源信息时，可以通过如下语句实现：如果框架找不到对应的资源，则显示“%语言.Key%”信息，例如“%ZH_CN.LABEL.VALUE%”。4. 例子请参看international.jsp，例如：http:/localhost:8080/international.jsp5. 注意在第一次启动时，框架根据浏览器的语言显示响应的语言资源，如果想通过程序强制修改语言，则可以通过如下语句实现：HttpSession session = request.getSession();session.setAttribute(com.trulytech.mantis.system.Properties. Session_Language, EN_US);以上语句将强制改为英语（美国）语言。七、 方法拦截在每个servlet里可以在action前调用preAction(request,response)和调用postAction(request,response)完成在action前后的拦截。八、 权限管理权限主要由Permission类来完成，当用户登陆时，通过Permission类的setPermission将Action与权限的对应关系赋到Session中，程序将自动针对每个Action进行权限的校验。其中Session-UserIDSession中存储用户ID的对象标志Session-PermissionSession中存储权限的对象标志Action-Tag判断动作的标志符，用于权限控制这四个参数是与权限相关的。HttpSession session = request.getSession(); /session赋值 session.setAttribute(UserID, ret0); if (ret0.equalsIgnoreCase(1) Permission perm = new Permission();/权限可以通过数据库赋到perm中 perm.setPermission(SingleServlet, insert, 单表插入); session.setAttribute(Permission, perm); getServletContext().getRequestDispatcher(/main.html).forward(request, response);当然，权限一般由数据库定义，有登陆的Servlet负责向Permission类赋值，这样，权限表可以定义如下：UserIDServletNameActionName1demo.SingleServletInsert单表插入如果某个Servlet不要求权限管理，可以通过重载HasPermission方法来解决/重载身份校验函数 protected int HasPermission(HttpServletRequest request, HttpServletResponse response, SQLParser Parser) throws Exception return Permission.ALLOW; 如果要在demo中插入操作员日志,除了要将init.xml中的isAudit参数置成true后，还需要修改Permission类中的HasPermission方法，将以下注释删除。/TODO: 写Audit/* Parser.SQLExecute(insert into operatorlog(operid,name,timestamp) values ( + UserID + , + Name + ,sysdate);*/九、 后台线程首先配置init.xml文件中的HasBackgroundThread， ThreadInterval和ThreadProcessClass和BackgroundThreadNum值。然后编写ThreadProcessClass中制定的类，例如：package demo;import com.trulytech.mantis.thread.*;public class ThreadProcess public static Boolean doGc(Long previousruntime, Long currenttime) throws Exception if (currenttime.longValue() - previousruntime.longValue() = 15000) System.gc(); System.runFinalization(); return Boolean.TRUE; else return Boolean.FALSE; 后台线程会依次调用该类中do开始的所有方法，方法必须声明为：public static Boolean do(Long previousruntime, Long currenttime) throws Exception 其中，previousruntime为上次运行该方法的时间，currenttime为本次运行的时间，如果符合条件并执行逻辑，必须返回Boolean.TRUE，否则返回Boolean.FALSE。此外该方法中不用关心事务处理和例外处理; helper为SQL的封装类， 可以在动作执行时调用来访问数据库。当backGroundThreadNum1时，后台会依次调用ThreadProcessClass定义的类中do方法，ThreadProcessClass定义的类 + “_” + ThreadNum-1命名的类中的方法。例如，ThreadProcessClass定义为demo.ThreadPrecess,而backGroundThreadNum=2,则系统会同时启动3个后台线程，3个thread分别调用demo.ThreadPrecess, demo.ThreadPrecess_1, demo.ThreadPrecess_2这三个类中的方法。注： 在Cluster环境中，一般一个节点的Thread触发后，这个Thread应该向数据库插入一条运行记录，而另外节点的Thread在触发时，首先检查数据库是否有已经触发的记录，如果有，则不做业务逻辑，如果没有，则才继续执行业务逻辑，并将出发事件插入到数据库中，之所以这样做，是为了避免两个节点重复执行后台业务逻辑的问题。十、 后台Socket 服务首先配置init.xml文件中的HasBackgroundScoekt， SocketPort, MaxProcessThread，MaxWait和SocketProcessClass值。然后编写SocketProcessClass中制定的类，例如：package demo;public class SocketProcess public static void doProcess(.Socket conn) throws Exception System.out.println(Receive Request); 后台服务会自动调用doProcess的方法来处理用户的Socket请求。十一、 附录A1. util.Chart类说明：该类完成动态图形的绘制，返回JPEG的图形，在该版本中只完成了饼状图的绘制。参数说明：参数说明缺省值Width图形宽度320Type图形类型0-饼图 3-字符串BKColor背景色白色FontColor字体颜色黑色Result结果集NullLabel标题在Result中的字段数0Value数值在Result中的字段数1Str显示在图形中的文字“”fill图形填充色兰色调用该类的方法如下：/初始化Chart实例对象Chart chart=new Chart (response,400,Color.white,Color.black,0);/从数据库中查询数据 DBResult Result=Parser.QueryExecute(select label,value from piechart order by id desc); /设置绘图属性 chart.setResult(Result); chart.setBKColor(Color.white); chart.setLabel(0); chart.setValue(1);chart.setFill(Color.red);/绘制图形 Return chart.drawChart();显示的图形如下所示：绘制包含字符的方法如下：/初始化Chart实例对象Chart chart = new Chart(response, 200, Color.black, Color.orange, 0);chart.setType(3);/从页面接收名为str的字符串chart.setStr(getParameter(request,str);/绘制图形Return chart.drawChart();产生随机校验码代码如下：Chart chart = new Chart(response, 50, null, null, 3); chart.setStrfont(new Font(Times New Roman, 0, 18); chart.setStr(StringUtils.randomNumber(4); return chart.drawChart(); 如果要将文件存储为文件,则只要将response替换为文件名即可，不过要注意扩展名必须为JPEG，例如：Chart chart = new Chart(“f:image.jpg”, 50, null, null, 3); chart.setStrfont(new Font(Times New Roman, 0, 18); chart.setStr(StringUtils.randomNumber(4); return chart.drawChart();2. util.CSV类说明：该类完成CSV数据的输出。例如：DBResult Result=Parser.QueryExecute(select id,name,age,sex,job from employee where + operid=!UserID order by id);Return CSV.makeCSV(response,Result);3. Util.Mail类说明：该类完成邮件的相关控制，包含text, html格式的邮件以及包含附件的邮件。例如Mail mail=new Mail(); mail.setFrom(request.getParameter(from); /设置发信人 mail.setTo(request.getParameter(to); /设置收信人 mail.setMsg(request.getParameter(msg); /设置信件信息 mail.setSubject(request.getParameter(subject); /设置信件标题mail.setContentType(text/html;charset=gb2312); /设置信件格式text/html mail.sendMsgMail(); 4. Util.Upload类说明：该类完成文件的上传，该版本只完成了永久文件的上传。例如int Count=UploadFile.Upload(request, Parser.getUpload();也可以上传并生成唯一文件名的文件，并返回相关的文件名。例如ArrayList Arr=UploadFile.UploadEx(request, Parser.getUpload();所调用该方法的Servlet必须继承FileServlet类以实现上传功能。例如：public class UploadServlet extends FileServlet public String Upload(HttpServletRequest request, HttpServletResponse response, FileSQLParser Parser) throws Exception ArrayList Vec = UploadFile.UploadEx(request, Parser.getUpload();Return “”;其中FileServlet为所有文件上传的父类，其UML图如下：此外,改类还提供了文件下载功能,可以通过调用如下代码完成文件的下载:UploadFileDownLoad(“c:a.txt”, getServletConfig(), request, response);也可以通过如下函数完成下载指定文件名的的功能:UploadFile.DownLoad(c:a.rar,测试.rar,getServletConfig(), request, response);5. Util. MSChart类说明：(客户端需要Office的ActiveX插件)该类完成动态图形的绘制，返回MSChart的图形，在该版本中只完成了单类别的绘制。参数说明：参数说明缺省值Width图形宽度640Height图形宽度480Type图形类型柱状图BKColor背景色白色BGURL背景图形“”Result结果集nullLabel标题在Result中的字段数0Value数值在Result中的字段数1Title图形标题“”SubTitle图形子标题“”AxisTitle纵轴标题“”HasLegend是否需要图例trueLegendTitle图例标题“”注：Type类型支持 0-柱状图 3-栏状图 6-平滑曲线图 18-饼行图 29-面积图。调用该类的方法如下：/从数据库中查询数据DBResult Result=Parser.QueryExecute(select label,value from piechart order by id desc);/初始化Chart实例对象com.TrulyTech.mantis.util.MSChar