高效 Java Web 开发框架 JessMA v3.4.1

    JessMA 是功能完备的高性能 Full-Stack Web 应用开发框架，内置可扩展的 MVC Web 基础架构和 DAO 数据库访问组件（内部已提供了 Hibernate、MyBatis 与 JDBC DAO 组件），集成了 Action 拦截、Form / Dao / Spring Bean 装配、国际化、文件上传下载和页面静态化等基础 Web 应用组件，提供高效灵活的纯 Jsp/Servlet API 编程模型，可完美整合 Spring / Guice，支持 Action Convention，能快速开发传统风格和 RESTful 风格应用程序，文档和示例完善，非常容易学习。

    JessMA 官方网站：http://www.jessma.org
    JessMA 下载地址：http://www.oschina.net/p/portal-basic
    JessMA 在线示例：http://demo.jessma.org
    JessMA 在线 API 文档：http://www.jessma.org/doc

    JessMA 在设计之初就充分注重功能、性能与使用体验。JessMA 主要特点：

    ★ 功能全面：内置稳定高效的 MVC 基础架构和 DAO 框架，支持 Action 拦截、Form Bean / Dao Bean / Spring Bean 装配和声明式事务，提供国际化、文件上传下载、缓存和页面静态化等常用Web组件，能满足绝大部分 Web 应用的需要。 
    ★ 高度扩展：JessMA 通过的 plug-in 机制可以灵活扩展，JessMA 发布包中自带的 jessma-ext-rest 和 jessma-ext-spring 均以插件的形式提供，用户可根据需要加载或卸载这些插件。应用程序开发者也可以根据实际需要编写自定义插件来扩展 JessMA。 
    ★ 强大的整合能力：JessMA 是一个 Full-Stack 框架，同时也是一个开放式框架，可以以非常简单的方式整合第三方组件。本开发手册会详细阐述如何在 JessMA 中整合 Freemarker、 Velocity 、 Urlrewrite、 EHCache-Web 、 Spring 、 Hibernate 和 Mybaits 等常用框架和组件。 
    ★ 高性能：性能要求是 JessMA 的硬性指标，从每个模块的设计到每行代码的实现都力求简洁高效。另外，Portal-Basi c并没有对 JSP/Servet API 进行过多封装，开发者仍然使用 JSP/Servet API 开发应用程序，没有过多的迂回，性能得到保证。 
    ★ 优秀的使用体验：JessMA 的设计目标之一是提供良好的开发体验，尽量减少应用程序开发者的工作，API 的设计力求简单、完整、明确。同时，JessMA 为应用开发提供了大量 Util 工具，用来处理应用程序开发过程中通常会遇到的一般性问题，进一步减少应用程序开发者的工作负担。 
    ★ 平缓的学习曲线：学习使用 JessMA 只需掌握一定的 Core Java 与 JSP/Servlet 知识，本开发手册会循序渐进阐述每个知识点，每个知识点都会结合完整的示例进行讲述，知识点之间前后呼应，确保学习者在学习时温故知新，融会贯通。 
    ★ 完善的技术支持：除了提供完善的开发手册和示例代码以外，还提供博客和 QQ 群用于解答使用 JessMA 过程中碰到的所有问题，也可以访问 JessMA 官方网站了解更多资讯。

* JessMA 总体架构

JessMA主要包括以下5个部分：

    ● 基础应用框架

    基础应用框架加载应用程序配置文件（默认：app-config.xml），监听应用程序的生命周期事件，并向上层应用发送应用程序启动和关闭通知，应用程序可以处理这些通知进行额外的初始化或清理工作。基础应用框架在org.jessma.app包中是实现。

    ● MVC框架

    MVC框架加载MVC配置文件（默认：mvc-config.xml），通过前端控制器ActionDispatcher接收和解析所有的客户HTTP请求，然后交由相应的Action进行处理，最后生成相应的视图返回给客户端。MVC框架在org.jessma.mvc包中实现。

    ● DAO框架

    DAO框架封装了所有的数据库访问操作，内置JDBC、Hibernate和MyBaits数据库访问组件以及Druid、Proxool、JNDI等连接池。DAO框架是可扩展的，用户可以通过扩展org.jessma.dao.AbstractFacade和org.jessma.dao.AbstractSessionMgr实现自己的数据库访问组件。DAO框架在以下包中实现：
    ▪ org.jessma.dao
    ▪ org.jessma.dao.hbn
    ▪ org.jessma.dao.jdbc
    ▪ org.jessma.dao.mybatis

    ● 公共组件

    公共组件提供多种通用功能帮助类（如：字符串处理、类型转换、分页算法、压缩/解压、加解密、邮件发送等），这些类与框架无关，可在任何应用程序中使用。公共组件在以下包中实现：
    ▪ org.jessma.util
    ▪ org.jessma.util.archive
    ▪ org.jessma.util.cache
    ▪ org.jessma.util.http
    ▪ org.jessma.util.mail

    ● 扩展插件

    扩展差插件是基于JessMA核心框架基础上的功能延伸，不是JessMA的必要组件。可由应用程序开发人员根据需要自行定制。JessMA发行包中也自带了一些扩展插件（如：jessma-ext-spring和jessma-ext-rest）。

* JessMA 应用程序依赖关系

    基础应用框架、MVC框架和DAO框架都依赖于公共组件，其中基础应用框架同时依赖于DAO框架，因此，MVC框架和DAO框架能脱离JessMA单独使用（当然，要附带上公共组件）。例如：可以把MVC框架和DAO框架用于JessMA之外的其它Web项目；也可以把DAO框架用于非Web项目（如：Swing / SWT桌面应用）。

---

JessMA 3.4.1 更新：

1、升级 Log4J 到 2.x 版本
1) Log4J 默认配置文件为 log4j2.xml
2) 默认 Logger 对象获取方式：org.jessma.util.LogUtil.getDefaultLogger(...)
3) 其它 Logger 对象获取方式：org.apache.logging.log4j.LogManager.getLogger(...)

2、其它更新
1) 依赖库 “jessma-lib” 中的所有 jar 包更新到最新版本
2) 依赖库 “spring-lib” 中的所有 jar 包更新到最新版本
3) 更新开发手册《JessMA Java Web 应用开发框架 (v3.4.1)》

3、应用程序升级说明
1) JessMA 3.3.x 升级到 JessMA 3.4.1 需要做以下工作
    A) 把原来 log4j-1.x 的依赖包升级到 log4j-2.x（参考：“jessma-lib”）
    B) 修改获取 Logger 对象的程序代码

---

JessMA 3.3.1 更新：

1、增强国际化功能

1) 支持设置应用程序器默认 Locale 和默认 Bundle
    A) 如果不配置器默认 Locale 则使用系统原来的默认 Locale
    B) 如果不配置默认 Bundle，则默认 Bundle 为 'res.application-message'

        （参考：下面的 MVC 配置文件条目）
        <!--
            default-locale：应用程序默认语言选项（默认：与当前操作系统一致）
            default-bundle：应用程序默认 Bundle（默认：res.application-message）
        -->
        <i18n default-locale="en_US" default-bundle="com.bruce.res.application-message" />

2) 支持基于 URL、Cookie 或浏览器语言选项的国际化方式
    A) org.jessma.mvc.i18n.URLI18nFilter        ：基于 URL 请求参数的国际化拦截器
    B) org.jessma.mvc.i18n.CookieI18nFilter   ：基于 Cookie 的国际化拦截器
    C) org.jessma.mvc.i18n.BrowserI18nFilter：基于浏览器语言选项的国际化拦截器
    D) JessMA 默认基于 Session 实现国际化，但可以通过配置上述拦截器改为相应的实现方式
    E) 上述拦截器的国际化属性是基于 Request Attribute 的，因此会屏蔽 Session 的国际化设置
    F) 上述拦截器可以组合使用，一般顺序为：URL -> Cookie -> Browser

        （例如：下面同时配置了 URL、Cookie 和 Browser 三个国际化拦截器）
        <action-filters>
            <!-- 优先检查客户请求中是否带有名称为 '__locale' 的请求参数 -->
            <filter class="org.jessma.mvc.i18n.URLI18nFilter"/>
            <!-- 然后检查请求是否带有名称为 '__locale' 的 Cookie -->
            <filter class="org.jessma.mvc.i18n.CookieI18nFilter"/>
            <!-- 最后根据客户端浏览器的语言选项设置当前请求的语言属性 -->
            <filter class="org.jessma.mvc.i18n.BrowserI18nFilter"/>
        </action-filters>

2、支持 JSR 303 Bean Validation 机制

1) 如果开启了Bean Validation 机制，应用程序可对由 @FormBean 注解的 Form Bean 执行自动验证
2) @FormBean 注解增加 'validate()' 和 'groups()' 两个属性，分别指示是否对 Form Bean 执行自动验证，以及自动验证的验证组
3) 如果自动验证成功则转入 Action 的 validate() 方法继续执行，否则会把错误信息写入 Action 的 errors 集合并跳转到 Action 的 INPUT 视图
4) 应用程序还可以随时调用 ActionSupport 的 validateBean() / validateBeanAndAddErrors() 方法验证其它任何 Bean
5) 增加错误信息输出标签 <p:err/>，支持多种方式和格式展示错误信息（参考：<p:err/> 及其实现类 org.jessma.tag.Error 相关注释）

        （参考：下面的 MVC 配置文件条目）
        <!--
            enable ：是否开启 Bean Validation 机制（默认：开启）
            bundle：验证文本消息的 Bundle（默认：res.validation-message）
            validator：验证器类（默认：org.jessma.mvc.validation.HibernateBeanValidator）
        -->
        <bean-validation
            enable="true"
            bundle="com.bruce.res.validation-message"
            validator="org.jessma.mvc.validation.HibernateBeanValidator"
        />

3、其它更新

1) org.jessma.ext.dao.* 包中的类移到 org.jessma.dao
2) 应用程序默认 Bundle 由 “res.message-resource” 改为 “res.application-message”
3) 修改 MVC 主/从配置文件、应用程序配置文件以及 REST 配置文件的 Sechema 引用（参考 MyJessMA 测试工程）
4) 更新开发手册《JessMA Java Web 应用开发框架 (v3.3.1)》
5) 整理依赖库 “jessma-lib”，删除多余的 jar 包4) 事务属性由最外层的 DAO 方法指定，忽略所有内层 DAO 方法的事务属性

4、应用程序升级说明

1) JessMA 3.2.x 升级到 JessMA 3.3.1 需要做以下工作：
    A) 把原来对 org.jessma.ext.dao 包的引用改为 org.jessma.dao
    B) 把资源文件 “res.message-resource” 改为 “res.application-message” 或在 <i18n/> 配置项中指定
    C) 如有必要，修改 MVC 主从配置文件、应用程序配置文件以及 REST 配置文件的 Sechema
    D) 如果要在 Tomcat-6.0 中开启 Bean Validation 机制，需要把 “tomcat_7_to_6_lib” 文件夹下的 3 个 jar 文件替换  Tomcat-6.0 的 lib 目录下的同名文件
2) Portal-Basic 3.1.1 及更早版本升级到 JessMA 3.3.1：（参考 JessMA 3.2.1 的升级说明）

---

JessMA 3.2.3 更新：

1、增加 Guice 支持

1) 增加  Guice 插件包 jessma-ext-guice-3.2.3.jar 用于整合 Guice
2) Action 通过 @GuiceBean/@GuiceBeans 注解声明 Guice Bean
3) Action 通过拦截器 com.bruce.ext.guice.GuiceInjectFilter 解析 @GuiceBean/@GuiceBeans 注解并注入 Guice Bean
4) 可以在 Guice Bean 中注入 JessMA DAO 对象，从而能在 Guice 环境下使用 JessMA DAO 子框架
5) 示例工程 MyJessMA 增加 Guice 整合示例

    （注：通常情况下，应用程序需要创建 GuiceInjectFilter 的子类并改写 configModules() 方法，用于定义 Module 的绑定规则）
    public class MyGuiceInjectFilter extends GuiceInjectFilter
    {
        @Override
        protected Collection<Module> configModules()
        {
            Set<Module> modules = new HashSet<Module>();
            // 加入第一个 Module
            modules.add(new Module()
            {
                @Override
                public void configure(Binder binder)
                {
                    // 配置绑定规则
                    // ......
                }
            });
            // ......
            // 加入第N个 Module
            modules.add(new Module()
            {
                @Override
                public void configure(Binder binder)
                {
                    // 配置绑定规则
                    // ......
                }
            });
            return modules;
        }
    }

2、Form Bean 支持联级属性注入

1) @FormBean 注解支持注入联级属性
2) org.jessma.util.BeanHelper 的 createBean(...) / setPropertiesOrFieldValues(...) 系列方法支持联级装配 Bean

    （例如：下面的 Form 对应的 Bean 中，b、x 和 y 为联级 Bean）
    <form>
        <input name="a" value="...">
        <input name="b.c" value="...">
        <input name="b.d" value="...">
        <input name="x.y.z" value="...">
    </form>

---

JessMA 3.2.2 更新：

(注：本次更新的主要内容是升级 DAO 组件)

1、org.jessma.dao.hbn.HibernateSessionMgr 支持自动扫描实体对象

1) 实体对象用 @Entity 注解取代 *.hbm.xml 映射文件（同时也不必在 hibernate.cfg.xml 中配置 ‘mapping’）
2) app-config.xml 中配置 HibernateSessionMgr 时，用第二个可选参数以正则表达式的格式指定实体对象所在包

    （例如：实体对象位于 ‘com.bruce.<任意子包>.model’ 中）
    <manager name="mgr-1" class="org.jessma.dao.hbn.HibernateSessionMgr">
        <initialize-args>
            <arg></arg>
            <arg>com.bruce..+.model</arg>
        </initialize-args>
    </manager>

2、org.jessma.dao.mybatis.MyBatisSessionMgr 支持自动扫描 SQL Mapper 接口

1) 不必在 mybatis.cfg.xml 中配置 ‘mapper’
2) app-config.xml 中配置 MyBatisSessionMgr 时，用第三个可选参数以正则表达式的格式指定 SQL Mapper 接口所在包

    （例如：SQL Mapper 接口位于 ‘com.bruce.<任意子包>.mapper’ 中）
    <manager name="mgr-2" class="org.jessma.dao.mybatis.MyBatisSessionMgr">
        <initialize-args>
            <arg></arg>
            <arg></arg>
            <arg>com.bruce..+.mapper</arg>
        </initialize-args>
    </manager>

3、org.jessma.dao.FacadeProxy 增加方法 executeCustomTransaction(...) 支持执行自定义事务

1) JessMA 的事务是 DAO 层事务，也就是说当外部调用某个 DAO 方法时，该方法作为一个事务单元执行。 但在一些特殊情形下可能需要在 DAO 外部执行 Service 层事务（例如：事务需要调用多个 DAO 对象的多个方法）， 此时需要创建一个自定义事务（CustomTransaction），并调用 FacadeProxy 的 executeCustomTransaction(...) 来执行该自定义事务。
2) 增加自定义事务相关接口：
    A) CustomTransaction　　: 自定义事务基接口
    B) JdbcTransaction　　　  : JDBC 自定义事务接口
    C) MyBatisTransaction　　: MyBatis自定义事务接口
    D) HibernateTransaction　: Hibernate 自定义事务接口

    （示例）
    public static void serviceMethod()
    {
        // 获取 SessionMgr
        HibernateSessionMgr mgr = (HibernateSessionMgr)AppConfig.getSessionManager("mgr-1");
        // 执行自定义事务
        FacadeProxy.executeCustomTransaction(mgr, new HibernateTransaction(){
        // 实现自定义事务方法
            @Override
            public void execute(HibernateSessionMgr mgr) throws DAOException
            {
                // 创建 dao1 （可以使用 FacadeProxy 创建 DAO 对象）
                MyDaoA dao1 = new MyDaoA(mgr);
               // 创建 dao2 （可以使用 ‘new MyDaoB(mgr)’ 创建 DAO 对象）
                MyDaoB dao2 = Facade.create(MyDaoB.class, mgr);

                // 执行 DAO 方法
                dao1.methodXxx();
                dao2.methodYyy();
                dao1.methodZzz();
                dao2.methodNnn();
            }});
    }

4、扩大 mvc-confing.xml 中 <result-path-aliases> 别名配置应用范围

1) 支持在 <result-path-aliases> 配置中引用前面定义的别名

    （示例：下面配置中 ${index} 的实际路径为 '/jsp/test/index.jsp'）
    <result-path-aliases>
        <alias name="jsp_base" path="/jsp/test"/>
        <alias name="index" path="${jsp_base}/index.jsp"/>
    </result-path-aliases>

2) 允许在 <action-convention> 的 'dispatch-file-path' 和 'dispatch-file-path' 配置中使用别名

    （示例：下面配置中 'dispatch-file-path' 的实际路径为 '/jsp'）
    <action-convention
        dispatch-file-path="${ac_path}"
        <!-- 其它配置（略）... -->
    />
    <result-path-aliases>
        <alias name="ac_path" path="/jsp"/>
    </result-path-aliases>