YMP轻量级JAVA应用开发框架使用手册

2019独角兽企业重金招聘Python工程师标准>>>

YMP v2 ——轻量级JAVA应用开发框架

使用手册

(20180327)

注意：框架代码仓库地址：https://gitee.com/suninformation/ymate-platform-v2

YMP是一个非常简单、易用的一套轻量级JAVA应用开发框架，设计原则主要侧重于简化工作任务、规范开发流程、提高开发效率，让开发工作像搭积木一样轻松是我们一直不懈努力的目标！

主要技术特点

• 采用组件化、模块化打包方式，可按需装配，灵活可扩展；

• 采用微内核实现Autoscan、AOP、IoC、Event等，涵盖SSH框架中绝大部分核心功能；

• 统一配置体系结构，感受不一样的文件资源配置及管理模式；

• 整合多种日志系统（log4j、jcl、slf4j）、日志文件可分离存储；

• 轻量级持久化层封装，针对RDBMS（MySQL、SQLServer、Oracle等）和NoSQL（MongoDB、Redis等）提供支持；

• 完善的插件机制，助力于更细颗粒度的业务拆分；

• 独特的独立服务开发体验；

• 功能强大的验证框架，完全基于Java注解，易于使用和扩展；

• 灵活的缓存服务，支持EhCache、Redis和多级缓存（MultiLevel）技术；

• 配置简单的MVC架构，强大且易于维护和扩展，支持RESTful风格，支持JSP、HTML、Binary、Freemarker、Velocity等多种视图技术；

模块及功能

YMP框架主要是由框架核心(Core)和若干模块(Modules)组成，整体结构非常简约、清晰，如图所示：

框架核心(Core)

主要负责框架的初始化和模块的加载及其生命周期管理，功能包括：

• 类对象管理器：提供包类的自动扫描以及Bean生命周期管理、依赖注入和方法拦截等特性；
• 事件服务：通过事件注册和广播的方式触发和监听事件动作，并支持同步和异步两种模式执行事件队列；
• 模块：是YMP框架所有功能特性封装的基础形式，负责模块的生命周期管理；
• 国际化资源管理器：提供统一的资源文件加载、销毁和内容读取，支持自定义资源加载和语言变化的事件监听；
• 另外，提供了一组自定义的数据结构和框架中需要的各种工具类；

查看文档...

配置体系(Configuration)

通过简单的目录结构实现在项目开发以及维护过程中，对配置等各种文件资源的统一管理，为模块化开发和部署提供灵活的、简单有效的解决方案：

• 规范模块化开发流程、统一资源文件管理；
• 具备有效的资源重用和灵活的系统集成构建、部署和数据备份与迁移等优势；
• 简单的配置文件检索、加载及管理模式；
• 模块间资源共享，模块可以共用所属项目的配置、类和jar包等资源文件；
• 默认支持XML和Properties配置文件解析，可以通过IConfigurationProvider接口自定义文件格式，支持缓存，避免重复加载；
• 配置对象支持注解方式声明，无需编码即可自动加载并填充配置内容到类对象；
• 集成模块的构建与分发、服务的启动与停止*，以及清晰的资源文件分类结构可快速定位；

查看文档...

日志(Log)

基于开源日志框架Log4J 2实现，提供对日志记录器对象的统一管理，可以在任意位置调用任意日志记录器输出日志，实现系统与业务日志的分离，并针对apache-commons-logging日志框架和slf4j日志系统提供支持；

查看文档...

持久化(Persistence)

JDBC

针对关系型数据库(RDBMS)数据存取的一套简单解决方案，主要关注数据存取的效率、易用性和透明，其具备以下功能特征：

• 基于JDBC框架API进行轻量封装，结构简单、便于开发、调试和维护；
• 优化批量数据更新、标准化结果集、预编译SQL语句处理；
• 支持单实体ORM操作，无需编写SQL语句；
• 提供脚手架工具，快速生成数据实体类，支持链式调用；
• 支持通过存储器注解自定义SQL语句或从配置文件中加载SQL并自动执行；
• 支持结果集与值对象的自动装配，支持自定义装配规则；
• 支持多数据源，默认支持C3P0、DBCP、JNDI连接池配置，支持数据源扩展；
• 支持多种数据库(如:Oracle、MySQL、SQLServer等)；
• 支持面向对象的数据库查询封装，有助于减少或降低程序编译期错误；
• 支持数据库事务嵌套；
• 支持数据库视图和存储过程；

查看文档...

MongoDB

针对MongoDB的数据存取操作的特点，以JDBC模块的设计思想进行简单封装，采用会话机制，支持多数据源配置和实体操作、基于对象查询、MapReduce、GridFS、聚合及函数表达式集成等，仍需进一步完善改进，文档整理中，敬请期待...

Redis

基于Jedis驱动封装，采用会话机制，支持多数据源及连接池配置，仍需进一步完善改进，文档整理中，敬请期待...

插件(Plugin)

采用独立的ClassLoader类加载器来管理私有JAR包、类、资源文件等，设计目标是在接口开发模式下，将需求进行更细颗粒度拆分，从而达到一个理想化可重用代码的封装形态；

每个插件都是封闭的世界，插件与外界之间沟通的唯一方法是通过业务接口调用，管理这些插件的容器被称之为插件工厂，负责插件的分析、加载和初始化，以及插件的生命周期管理，插件模块支持创建多个插件工厂实例，工厂对象之间完全独立，无任何依赖关系；

查看文档...

服务(Serv)

一套基于NIO实现的通讯服务框架，提供TCP、UDP协议的客户端与服务端封装，灵活的消息监听与消息内容编/解码，简约的配置使二次开发更加便捷；

同时默认提供断线重连、链路维护(心跳)等服务支持，您只需了解业务即可轻松完成开发工作。

查看文档...

验证(Validation)

服务端参数有效性验证工具，采用注解声明方式配置验证规则，更简单、更直观、更友好，支持方法参数和类成员属性验证，支持验证结果国际化I18N资源绑定，支持自定义验证器，支持多种验证模式；

查看文档...

缓存(Cache)

以EhCache作为默认JVM进程内缓存服务，通过整合外部Redis服务实现多级缓存（MultiLevel）的轻量级缓存框架，并与YMP框架深度集成(支持针对类方法的缓存，可以根据方法参数值进行缓存)，灵活的配置、易于使用和扩展；

查看文档...

WebMVC框架

WebMVC模块在YMP框架中是除了JDBC模块以外的另一个非常重要的模块，集成了YMP框架的诸多特性，在功能结构的设计和使用方法上依然保持一贯的简单风格，同时也继承了主流MVC框架的基因，对于了解和熟悉SSH等框架技术的开发人员来说，上手极其容易，毫无学习成本。

其主要功能特性如下：

• 标准MVC实现，结构清晰，完全基于注解方式配置简单；
• 支持约定模式，无需编写控制器代码，直接匹配并执行视图；
• 支持多种视图技术(JSP、Freemarker、Velocity、Text、HTML、JSON、Binary、Forward、Redirect、HttpStatus等)；
• 支持RESTful模式及URL风格；
• 支持请求参数与控制器方法参数的自动绑定；
• 支持参数有效性验证；
• 支持控制器方法的拦截；
• 支持注解配置控制器请求路由映射；
• 支持自动扫描控制器类并注册；
• 支持事件和异常的自定义处理；
• 支持I18N资源国际化；
• 支持控制器方法和视图缓存；
• 支持控制器参数转义；
• 支持插件扩展；

查看文档...

相关阅读

• Quickstart——快速上手

• Quickstart_New——扩展工具篇

One More Thing

YMP不仅提供便捷的Web及其它Java项目的快速开发体验，也将不断提供更多丰富的项目实践经验。

感兴趣的小伙伴儿们可以加入 官方QQ群480374360，一起交流学习，帮助YMP成长！

了解更多有关YMP框架的内容，请访问官网：http://www.ymate.net/

框架核心（Core）

YMP框架主要是由核心(Core)和若干模块(Modules)组成，核心主要负责框架的初始化和模块的生命周期管理。

主要核心功能

• Beans：类对象管理器（微型的Spring容器），提供包类的自动扫描（AutoScan）以及Bean生命周期管理、依赖注入（IoC）和方法拦截（AOP）等特性。

• Event：事件服务，通过事件注册和广播的方式触发和监听事件动作，并支持同步和异步两种模式执行事件队列。

• Module：模块，是YMP框架所有功能特性封装的基础形式，负责模块的生命周期管理，模块将在框架初始化时自动加载并初始化，在框架销毁时自动销毁。

• I18N：国际化资源管理器，提供统一的资源文件加载、销毁和内容读取，支持自定义资源加载和语言变化的事件监听。

• Lang：提供了一组自定义的数据结构，它们在部分模块中起到了重要的作用，包括：

  • BlurObject：用于解决常用数据类型间转换的模糊对象。
  • PairObject：用于将两个独立的对象捆绑在一起的结对对象。
  • TreeObject：使用级联方式存储各种数据类型，不限层级深度的树型对象。

• Util：提供框架中需要的各种工具类。

Maven包依赖

<dependency>
    <groupId>net.ymate.platform</groupId>
    <artifactId>ymate-platform-core</artifactId>
    <version><VERSION></version>
</dependency>

注：若想单独使用YMP核心包时需要在pom.xml中添加上述配置，其它模块已经默认引入核心包依赖，无需重复配置。

框架初始化

YMP框架的初始化是从加载ymp-conf.properties文件开始的，该文件必须被放置在classpath的根路径下；

• 根据程序运行环境的不同，YMP框架初始化时将根据当前操作系统优先级加载配置：

  • 优先加载 ymp-conf_DEV.properties (若加载成功则强制设置ymp.dev_mode=true)
  • Unix/Linux环境下，优先加载 ymp-conf_UNIX.properties；
  • Windows环境下，优先加载 ymp-conf_WIN.properties；
  • 若以上配置文件未找到，则加载默认配置 ymp-conf.properties；

• 同时，也可以通过JVM启动参数配置系统环境，框架将优先根据当前操作系统及运行环境加载匹配的配置文件：

  • -Dymp.run_env=test：测试环境，将优先加载ymp-conf_TEST.properties
  • -Dymp.run_env=dev：开发环境，将优先加载ymp-conf_DEV.properties
  • -Dymp.run_env=product：生产环境，将优先加载ymp-conf.properties

• 框架初始化基本配置参数：

    #-------------------------------------
    # 框架基本配置参数
    #-------------------------------------
  
    # 是否为开发模式，默认为false
    ymp.dev_mode=
  
    # 框架自动扫描的包路径集合，多个包名之间用'|'分隔，默认已包含net.ymate.platform包，其子包也将被扫描
    ymp.autoscan_packages=
  
    # 包文件排除列表，多个文件名称之间用'|'分隔，被包含的JAR或ZIP文件在扫描过程中将被忽略
    ymp.excluded_files=
  
    # 模块排除列表，多个模块名称或类名之间用'|'分隔，被包含的模块在加载过程中将被忽略
    ymp.excluded_modules=
  
    # 国际化资源默认语言设置，可选参数，默认采用系统环境语言
    ymp.i18n_default_locale=zh_CN
  
    # 国际化资源管理器事件监听处理器，可选参数，默认为空
    ymp.i18n_event_handler_class=
  
    # 框架全局自定义参数，xxx表示自定义参数名称，vvv表示参数值
    ymp.params.xxx=vvv
  
    # 本文测试使用的自定义参数
    ymp.params.helloworld=Hello, YMP!
  

• 测试代码，完成框架的启动和销毁：

    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            // 输出自定义参数值：Hello, YMP!
            System.out.println(YMP.get().getConfig().getParam("helloworld"));
        } finally {
            YMP.get().destroy();
        }
    }
  

Beans

包类的自动扫描（AutoScan）

YMP框架初始化时将自动扫描由autoscan_packages参数配置的包路径下所有声明了@Bean注解的类文件，首先分析被加载的类所有已实现接口并注册到Bean容器中，然后执行类成员的依赖注入和方法拦截代理的绑定；

说明：

• 相同接口的多个实现类被同时注册到Bean容器时，通过接口获取的实现类将是最后被注册到容器的那个，此时只能通过实例对象类型才能正确获取；

• 若不希望某个类被自动扫描，只需在该类上声明@Ignored注解，自动扫描程序都忽略它；

• 示例一：

    // 业务接口
    public interface IDemo {
        String sayHi();
    }
  
    // 业务接口实现类，单例模式
    [@Bean](https://my.oschina.net/bean)
    public class DemoBean implements IDemo {
        public String sayHi() {
            return "Hello, YMP!";
        }
    }
  

• 示例二：

    // 示例一中的业务接口实现类，非单例模式
    @Bean(singleton = false)
    public class DemoBean implements IDemo {
        public String sayHi() {
            return "Hello, YMP!";
        }
    }
  

• 示例三：

    public class DemoBeanHandler implements IBeanHandler {
  
        [@Override](https://my.oschina.net/u/1162528)
        public Object handle(Class<?> targetClass) throws Exception {
            // 自定义对象处理逻辑...
            return targetClass.newInstance();
        }
    }
  
    // 自定义对象处理器 (将取代原来的处理器)
    @Bean(handler=DemoBeanHandler.class)
    public class DemoBean implements IDemo {
        public String sayHi() {
            return "Hello, YMP!";
        }
    }
  

• 示例四：

    // 自定义Bean实例初始化后处理逻辑
    [@Bean](https://my.oschina.net/bean)
    public class DemoBean implements IDemo, IBeanInitializer {
        public String sayHi() {
            return "Hello, YMP!";
        }
  
        public void afterInitialized() throws Exception {
            System.out.println(sayHi() + " ---- afterInitialized.");
        }
    }
  

• 测试代码：

    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            // 1. 通过接口获取实例对象
            IDemo _demo = YMP.get().getBean(IDemo.class);
            System.out.println(_demo.sayHi());
  
            // 2. 直接获取实例对象
            _demo = YMP.get().getBean(DemoBean.class);
            System.out.println(_demo.sayHi());
        } finally {
            YMP.get().destroy();
        }
    }
  

依赖注入（IoC）

通过在类成员属性上声明@Inject和@By注解来完成依赖注入的设置，且只有被Bean容器管理的类对象才支持依赖注入，下面举例说明：

• 示例：

    // 业务接口
    public interface IDemo {
        String sayHi();
    }
  
    // 业务接口实现类1
    @Bean
    public class DemoOne implements IDemo {
        public String sayHi() {
            return "Hello, YMP! I'm DemoOne.";
        }
    }
  
    // 业务接口实现类2
    @Bean
    public class DemoTwo implements IDemo {
        public String sayHi() {
            return "Hello, YMP! I'm DemoTwo.";
        }
    }
  

• 测试代码：

    @Bean
    public class TestDemo {
  
        @Inject
        private IDemo __demo1;
  
        @Inject
        @By(DemoOne.class)
        private IDemo __demo2;
  
        public void sayHi() {
            // _demo1注入的将是最后被注册到容器的IDemo接口实现类
            System.out.println(__demo1.sayHi());
            // _demo2注入的是由@By注解指定的DemoOne类
            System.out.println(__demo2.sayHi());
        }
  
        public static void main(String[] args) throws Exception {
            YMP.get().init();
            try {
                TestDemo _demo = YMP.get().getBean(TestDemo.class);
                _demo.sayHi();
            } finally {
                YMP.get().destroy();
            }
        }
    }
  

也可以通过@Injector注解声明一个IBeanInjector接口实现类向框架注册自定义的注入处理逻辑，下面举例说明如何为注入对象添加包装器：

• 示例：

    // 定义一个业务接口
  
    public interface IInjectBean {
  
        String getName();
  
        void setName(String name);
    }
  
    // 业务接口实现类
  
    @Bean
    public class InjectBeanImpl implements IInjectBean {
  
        private String name;
  
        public String getName() {
            return name;
        }
  
        public void setName(String name) {
            this.name = name;
        }
    }
  
    // 业务对象包装器类
  
    public class InjectBeanWrapper implements IInjectBean {
  
        private IInjectBean __targetBean;
  
        public InjectBeanWrapper(IInjectBean targetBean) {
            __targetBean = targetBean;
        }
  
        public String getName() {
            return __targetBean.getName();
        }
  
        public void setName(String name) {
            __targetBean.setName(name);
        }
    }
  
    // 自定义一个注解
  
    @Target({ElementType.FIELD})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    public @interface Demo {
  
        String value();
    }
  
    // 为注解编写自定义注入逻辑
  
    @Injector(Demo.class)
    public class DemoBeanInjector implements IBeanInjector {
  
        public Object inject(IBeanFactory beanFactory, Annotation annotation, Class<?> targetClass, Field field, Object originInject) {
            // 为从自定义注解取值做准备
            Demo _anno = (Demo) annotation;
            if (originInject == null) {
                // 若通过@Inject注入的对象不为空则为其赋值
                IInjectBean _bean = new InjectBeanImpl();
                _bean.setName(_anno.value());
                // 创建包装器
                originInject = new InjectBeanWrapper(_bean);
            } else {
                // 直接创建包装器并赋值
                InjectBeanWrapper _wrapper = new InjectBeanWrapper((IInjectBean) originInject);
                _wrapper.setName(_anno.value());
                //
                originInject = _wrapper;
            }
            return originInject;
        }
    }
  

• 测试代码：

    @Bean
    public class App {
  
        @Inject
        @Demo("demo")
        private IInjectBean __bean;
  
        public IInjectBean getBean() {
            return __bean;
        }
  
        public static void main(String[] args) throws Exception {
            try {
                YMP.get().init();
                //
                App _app = YMP.get().getBean(App.class);
                IInjectBean _bean = _app.getBean();
                System.out.println(_bean.getName());
            } finally {
                YMP.get().destroy();
            }
        }
    }
  

说明：

• 当使用自定义注解进行依赖注入操作时可以忽略@Inject注解，若存在则优先执行@Inject注入并将此对象当作IBeanInjector接口方法参数传入；
• 当成员变量被声明多个自定义注入规则注解时（不推荐），根据框架加载顺序，仅执行首个注入规则；

方法拦截（AOP）

YMP框架的AOP是基于CGLIB的MethodInterceptor实现的拦截，通过以下注解进行配置：

• @Before：用于设置一个类或方法的前置拦截器，声明在类上的前置拦截器将被应用到该类所有方法上；

• @After：用于设置一个类或方法的后置拦截器，声明在类上的后置拦截器将被应用到该类所有方法上；

• @Around：用于同时配置一个类或方法的前置和后置拦截器；

• @Clean：用于清理类上全部或指定的拦截器，被清理的拦截器将不会被执行；

• @ContextParam：用于设置上下文参数，主要用于向拦截器传递参数配置；

• @Ignored：声明一个方法将忽略一切拦截器配置；

说明:

声明@Ignored注解的方法、非公有方法和Object类方法及Object类重载方法将不被拦截器处理。

示例一：

    // 创建自定义拦截器
    public class DemoInterceptor implements IInterceptor {
        public Object intercept(InterceptContext context) throws Exception {
            // 判断当前拦截器执行方向
            switch (context.getDirection()) {
                // 前置
                case BEFORE:
                    System.out.println("before intercept...");
                    // 获取拦截器参数
                    String _param = context.getContextParams().get("param");
                    if (StringUtils.isNotBlank(_param)) {
                        System.out.println(_param);
                    }
                    break;
                // 后置
                case AFTER:
                    System.out.println("after intercept...");
            }
            return null;
        }
    }

    @Bean
    public class TestDemo {

        @Before(DemoInterceptor.class)
        public String beforeTest() {
            return "前置拦截测试";
        }

        @After(DemoInterceptor.class)
        public String afterTest() {
            return "后置拦截测试";
        }

        @Around(DemoInterceptor.class)
        @ContextParam({
                @ParamItem(key = "param", value = "helloworld")
            })
        public String allTest() {
            return "拦截器参数传递";
        }

        public static void main(String[] args) throws Exception {
            YMP.get().init();
            try {
                TestDemo _demo = YMP.get().getBean(TestDemo.class);
                _demo.beforeTest();
                _demo.afterTest();
                _demo.allTest();
            } finally {
                YMP.get().destroy();
            }
        }
    }

示例二：

    @Bean
    @Before(DemoInterceptor.class)
    @ContextParam({
            @ParamItem(key = "param", value = "helloworld")
        })
    public class TestDemo {

        public String beforeTest() {
            return "默认前置拦截测试";
        }

        @After(DemoInterceptor.class)
        public String afterTest() {
            return "后置拦截测试";
        }

        @Clean
        public String cleanTest() {
            return "清理拦截器测试";
        }

        public static void main(String[] args) throws Exception {
            YMP.get().init();
            try {
                TestDemo _demo = YMP.get().getBean(TestDemo.class);
                _demo.beforeTest();
                _demo.afterTest();
                _demo.cleanTest();
            } finally {
                YMP.get().destroy();
            }
        }
    }

注：@ContextParam注解的value属性允许通过$xxx的格式支持从框架全局参数中获取xxx的值

包拦截器配置

YMP框架支持将@Before、@After、@Around和@ContextParam注解在package-info.java类中声明，声明后该拦截器配置将作用于其所在包下所有类(子包将继承父级包配置)。

拦截器的执行顺序: package > class > method

通过@Packages注解让框架自动扫描package-info.java类并完成配置注册。

示例:

本例将为net.ymate.demo.controller包指定拦截器配置，其package-info.java内容如下：

@Packages
@Before(DemoInterceptor.class)
@ContextParam(@ParamItem(key = "param", value = "helloworld"))
package net.ymate.demo.controller;

import net.ymate.demo.intercept.DemoInterceptor;
import net.ymate.platform.core.beans.annotation.Before;
import net.ymate.platform.core.beans.annotation.ContextParam;
import net.ymate.platform.core.beans.annotation.Packages;
import net.ymate.platform.core.beans.annotation.ParamItem;

拦截器全局规则设置

有些时候，我们需要对指定的拦截器或某些类和方法的拦截器配置进行调整，往往我们要修改代码、编译打包并重新部署，这样做显然很麻烦！

现在我们可以通过配置文件来完成此项工作，配置格式及说明如下：

#-------------------------------------
# 框架拦截器全局规则设置参数
#-------------------------------------

# 是否开启拦截器全局规则设置, 默认为false
ymp.intercept_settings_enabled=true

# 为指定包配置拦截器, 格式: ymp.intercept.packages.<包名>=<[before:|after:]拦截器类名> (通过'|'分隔多个拦截器)
ymp.intercept.packages.net.ymate.demo.controller=before:net.ymate.demo.intercept.UserSessionInterceptor

# 全局设置指定的拦截器状态为禁止执行, 仅当取值为disabled时生效, 格式: ymp.intercept.globals.<拦截器类名>=disabled
ymp.intercept.globals.net.ymate.framework.webmvc.intercept.UserSessionAlreadyInterceptor=disabled

# 为目标类配置拦截器执行规则:
#
# -- 格式: ymp.intercept.settings.<目标类名>#[方法名称]=<[*|before:*|after:*]或[before:|after:]interceptor_class_name[+|-]]>
# -- 假设目标类名称为: net.ymate.demo.controller.DemoController
#
# -- 方式一: 指定目标类所有方法禁止所有拦截器(*表示全部, 即包括前置和后置拦截器)
ymp.intercept.settings.net.ymate.demo.controller.DemoController#=*

# -- 方式二: 指定目标类的doLogin方法禁止所有前置拦截器(before:表示规则限定为前置拦截器, after:表示规则限定为后置拦截器)
ymp.intercept.settings.net.ymate.demo.controller.DemoController#doLogin=before:*

# -- 方式三: 指定目标类的doLogout方法禁止某个前置拦截器并增加一个新的后置拦截器(多个执行规则通过'|'分隔, 增加拦截器的'+'可以省略)
ymp.intercept.settings.net.ymate.demo.controller.DemoController#__doLogout=before:net.ymate.demo.intercept.UserSessionInterceptor-|after:net.ymate.demo.intercept.UserStatusUpdateInterceptor+

记录类属性状态 (PropertyState)

通过在类成员变量上声明@PropertyState注解，并使用PropertyStateSupport工具类配合，便可以轻松实现对类成员属性的变化情况进行监控。

• @PropertyState注解：声明记录类成员属性值的变化；

  propertyName：成员属性名称，默认为空则采用当前成员名称；

  aliasName：自定义别名，默认为空；

  setterName：成员属性SET方法名称，默认为空；

• 示例代码：

    public class PropertyStateTest {
  
        @PropertyState(propertyName = "user_name")
        private String username;
  
        @PropertyState(aliasName = "年龄")
        private int age;
  
        public String getUsername() {
            return username;
        }
  
        public void setUsername(String username) {
            this.username = username;
        }
  
        public int getAge() {
            return age;
        }
  
        public void setAge(int age) {
            this.age = age;
        }
  
        public static void main(String[] args) throws Exception {
            PropertyStateTest _original = new PropertyStateTest();
            _original.setUsername("123456");
            _original.setAge(20);
            //
            PropertyStateSupport<PropertyStateTest> _support = PropertyStateSupport.create(_original);
            PropertyStateTest _new = _support.bind();
            _new.setUsername("YMPer");
            _new.setAge(30);
            //
            System.out.println("发生变更的字段名集合: " + Arrays.asList(_support.getChangedPropertyNames()));
            for (PropertyStateSupport.PropertyStateMeta _meta : _support.getChangedProperties()) {
                System.out.println("已将" + StringUtils.defaultIfBlank(_meta.getAliasName(), _meta.getPropertyName()) + "由" + _meta.getOriginalValue() + "变更为" + _meta.getNewValue());
            }
        }
    }
  

• 执行结果：

    发生变更的字段名集合: [user_name, age]
    已将user_name由123456变更为YMPer
    已将年龄由20变更为30
  

Event

事件服务，通过事件的注册、订阅和广播完成事件消息的处理，目的是为了减少代码侵入，降低模块之间的业务耦合度，事件消息采用队列存储，采用多线程接口回调实现消息及消息上下文对象的传输，支持同步和异步两种处理模式；

框架事件初始化配置参数

#-------------------------------------
# 框架事件初始化参数
#-------------------------------------

# 默认事件触发模式(不区分大小写)，取值范围：NORMAL-同步执行，ASYNC-异步执行，默认为ASYNC
ymp.event.default_mode=

# 事件管理提供者接口实现，默认为net.ymate.platform.core.event.impl.DefaultEventProvider
ymp.event.provider_class=

# 事件线程池初始化大小，默认为Runtime.getRuntime().availableProcessors()
ymp.event.thread_pool_size=

# 最大线程池大小，默认为 200
ymp.event.thread_max_pool_size=

# 线程队列大小，默认为 1024
ymp.event.thread_queue_size=

YMP核心事件对象

• ApplicationEvent：框架事件

    APPLICATION_INITED - 框架初始化
    APPLICATION_DESTROYED - 框架销毁
  

• ModuleEvent：模块事件

    MODULE_INITED - 模块初始化
    MODULE_DESTROYED - 模块销毁
  

注：以上只是YMP框架核心中包含的事件对象，其它模块中包含的事件对象将在其相应的文档描述中阐述；

事件的订阅

• 方式一：通过代码手动完成事件的订阅

    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            // 订阅模块事件
            YMP.get().getEvents().registerListener(ModuleEvent.class, new IEventListener<ModuleEvent>() {
                @Override
                public boolean handle(ModuleEvent context) {
                    switch (context.getEventName()) {
                        case MODULE_INITED:
                            // 注意：这段代码是不会被执行的，因为在我们进行事件订阅时，模块的初始化动作已经完成
                            System.out.println("Inited :" + context.getSource().getName());
                            break;
                        case MODULE_DESTROYED:
                            System.out.println("Destroyed :" + context.getSource().getName());
                            break;
                    }
                    return false;
                }
            });
        } finally {
            YMP.get().destroy();
        }
    }
  

• 方式二：通过@EventRegister注解和IEventRegister接口实现事件的订阅

    // 首先创建事件注册类，通过实现IEventRegister接口完成事件的订阅
    // 通过@EventRegister注解，该类将在YMP框架初始化时被自动加载
    @EventRegister
    public class DemoEventRegister implements IEventRegister {
        public void register(Events events) throws Exception {
            // 订阅模块事件
            events.registerListener(ModuleEvent.class, new IEventListener<ModuleEvent>() {
                @Override
                public boolean handle(ModuleEvent context) {
                    switch (context.getEventName()) {
                        case MODULE_INITED:
                            System.out.println("Inited :" + context.getSource().getName());
                            break;
                        case MODULE_DESTROYED:
                            System.out.println("Destroyed :" + context.getSource().getName());
                            break;
                    }
                    return false;
                }
            });
            //
            // ... 还可以添加更多的事件订阅代码
        }
    }
  
    // 框架启动测试
    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            // Do Nothing...
        } finally {
            YMP.get().destroy();
        }
    }
  

自定义事件

YMP的事件对象必须实现IEvent接口的同时需要继承EventContext对象，下面的代码就是一个自定义事件对象：

• 创建自定义事件对象

    public class DemoEvent extends EventContext<Object, DemoEvent.EVENT> implements IEvent {
  
        public enum EVENT {
            CUSTOM_EVENT_ONE, CUSTOM_EVENT_TWO
        }
  
        public DemoEvent(Object owner, Class<? extends IEvent> eventClass, EVENT eventName) {
            super(owner, eventClass, eventName);
        }
    }
  

  说明：EventContext的注解中的第一个参数代表事件源对象类型，第二个参数是指定用于事件监听事件名称的枚举类型；

• 注册自定义事件

  • 方式一：通过代码注册

      YMP.get().getEvents().registerEvent(DemoEvent.class);
    

  • 方式二：通过在自定义事件类上声明@Event注解，框架初始化时将被自动注册；

• 订阅自定义事件

  事件订阅（或监听）需实现IEventListener接口，该接口的handle方法返回值在同步触发模式下将影响事件监听队列是否终止执行，异步触发模式下请忽略此返回值；

    // 采用默认模式执行事件监听器
    YMP.get().getEvents().registerListener(DemoEvent.class, new IEventListener<DemoEvent>() {
  
        public boolean handle(DemoEvent context) {
            switch (context.getEventName()) {
                case CUSTOM_EVENT_ONE:
                    System.out.println("CUSTOM_EVENT_ONE");
                    break;
                case CUSTOM_EVENT_TWO:
                    System.out.println("CUSTOM_EVENT_TWO");
                    break;
            }
            return false;
        }
    });
  
    // 采用异步模式执行事件监听器
    YMP.get().getEvents().registerListener(Events.MODE.ASYNC, DemoEvent.class, new IEventListener<DemoEvent>() {
  
        public boolean handle(DemoEvent context) {
            ......
        }
    });
  

  当然，也可以通过@EventRegister注解和IEventRegister接口实现自定义事件的订阅；

  注：当某个事件被触发后，订阅（或监听）该事件的接口被回调执行的顺序是不能被保证的；

• 触发自定义事件

    YMP.get().getEvents().fireEvent(new DemoEvent(YMP.get(), DemoEvent.class, DemoEvent.EVENT.CUSTOM_EVENT_ONE));
    //
    YMP.get().getEvents().fireEvent(new DemoEvent(YMP.get(), DemoEvent.class, DemoEvent.EVENT.CUSTOM_EVENT_TWO));
  

• 示例测试代码：

    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            // 注册自定义事件对象
            YMP.get().getEvents().registerEvent(DemoEvent.class);
            // 注册自定义事件监听
            YMP.get().getEvents().registerListener(DemoEvent.class, new IEventListener<DemoEvent>() {
  
                public boolean handle(DemoEvent context) {
                    switch (context.getEventName()) {
                        case CUSTOM_EVENT_ONE:
                            System.out.println("CUSTOM_EVENT_ONE");
                            break;
                        case CUSTOM_EVENT_TWO:
                            System.out.println("CUSTOM_EVENT_TWO");
                            break;
                    }
                    return false;
                }
            });
            // 触发事件
            YMP.get().getEvents().fireEvent(new DemoEvent(YMP.get(), DemoEvent.class, DemoEvent.EVENT.CUSTOM_EVENT_ONE));
            YMP.get().getEvents().fireEvent(new DemoEvent(YMP.get(), DemoEvent.class, DemoEvent.EVENT.CUSTOM_EVENT_TWO));
        } finally {
            YMP.get().destroy();
        }
    }
  

Module

创建自定义模块

• 步骤一：根据业务需求创建需要对外暴露的业务接口

    public interface IDemoModule {
  
        // 为方便引用，定义模块名称常量
        String MODULE_NAME = "demomodule";
  
        // 返回自定义模块的参数配置接口对象
        IDemoModuleCfg getModuleCfg();
  
        // 对外暴露的业务方法
        String sayHi();
    }
  

• 步骤二：处理自定义模块的配置参数，下列代码假定测试模块有两个自定义参数

    // 定义模块配置接口
    public interface IDemoModuleCfg {
  
        String getModuleParamOne();
  
        String getModuleParamTwo();
    }
  
    // 实现模块配置接口
    public class DemoModuleCfg implements IDemoModuleCfg {
  
        private String __moduleParamOne;
  
        private String __moduleParamTwo;
  
        public DemoModuleCfg(YMP owner) {
            // 从YMP框架中获取模块配置映射
            Map<String, String> _moduleCfgs = owner.getConfig().getModuleConfigs(IDemoModule.MODULE_NAME);
            //
            __moduleParamOne = _moduleCfgs.get("module_param_one");
            __moduleParamTwo = _moduleCfgs.get("module_param_two");
        }
  
        public String getModuleParamOne() {
            return __moduleParamOne;
        }
  
        public String getModuleParamTwo() {
            return __moduleParamTwo;
        }
    }
  

• 步骤三：实现模块及业务接口

  注：一定不要忘记在模块实现类上声明@Module注解，这样才能被YMP框架自动扫描、加载并初始化；

    @Module
    public class DemoModule implements IModule, IDemoModule {
  
        private YMP __owner;
  
        private IDemoModuleCfg __moduleCfg;
  
        private boolean __inited;
  
        public String getName() {
            return IDemoModule.MODULE_NAME;
        }
  
        public void init(YMP owner) throws Exception {
            if (!__inited) {
                __owner = owner;
                __moduleCfg = new DemoModuleCfg(owner);
                //
                __inited = true;
            }
        }
  
        public boolean isInited() {
            return __inited;
        }
  
        public YMP getOwner() {
            return __owner;
        }
  
        public IDemoModuleCfg getModuleCfg() {
            return __moduleCfg;
        }
  
        public void destroy() throws Exception {
            if (__inited) {
                __inited = false;
                //
                __moduleCfg = null;
                __owner = null;
            }
        }
  
        public String sayHi() {
            return "Hi, YMP!";
        }
    }
  

• 步骤四：在YMP的配置文件ymp-conf.properties中添加模块的配置内容

  格式： ymp.configs.<模块名称>.<参数名称>=[参数值]

    ymp.configs.demomodule.module_param_one=module_param_one_value
    ymp.configs.demomodule.module_param_two=module_param_two_value
  

调用自定义模块

public static void main(String[] args) throws Exception {
    YMP.get().init();
    try {
        // 获取自定义模块实例对象
        IDemoModule _demoModule = YMP.get().getModule(IDemoModule.class);
        // 调用模块业务接口方法
        System.out.println(_demoModule.sayHi());
        // 调用模块配置信息
        System.out.println(_demoModule.getModuleCfg().getModuleParamOne());
    } finally {
        YMP.get().destroy();
    }
}

注：自定义模块不支持IoC、AOP等特性；

I18N

I18N服务是在YMP框架启动时初始化，其根据ymp.i18n_default_locale进行语言配置，默认采用系统运行环境的语言设置；

• 国际化资源管理器提供的主要方法：

  • 获取当前语言设置

      I18N.current();
    

  • 设置当前语言

      // 变更当前语言设置且不触发事件
      I18N.current(Locale.ENGLISH);
    
      或者
    
      // 将触发监听处理器onChanged事件
      I18N.change(Locale.ENGLISH);
    

  • 根据当前语言设置，加载指定名称资源文件内指定的属性值

      I18N.load("resources", "home_title");
    
      或者
    
      I18N.load("resources", "home_title", "首页");
    

  • 格式化消息字符串并绑定参数

      // 加载指定名称资源文件内指定的属性并使用格式化参数绑定
      I18N.formatMessage("resources", "site_title", "Welcome {0}, {1}"，"YMP"，“GoodLuck！”);
    
      // 使用格式化参数绑定
      I18N.formatMsg("Hello, {0}, {1}", "YMP"，“GoodLuck！”);
    

• 国际化资源管理器事件监听处理器，通过实现II18NEventHandler接口，在YMP配置文件中的i18n_event_handler_class参数进行设置，该监听器可以完成如下操作：

  • 自定义资源文件加载过程

  • 自定义获取当前语言设置

  • 语言设置变更的事件处理过程

Lang

BlurObject：模糊对象

BlurObject.bind("1234").toLongValue();

PairObject：结对对象

List<String> _key = new ArrayList<String>();
Map<String, String> _value = new HashMap<String, String>();
...
PairObject _pObj = new PairObject(_key, _value);

//
_pObj.getKey();
//
_pObj.getValue();

TreeObject：树型对象

Object _id = UUIDUtils.UUID();
TreeObject _target = new TreeObject()
        .put("id", _id)
        .put("category", new Byte[]{1, 2, 3, 4})
        .put("create_time", new Date().getTime(), true)
        .put("is_locked", true)
        .put("detail", new TreeObject()
                .put("real_name", "汉字将被混淆", true)
                .put("age", 32));

// 这样赋值是List
TreeObject _list = new TreeObject();
_list.add("list item 1");
_list.add("list item 2");

// 这样赋值代表Map
TreeObject _map = new TreeObject();
_map.put("key1", "keyvalue1");
_map.put("key2", "keyvalue2");

TreeObject idsT = new TreeObject();
idsT.put("ids", _list);
idsT.put("maps", _map);

// List操作
System.out.println(idsT.get("ids").isList());
System.out.println(idsT.get("ids").getList());

// Map操作
System.out.println(idsT.get("maps").isMap());
System.out.println(idsT.get("maps").getMap());

//
_target.put("map", _map);
_target.put("list", _list);

//
System.out.println(_target.get("detail").getMixString("real_name"));

// TreeObject对象转换为JSON字符串输出
String _jsonStr = _target.toJson().toJSONString();
System.out.println(_jsonStr);

// 通过JSON字符串转换为TreeObject对象-->再转为JSON字符串输出
String _jsonStrTmp = (_target = TreeObject.fromJson(_target.toJson())).toJson().toJSONString();
System.out.println(_jsonStrTmp);
System.out.println(_jsonStr.equals(_jsonStrTmp));

Util

关于YMP框架常用的工具类，这里着重介绍以下几个：

• ClassUtils提供的BeanWrapper工具，它是一个类对象包裹器，赋予对象简单的属性操作能力；

    public static void main(String[] args) throws Exception {
        // 包裹一个Bean对象
        ClassUtils.BeanWrapper<DemoBean> _w = ClassUtils.wrapper(new DemoBean());
        // 输出该对象的成员属性名称
        for (String _fieldName : _w.getFieldNames()) {
            System.out.println(_fieldName);
        }
        // 为成员属性设置值
        _w.setValue("name", "YMP");
        // 获取成员属性值
        _w.getValue("name");
        // 拷贝Bean对象属性到目标对象(不局限相同对象)
        DemoBean _bean = _w.duplicate(new DemoBean());
        // 将对象属性转为Map存储
        Map<String, Object> _maps = _w.toMap();
        // 通过Map对象构建Bean对象并获取Bean实例
        DemoBean _target = ClassUtils.wrapper(DemoBean.class).fromMap(_maps).getTargetObject();
    }
  

• RuntimeUtils运行时工具类，获取运行时相关信息；

  • 获取当前环境变量：

      RuntimeUtils.getSystemEnvs();
    
      RuntimeUtils.getSystemEnv("JAVA_HOME");
    

  • 判断当前运行环境操作系统：

      RuntimeUtils.isUnixOrLinux();
    
      RuntimeUtils.isWindows();
    

  • 获取应用根路径：若WEB工程则基于.../WEB-INF/返回，若普通工程则返回类所在路径

      RuntimeUtils.getRootPath();
    
      RuntimeUtils.getRootPath(false);
    

  • 替换环境变量：支持${root}、${user.dir}和${user.home}环境变量占位符替换

      RuntimeUtils.replaceEnvVariable("${root}/home");
    

配置体系（Configuration）

配置体系模块，是通过简单的目录结构实现在项目开发以及维护过程中，对配置等各种文件资源的统一管理，为模块化开发和部署提供灵活的、简单有效的解决方案；

Maven包依赖

<dependency>
    <groupId>net.ymate.platform</groupId>
    <artifactId>ymate-platform-configuration</artifactId>
    <version><VERSION></version>
</dependency>

注：在项目的pom.xml中添加上述配置，该模块已经默认引入核心包依赖，无需重复配置。

特点

• 从开发角度规范了模块化开发流程、统一资源文件的生命周期管理；
• 从可维护角度将全部资源集成在整个体系中，具备有效的资源重用和灵活的系统集成构建、部署和数据备份与迁移等优势；
• 简单的配置文件检索、加载及管理模式；
• 模块间资源共享，模块(modules)可以共用所属项目(projects)的配置、类和jar包等资源文件；
• 默认支持XML和Properties配置文件解析，可以通过IConfigurationProvider接口自定义文件格式，支持缓存，避免重复加载；
• 配置对象支持@Configuration注解方式声明，无需编码即可自动加载并填充配置内容到类对象；
• 集成模块的构建（编译）与分发、服务的启动与停止，以及清晰的资源文件分类结构可快速定位；

配置体系目录结构

按优先级由低到高的顺序依次是：全局(configHome) -> 项目(projects) -> 模块(modules)：

CONFIG_HOME\
    |--bin\
    |--cfgs\
    |--classes\
    |--dist\
    |--lib\
    |--logs\
    |--plugins\
    |--projects\
    |   |--<project_xxx>
    |   |   |--cfgs\
    |   |   |--classes\
    |   |   |--lib\
    |   |   |--logs\
    |   |   |--modules\
    |   |   |   |--<module_xxx>
    |   |   |   |   |--cfgs\
    |   |   |   |   |--classes\
    |   |   |   |   |--lib\
    |   |   |   |   |--logs\
    |   |   |   |   |--plugins\
    |   |   |   |   |--<......>
    |   |   |   |--<......>
    |   |   |--plugins\
    |   |--<......>
    |--temp\
    |--......

模块配置

配置体系模块初始化参数, 将下列配置项按需添加到ymp-conf.properties文件中, 否则模块将使用默认配置进行初始化:

    #-------------------------------------
    # 配置体系模块初始化参数
    #-------------------------------------
    
    # 配置体系根路径，必须绝对路径，前缀支持${root}、${user.home}和${user.dir}变量，默认为${root}
    ymp.configs.configuration.config_home=
    
    # 项目名称，做为根路径下级子目录，对现实项目起分类作用，默认为空
    ymp.configs.configuration.project_name=
    
    # 模块名称，此模块一般指现实项目中分拆的若干子项目的名称，默认为空
    ymp.configs.configuration.module_name=
    
    # 配置文件检查时间间隔(毫秒)，默认值为0表示不开启
    ymp.configs.configuration.config_check_time_interval=
    
    # 指定配置体系下的默认配置文件分析器，默认为net.ymate.platform.configuration.impl.DefaultConfigurationProvider
    ymp.configs.configuration.provider_class=

注：配置体系根路径config_home配置参数，可以通过JVM启动参数方式进行配置，如：java -jar -Dymp.config_home=...，这种方式将优先于配置文件。

示例一：解析XML配置

• 基于XML文件的基础配置格式如下, 为了配合测试代码, 请将该文件命名为configuration.xml并放置在config_home路径下的cfgs目录里:

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- XML根节点为properties -->
    <properties>
  
        <!-- 分类节点为category, 默认分类名称为default -->
        <category name="default">
  
            <!-- 属性标签为property, name代表属性名称, value代表属性值(也可以用property标签包裹) -->
            <property name="company_name" value="Apple Inc."/>
  
            <!-- 用属性标签表示一个数组或集合数据类型的方法 -->
            <property name="products">
                <!-- 集合元素必须用value标签包裹, 且value标签不要包括任何扩展属性 -->
                <value>iphone</value>
                <value>ipad</value>
                <value>imac</value>
                <value>itouch</value>
            </property>
  
            <!-- 用属性标签表示一个MAP数据类型的方法, abc代表扩展属性key, xyz代表扩展属性值, 扩展属性与item将被合并处理  -->
            <property name="product_spec" abc="xzy">
                <!-- MAP元素用item标签包裹, 且item标签必须包含name扩展属性(其它扩展属性将被忽略), 元素值由item标签包裹 -->
                <item name="color">red</item>
                <item name="weight">120g</item>
                <item name="size">small</item>
                <item name="age">2015</item>
            </property>
        </category>
    </properties>
  

• 新建配置类DemoConfig, 通过@Configuration注解指定配置文件相对路径

    @Configuration("cfgs/configuration.xml")
    public class DemoConfig extends DefaultConfiguration {
    }
  

• 测试代码, 完成模块初始化并加载配置文件内容:

    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            DemoConfig _cfg = new DemoConfig();
            if (Cfgs.get().fillCfg(_cfg)) {
                System.out.println(_cfg.getString("company_name"));
                System.out.println(_cfg.getMap("product_spec"));
                System.out.println(_cfg.getList("products"));
            }
        } finally {
            YMP.get().destroy();
        }
    }
  

• 执行结果:

    Apple Inc.
    {abc=xzy, color=red, size=small, weight=120g, age=2015}
    [itouch, imac, ipad, iphone]
  

示例二：解析Properties配置

• 基于Properties文件的基础配置格式如下, 同样请将该文件命名为configuration.properties并放置在config_home路径下的cfgs目录里:

    #--------------------------------------------------------------------------
    # 配置文件内容格式: properties.<categoryName>.<propertyName>=[propertyValue]
    #
    # 注意: attributes将作为关键字使用, 用于表示分类, 属性, 集合和MAP的子属性集合
    #--------------------------------------------------------------------------
  
    # 举例1: 默认分类下表示公司名称, 默认分类名称为default
    properties.default.company_name=Apple Inc.
  
    #--------------------------------------------------------------------------
    # 数组和集合数据类型的表示方法: 多个值之间用'|'分隔, 如: Value1|Value2|...|ValueN
    #--------------------------------------------------------------------------
    properties.default.products=iphone|ipad|imac|itouch
  
    #--------------------------------------------------------------------------
    # MAP<K, V>数据类型的表示方法:
    # 如:产品规格(product_spec)的K分别是color|weight|size|age, 对应的V分别是热red|120g|small|2015
    #--------------------------------------------------------------------------
    properties.default.product_spec.color=red
    properties.default.product_spec.weight=120g
    properties.default.product_spec.size=small
    properties.default.product_spec.age=2015
  
    # 每个MAP都有属于其自身的属性列表(深度仅为一级), 用attributes表示, abc代表属性key, xyz代表属性值
    # 注: MAP数据类型的attributes和MAP本身的表示方法达到的效果是一样的
    properties.default.product_spec.attributes.abc=xyz
  

• 修改配置类DemoConfig如下, 通过@ConfigurationProvider注解指定配置文件内容解析器:

    @Configuration("cfgs/configuration.properties")
    @ConfigurationProvider(PropertyConfigurationProvider.class)
    public class DemoConfig extends DefaultConfiguration {
    }
  

• 重新执行示例代码, 执行结果与示例一结果相同:

    Apple Inc.
    {abc=xzy, color=red, size=small, weight=120g, age=2015}
    [itouch, imac, ipad, iphone]
  

示例三：无需创建配置对象, 直接加载配置文件

public static void main(String[] args) throws Exception {
    YMP.get().init();
    try {
        IConfiguration _cfg = Cfgs.get().loadCfg("cfgs/configuration.properties");
        if (_cfg != null) {
            System.out.println(_cfg.getString("company_name"));
            System.out.println(_cfg.getMap("product_spec"));
            System.out.println(_cfg.getList("products"));
        }
    } finally {
        YMP.get().destroy();
    }
}

示例四：通过@Configurable注解并配合IConfigurable接口实现配置文件自动装配

public interface IDemoService {

    String getCompanyName();
}

@Bean
@Configurable(type = DemoConfig.class)
public class DemoService extends AbstractConfigurable<DemoConfig> implements IDemoService {

    @Override
    public String getCompanyName() {
        return getConfig().getString("company_name");
    }
}

配置体系模块更多操作

获取路径信息

下列方法的返回结果会根据配置体系模块配置的不同而不同:

// 返回配置体系根路径
Cfgs.get().getConfigHome();

// 返回项目根路径
Cfgs.get().getProjectHome();

// 返回项目模块根路径
Cfgs.get().getModuleHome();

// 返回user.dir所在路径
Cfgs.get().getUserDir();

// 返回user.home所在路径
Cfgs.get().getUserHome();

搜索目标文件

// 在配置体系中搜索cfgs/configuration.xml文件并返回其File对象
Cfgs.get().searchFile("cfgs/configuration.xml");

// 在配置体系中搜索cfgs/configuration.properties文件并返回其绝对路径
Cfgs.get().searchPath("cfgs/configuration.properties");

日志（Log）

基于开源日志框架Log4J 2实现，提供对日志记录器对象的统一管理，可以在任意位置调用任意日志记录器输出日志，实现系统与业务日志的分离；与YMP配置体系模块配合使用，效果更佳:)

日志框架同时提供扩展支持的两个子项目：

• log-jcl：用于整合apache-commons-logging日志框架；
• log-slf4j：针对slf4j日志系统提供支持；

Maven包依赖

• Log依赖配置

    <dependency>
        <groupId>net.ymate.platform</groupId>
        <artifactId>ymate-platform-log</artifactId>
        <version><VERSION></version>
    </dependency>
  

• log-jcl依赖配置

    <dependency>
        <groupId>net.ymate.platform</groupId>
        <artifactId>ymate-platform-log-jcl</artifactId>
        <version><VERSION></version>
    </dependency>
  

• log-slf4j依赖配置

    <dependency>
        <groupId>net.ymate.platform</groupId>
        <artifactId>ymate-platform-log-slf4j</artifactId>
        <version><VERSION></version>
    </dependency>
  

注：请根据您项目的实际情况，在项目的pom.xml中添加相应配置，该模块已经默认引入核心包依赖，无需重复配置。

模块事件

LogEvent事件枚举对象包括以下事件类型：

事务类型	说明
LOG_WRITE_IN	日志写入时触发该事件

模块配置

日志模块初始化参数, 将下列配置项按需添加到ymp-conf.properties文件中, 否则模块将使用默认配置进行初始化:

  #-------------------------------------
  # 日志模块初始化参数
  #-------------------------------------

  # 日志记录器配置文件，默认为${root}/cfgs/log4j.xml，变量${user.dir}的取值结果将受配置体系模块影响
  ymp.configs.log.config_file=
  
  # 日志文件输出路径，默认为${root}/logs/
  ymp.configs.log.output_dir=
  
  # 日志记录器默认名称，默认为default
  ymp.configs.log.logger_name=
  
  # 日志记录器接口实现类，默认为net.ymate.platform.log.impl.DefaultLogger
  ymp.configs.log.logger_class=
  
  # 默认日志记录器是否允许控制台输出，默认为false
  ymp.configs.log.allow_output_console=

注：需要注意config_file配置的log4j.xml文件是否存在，以及output_dir指定的输出路径是否正确有效，这两项配置会影响YMP框架启动时异常；

此外，建议在开发阶段将allow_output_console参数设置为true，这样可以通过控制台直接查看日志输出；

Log4J配置文件，内容如下：

    <?xml version="1.0" encoding="UTF-8"?>
    <Configuration>
        <Appenders>
            <RollingFile name="default" fileName="${sys:LOG_OUT_DIR}/default.log"
                         filePattern="${sys:LOG_OUT_DIR}/$${date:yyyy-MM}/default-%d{MM-dd-yyyy}-%i.log.gz">
                <PatternLayout pattern="%m %n" charset="UTF-8"/>
                <SizeBasedTriggeringPolicy size="500 MB"/>
            </RollingFile>
            <!--
            <RollingFile name="custom-logname" fileName="${sys:LOG_OUT_DIR}/custom-logname.log"
                         filePattern="${sys:LOG_OUT_DIR}/$${date:yyyy-MM}/custom-logname-%d{MM-dd-yyyy}-%i.log.gz">
                <PatternLayout pattern="%m %n" charset="UTF-8"/>
                <SizeBasedTriggeringPolicy size="500 MB"/>
            </RollingFile>
            -->
        </Appenders>
        <Loggers>
            <!--
            <Logger name="custom-logname" level="debug">
                <AppenderRef ref="custom-logname"/>
            </Logger>
            -->
            <!-- 配置记录器级别 -->
            <Root level="debug">
                <!-- 输出设置 -->
                <AppenderRef ref="default"/>
            </Root>
        </Loggers>
    </Configuration>

**注**：该文件应根据ymp.configs.log.config_file指定的位置，其内容请根据实际情况调整。

使用示例

首先，为了配合演示多个日志记录器的使用方法，修改log4j.xml配置内容如下：

  <?xml version="1.0" encoding="UTF-8"?>
  <Configuration>
      <Appenders>
          <RollingFile name="default" fileName="${sys:LOG_OUT_DIR}/default.log"
                       filePattern="${sys:LOG_OUT_DIR}/$${date:yyyy-MM}/default-%d{MM-dd-yyyy}-%i.log.gz">
              <PatternLayout pattern="%m %n" charset="UTF-8"/>
              <SizeBasedTriggeringPolicy size="500 MB"/>
          </RollingFile>

          <RollingFile name="wechat" fileName="${sys:LOG_OUT_DIR}/wechat.log"
                       filePattern="${sys:LOG_OUT_DIR}/$${date:yyyy-MM}/wechat-%d{MM-dd-yyyy}-%i.log.gz">
              <PatternLayout pattern="%m %n" charset="UTF-8"/>
              <SizeBasedTriggeringPolicy size="500 MB"/>
          </RollingFile>

      </Appenders>
      <Loggers>

          <Logger name="wechat" level="debug">
              <AppenderRef ref="wechat"/>
          </Logger>

          <!-- 配置记录器级别 -->
          <Root level="debug">
              <!-- 输出设置 -->
              <AppenderRef ref="default"/>
          </Root>
      </Loggers>
  </Configuration>

上面的配置文件中共配置两个日志记录器：

• default：默认根日志记录器，它将记录所有日志内容；
• wechat：自定义的日志记录器；

示例代码：

• 使用默认日志记录器输出：

    Logs.get().getLogger().debug("日志将被输出到default.log文件...");
    Logs.get().getLogger().debug("日志内容", e);
  

  注：默认日志记录器是由logger_name参数指定的，默认值为default；

• 输出日志到wechat.log文件中：

    ILogger _wechat = Logs.get().getLogger("wechat");
    _wechat.debug("日志将被分别输出到wechat.log和default.log文件中");
    //
    if (_wechat.isDebugEnabled()) {
    	_wechat.debug("日志内容", e);
    }
  
    // 或者
    Logs.get().getLogger("wechat").info("日志内容");
  

怀旧版业务日志记录工具使用示例

通过@Loggable注解与Logoo类配合来记录完整业务逻辑处理过程；

• @Loggable: 声明一个类对业务日志记录工具的支持或声明一个方法开始业务日志记录器：

  value[]：设定输出到日志记录器名称集合，可选；

  flag：自定义标识；

  action：自定义动作标识；

  level：日志输出级别, 默认为: INFO；

  merge：是否日志合并输出, 默认为: false；

  adapterClass：自定义日志适配器类；

• 示例代码：：

    public class DemoLogooAdapter extends DefaultLogooAdapter {
  
        @Override
        public void onLogWritten(String flag, String action, Map<String, Object> attributes) {
            // 自定义业务逻辑处理过程中传递的参数, 如: 写入数据库等
            System.out.println("业务逻辑处理完毕...");
        }
    }
  
    @Controller
    @RequestMapping("/hello")
    @Loggable(value = "custom", flag = "示例:")
    public class HelloController {
  
        @RequestMapping("/")
        @Loggable(flag = "逻辑处理", merge = true, adapterClass = DemoLogooAdapter.class)
        public IView hello() throws Exception {
            // 输出日志
            Logoo.log("日志输出...");
            // 传递参数
            Logoo.addAttribute("key1", "value1);
            //
            Logoo.finished();
            //
            return View.textView("Hello YMP world!");
        }
    }
  

缓存（Cache）

缓存模块是以EhCache作为默认JVM进程内缓存服务，通过整合外部Redis服务实现多级缓存（MultiLevel）的轻量级缓存框架，并与YMP框架深度集成(支持针对类方法的缓存，可以根据方法参数值进行缓存)，灵活的配置、易于使用和扩展；

Maven包依赖

<dependency>
    <groupId>net.ymate.platform</groupId>
    <artifactId>ymate-platform-cache</artifactId>
    <version><VERSION></version>
</dependency>

注：

• 在项目的pom.xml中添加上述配置，该模块已经默认引入核心包依赖，无需重复配置。

• 若需要启用redis作为缓存服务，请添加以下依赖配置：

    <dependency>
        <groupId>net.ymate.platform</groupId>
        <artifactId>ymate-platform-persistence-redis</artifactId>
        <version><VERSION></version>
    </dependency>
  

基础接口概念

开发者可以根据以下接口完成对缓存模块的自定义扩展实现；

• 缓存服务提供者(ICacheProvider)接口：

  • DefaultCacheProvider - 基于EhCache缓存服务的默认缓存服务提供者接口实现类；
  • RedisCacheProvider - 基于Redis数据库的缓存服务提供者接口实现类；
  • MultievelCacheProvider - 融合EhCache和Redis两者的缓存服务提供者接口实现类，通过MultilevelKey决定缓存对象的获取方式；

• 缓存Key生成器(IKeyGenerator)接口：

  • DefaultKeyGenerator - 根据提供的类方法和参数对象生成缓存Key，默认是将方法和参数对象进行序列化后取其MD5值；

• 序列化服务(ISerializer)接口：

  • DefaultSerializer - 默认序列化服务采用JDK自带的对象序列化技术实现；

• 缓存事件监听(ICacheEventListener)接口：用于监听被缓存对象发生变化时的事件处理，需开发者实现接口；

• 缓存作用域处理器(ICacheScopeProcessor)接口：用于处理@Cacheable注解的Scope参数设置为非DEFAULT作用域的缓存对象，需开发者实现接口；

模块配置

初始化参数配置

#-------------------------------------
# 缓存模块初始化参数
#-------------------------------------

# 缓存提供者，可选参数，默认值为default，目前支持[default|redis|multilevel]或自定义类名称
ymp.configs.cache.provider_class=

# 缓存对象事件监听器，可选参数，默认值为net.ymate.platform.cache.impl.DefaultCacheEventListener
ymp.configs.cache.event_listener_class=

# 缓存作用域处理器，可选参数，默认值为空
ymp.configs.cache.scope_processor_class=

# 缓存Key生成器，可选参数，为空则采用框架默认net.ymate.platform.cache.impl.DefaultKeyGenerator
ymp.configs.cache.key_generator_class=

# 对象序列化接口实现，可选参数，默认值为net.ymate.platform.cache.impl.DefaultSerializer
ymp.configs.cache.serializer_class=

# 默认缓存名称，可选参数，默认值为default，对应于Ehcache配置文件中设置name="__DEFAULT__"
ymp.configs.cache.default_cache_name=

# 缓存数据超时时间，可选参数，数值必须大于等于0，为0表示默认缓存300秒
ymp.configs.cache.default_cache_timeout=

EhCache配置示例

请将以下内容保存在ehcache.xml文件中，并放置在classpath根路径下；

<ehcache updateCheck="false" dynamicConfig="false">

    <diskStore path="java.io.tmpdir"/>

    <cacheManagerEventListenerFactory class="" properties=""/>

    <defaultCache
            maxElementsInMemory="1000"
            eternal="false"
            timeToIdleSeconds="60"
            timeToLiveSeconds="120"
            overflowToDisk="true">
    </defaultCache>

    <cache name="__DEFAULT__"
           maxElementsInMemory="5000"
           eternal="false"
           timeToIdleSeconds="1800"
           timeToLiveSeconds="1800"
           overflowToDisk="false"
    />
</ehcache>

模块事件

当event_listener_class采用默认配置时，可以通过CacheEvent捕获缓存事件，事件枚举对象包括以下事件类型：

事务类型	说明
ELEMENT_PUT	添加元素到缓存
ELEMENT_UPDATED	缓存元素更新
ELEMENT_EXPIRED	缓存元素过期
ELEMENT_EVICTED
ELEMENT_REMOVED	缓存元素删除
ELEMENT_REMOVED_ALL	缓存清空

模块使用

示例一：直接通过缓存模块操作缓存数据

public static void main(String[] args) throws Exception {
    YMP.get().init();
    try {
        // 操作默认缓存
        Caches.get().put("key1", "value1");
        System.out.println(Caches.get().get("key1"));
        // 操作指定名称的缓存
        Caches.get().put("default", "key2", "value2");
        System.out.println(Caches.get().get("default", "key2"));
    } finally {
        YMP.get().destroy();
    }
}

注：当指定缓存名称时，请确认与名称对应的配置是否已存在；

执行结果：

value1
value2

示例二：基于注解完成类方法的缓存

这里用到了@Cacheable注解，作用是标识类中方法的执行结果是否进行缓存，需要注意的是：

首先@Cacheable注解必须在已注册到YMP类对象管理器的类上声明，表示该类支持缓存；

其次，在需要缓存执行结果的方法上添加@Cacheable注解；

@Cacheable注解参数说明：

cacheName：缓存名称, 默认值为default；

key：缓存Key, 若未设置则使用keyGenerator自动生成；

generator：Key生成器接口实现类，默认为DefaultKeyGenerator.class；

scope：缓存作用域，可选值为APPLICATION、SESSION和DEFAULT，默认为DEFAULT，非DEFAULT设置需要缓存作用域处理器(ICacheScopeProcessor)接口配合；

timeout：缓存数据超时时间, 可选参数，数值必须大于等于0，为0表示默认缓存300秒；

示例代码：

@Bean
@Cacheable
public class CacheDemo {

    @Cacheable
    public String sayHi(String name) {
        System.out.println("No Cached");
        return "Hi, " + name;
    }

    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            CacheDemo _demo = YMP.get().getBean(CacheDemo.class);
            System.out.println(_demo.sayHi("YMP"));
            System.out.println(_demo.sayHi("YMP"));
            //
            System.out.println("--------");
            //
            System.out.println(_demo.sayHi("YMPer"));
            System.out.println(_demo.sayHi("YMP"));
            System.out.println(_demo.sayHi("YMPer"));
        } finally {
            YMP.get().destroy();
        }
    }
}

执行结果：

No Cached
Hi, YMP
Hi, YMP
--------
No Cached
Hi, YMPer
Hi, YMP
Hi, YMPer

以上结果输出可以看出，sayHi方法相同参数首次被调用时将输出“No Cached”字符串，说明它没有使用缓存，再次调用时直接从缓存中返回值；

JDBC

JDBC持久化模块针对关系型数据库(RDBMS)数据存取的一套简单解决方案，主要关注数据存取的效率、易用性和透明，其具备以下功能特征：

• 基于JDBC框架API进行轻量封装，结构简单、便于开发、调试和维护；
• 优化批量数据更新、标准化结果集、预编译SQL语句处理；
• 支持单实体ORM操作，无需编写SQL语句；
• 提供脚手架工具，快速生成数据实体类，支持链式调用；
• 支持通过存储器注解自定义SQL语句或从配置文件中加载SQL并自动执行；
• 支持结果集与值对象的自动装配，支持自定义装配规则；
• 支持多数据源，默认支持C3P0、DBCP、JNDI连接池配置，支持数据源扩展；
• 支持多种数据库(如:Oracle、MySQL、SQLServer等)；
• 支持面向对象的数据库查询封装，有助于减少或降低程序编译期错误；
• 支持数据库事务嵌套；
• 支持数据库视图和存储过程；

Maven包依赖

<dependency>
    <groupId>net.ymate.platform</groupId>
    <artifactId>ymate-platform-persistence-jdbc</artifactId>
    <version><VERSION></version>
</dependency>

注：在项目的pom.xml中添加上述配置，该模块已经默认引入核心包及持久化基础包依赖，无需重复配置。

####模块初始化配置

#-------------------------------------
# JDBC持久化模块初始化参数
#-------------------------------------

# 默认数据源名称，默认值为default
ymp.configs.persistence.jdbc.ds_default_name=

# 数据源列表，多个数据源名称间用'|'分隔，默认为default
ymp.configs.persistence.jdbc.ds_name_list=

# 是否显示执行的SQL语句，默认为false
ymp.configs.persistence.jdbc.ds.default.show_sql=

# 是否开启堆栈跟踪，默认为false
ymp.configs.persistence.jdbc.ds.default.stack_traces=

# 堆栈跟踪层级深度，默认为0(即全部)
ymp.configs.persistence.jdbc.ds.default.stack_trace_depth=

# 堆栈跟踪包名前缀过滤，默认为空
ymp.configs.persistence.jdbc.ds.default.stack_trace_package=

# 数据库表前缀名称，默认为空
ymp.configs.persistence.jdbc.ds.default.table_prefix=

# 数据源适配器，可选值为已知适配器名称或自定义适配置类名称，默认为default，目前支持已知适配器[default|dbcp|c3p0|jndi|...]
ymp.configs.persistence.jdbc.ds.default.adapter_class=

# 数据库类型，可选参数，默认值将通过连接字符串分析获得，目前支持[mysql|oracle|sqlserver|db2|sqlite|postgresql|hsqldb|h2]
ymp.configs.persistence.jdbc.ds.default.type=

# 数据库方言，可选参数，自定义方言将覆盖默认配置
ymp.configs.persistence.jdbc.ds.default.dialect_class=

# 数据库引用标识符，默认为空
ymp.configs.persistence.jdbc.ds.default.identifier_quote=

# 数据库连接驱动，可选参数，框架默认将根据数据库类型进行自动匹配
ymp.configs.persistence.jdbc.ds.default.driver_class=

# 数据库连接字符串，必填参数
ymp.configs.persistence.jdbc.ds.default.connection_url=

# 数据库访问用户名称，必填参数
ymp.configs.persistence.jdbc.ds.default.username=

# 数据库访问密码，可选参数，经过默认密码处理器加密后的admin字符串为wRI2rASW58E
ymp.configs.persistence.jdbc.ds.default.password=

# 数据库访问密码是否已加密，默认为false
ymp.configs.persistence.jdbc.ds.default.password_encrypted=

# 数据库密码处理器，可选参数，用于对已加密数据库访问密码进行解密，默认为空
ymp.configs.persistence.jdbc.ds.default.password_class=

配置参数补充说明：

数据源的数据库连接字符串和用户名是必填项，其它均为可选参数，最简配置如下：

ymp.configs.persistence.jdbc.ds.default.connection_url=jdbc:mysql://localhost:3306/mydb

ymp.configs.persistence.jdbc.ds.default.username=root

为了避免明文密码出现在配置文件中，YMP框架提供了默认的数据库密码处理器，或者通过IPasswordProcessor接口自行实现；

net.ymate.platform.core.support.impl.DefaultPasswordProcessor

数据源（DataSource）

多数据源连接

JDBC持久化模块默认支持多数据源配置，下面通过简单的配置来展示如何连接多个数据库：

# 定义两个数据源分别用于连接MySQL和Oracle数据库，同时指定默认数据源为default(即MySQL数据库)
ymp.configs.persistence.jdbc.ds_default_name=default
ymp.configs.persistence.jdbc.ds_name_list=default|oracledb

# 连接到MySQL数据库的数据源配置
ymp.configs.persistence.jdbc.ds.default.connection_url=jdbc:mysql://localhost:3306/mydb
ymp.configs.persistence.jdbc.ds.default.username=root
ymp.configs.persistence.jdbc.ds.default.password=123456

# 连接到Oracle数据库的数据源配置
ymp.configs.persistence.jdbc.ds.oracledb.connection_url=jdbc:oracle:thin:@localhost:1521:ORCL
ymp.configs.persistence.jdbc.ds.oracledb.username=ORCL
ymp.configs.persistence.jdbc.ds.oracledb.password=123456

从上述配置中可以看出，配置不同的数据源时只需要定义数据源名称列表，再根据列表逐一配置即可；

连接池配置

JDBC持久化模块提供的数据源类型如下：

• default：默认数据源适配器，通过DriverManager直接连接数据库，建议仅用于测试；
• c3p0：基于C3P0连接池的数据源适配器；
• dbcp：基于DBCP连接池的数据源适配器；
• jndi：基于JNDI的数据源适配器；

只需根据实际情况调整对应数据源名称的配置，如：

ymp.configs.persistence.jdbc.ds.default.adapter_class=dbcp

针对于dbcp和c3p0连接池的配置文件及内容，请将对应的dbcp.properties或c3p0.properties文件放置在工程的classpath根路径下，配置内容请参看JDBC持久化模块开源工程中的示例文件；

当然，也可以通过IDataSourceAdapter接口自行实现，框架针对IDataSourceAdapter接口提供了一个抽象封装AbstractDataSourceAdapter类，直接继承即可；

数据库连接持有者（IConnectionHolder）

用于记录真正的数据库连接对象（Connection）原始的状态及与数据源对应关系；

数据实体（Entity）

数据实体注解

• @Entity：声明一个类为数据实体对象；

  value：实体名称(数据库表名称)，默认采用当前类名称；

    @Entity("tb_demo")
    public class Demo {
        //...
    }
  

• @Id：声明一个类成员为主键；

  无参数，配合@Property注解使用；

    @Entity("tb_demo")
    public class Demo {
  
        @Id
        @Property
        private String id;
  
        public String getId() {
            return id;
        }
  
        public void setId(String id) {
            this.id = id;
        }
    }
  

• @Property：声明一个类成员为数据实体属性；

  name：实现属性名称，默认采用当前成员名称；

  autoincrement：是否为自动增长，默认为false；

  sequenceName：序列名称，适用于类似Oracle等数据库，配合autoincrement参数一同使用；

  nullable：允许为空，默认为true；

  unsigned：是否为无符号，默认为false；

  length：数据长度，默认0为不限制；

  decimals：小数位数，默认0为无小数；

  type：数据类型，默认为Type.FIELD.VARCHAR；

    @Entity("tb_user")
    public class User {
  
        @Id
        @Property
        private String id;
  
        @Property(name = "user_name",
                  nullable = false,
                  length = 32)
        private String username;
  
        @Property(name = "age",
                  unsigned = true,
                  type = Type.FIELD.INT)
        private Integer age;
  
        // 省略Get/Set方法...
    }
  

• @PK：声明一个类为某数据实体的复合主键对象；

  无参数；

    @PK
    public class UserExtPK {
  
        @Property
        private String uid;
  
        @Property(name = "wx_id")
        private String wxId;
  
        // 省略Get/Set方法...
    }
  
    @Entity("tb_user_ext")
    public class UserExt {
  
        @Id
        private UserExtPK id;
  
        @Property(name = "open_id",
                  nullable = false,
                  length = 32)
        private String openId;
  
        // 省略Get/Set方法...
    }
  

• @Readonly：声明一个成员为只读属性，数据实体更新时其将被忽略；

  无参数，配合@Property注解使用；

    @Entity("tb_demo")
    public class Demo {
  
        @Id
        @Property
        private String id;
  
        @Property(name = "create_time")
        @Readonly
        private Date createTime;
  
        // 省略Get/Set方法...
    }
  

• @Indexes：声明一组数据实体的索引；

• @Index：声明一个数据实体的索引；

• @Comment：注释内容；

• @Default：为一个成员属性或方法参数指定默认值；

看着这么多的注解，是不是觉得编写实体很麻烦呢，不要急，框架提供了自动生成实体的方法，往下看:)

注：上面注解或注解参数中有一些是用于未来能通过实体对象直接创建数据库表结构（以及SQL脚本文件）的，可以暂时忽略；

自动生成实体类

YMP框架自v1.0开始就支持通过数据库表结构自动生成实体类代码，所以v2.0版本不但重构了实体代码生成器，而且更简单好用！

#-------------------------------------
# JDBC数据实体代码生成器配置参数
#-------------------------------------

# 是否生成新的BaseEntity类，默认为false(即表示使用框架提供的BaseEntity类)
ymp.params.jdbc.use_base_entity=

# 是否使用类名后缀，不使用和使用的区别如: User-->UserModel，默认为false
ymp.params.jdbc.use_class_suffix=

# 是否采用链式调用模式，默认为false
ymp.params.jdbc.use_chain_mode=

# 是否添加类成员属性值状态变化注解，默认为false
ymp.params.jdbc.use_state_support=

# 实体及属性命名过滤器接口实现类，默认为空
ymp.params.jdbc.named_filter_class=

# 数据库名称(仅针对特定的数据库使用，如Oracle)，默认为空
ymp.params.jdbc.db_name=

# 数据库用户名称(仅针对特定的数据库使用，如Oracle)，默认为空
ymp.params.jdbc.db_username=

# 数据库表名称前缀，多个用'|'分隔，默认为空
ymp.params.jdbc.table_prefix=

# 否剔除生成的实体映射表名前缀，默认为false
ymp.params.jdbc.remove_table_prefix=

# 预生成实体的数据表名称列表，多个用'|'分隔，默认为空表示全部生成
ymp.params.jdbc.table_list=

# 排除的数据表名称列表，在此列表内的数据表将不被生成实体，多个用'|'分隔，默认为空
ymp.params.jdbc.table_exclude_list=

# 需要添加@Readonly注解声明的字段名称列表，多个用'|'分隔，默认为空
ymp.params.jdbc.readonly_field_list=

# 生成的代码文件输出路径，默认为${root}
ymp.params.jdbc.output_path=

# 生成的代码所属包名称，默认为: packages
ymp.params.jdbc.package_name=

实际上你可以什么都不用配置（请参看以上配置项说明，根据实际情况进行配置），但使用过程中需要注意以下几点：

• 代码生成器依赖JDBC持久化模块才能完成与数据库连接等操作；

• 在多数据源模式下，代码生成器使用的是默认数据源；

• 代码生成器依赖freemarker模板引擎，所以请检查依赖关系是否正确；

• 在WEB工程中运行代码生成器时请确认servlet-api和jsp-api包依赖关系是否正确；

• 如果你的工程中引用了很多的模块，在运行代码生成器时可以暂时通过ymp.excluded_modules参数排除掉；

• 如果使用的JDBC驱动是mysql-connector-java-6.x及以上版本时，则必须配置db_name和db_username参数；

• 实体及属性命名过滤器参数named_filter_class指定的类需要实现IEntityNamedFilter接口；

了解了以上的配置后，直接运行代码生成器：

net.ymate.platform.persistence.jdbc.scaffold.EntityGenerator

找到并运行它，如果是Maven项目，可以通过以下命令执执行：

mvn compile exec:java -Dexec.mainClass="net.ymate.platform.persistence.jdbc.scaffold.EntityGenerator"

OK！就这么简单，一切都结束了！

当然，上面介绍的实体生成方法还是有些麻烦，所以我们提供了另外一种更方便的方式 —— 通过YMP框架提供的Maven扩展工具生成实体：

• 步骤1：编译并安装ymate-maven-extension扩展工具

  • 下载YMP框架Maven扩展工具源码（点击这里查看此项目）

    执行命令：

      git clone https://git.oschina.net/suninformation/ymate-maven-extension.git
    

  • 编译并安装到本地Maven仓库

    执行命令:

      cd ymate-maven-extension
      mvn clean install
    

• 步骤2：将pom.xml中添加ymate-maven-plugin插件

    <plugin>
        <groupId>net.ymate.maven.plugins</groupId>
        <artifactId>ymate-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
    </plugin>
  

• 步骤3：执行插件生成实体

  在工程根路径下执行命令：

    mvn ymate:entity
  

  输出内容：

    Picked up JAVA_TOOL_OPTIONS: -Dfile.encoding=UTF-8
    [INFO] Scanning for projects...
    [INFO] ......（此处省略若干字）
    [INFO] --- ymate-maven-plugin:1.0-SNAPSHOT:entity (default-cli) @ ymp-examples-webapp ---
    三月 25, 2016 12:25:07 上午 net.ymate.platform.core.YMP init
    信息: 
    __   ____  __ ____          ____  
    \ \ / /  \/  |  _ \  __   _|___ \ 
     \ V /| |\/| | |_) | \ \ / / __) |
      | | | |  | |  __/   \ V / / __/ 
      |_| |_|  |_|_|       \_/ |_____|  Website: http://www.ymate.net/
    三月 25, 2016 12:25:07 上午 net.ymate.platform.core.YMP init
    信息: Initializing ymate-platform-core-2.0.0-GA build-20160324-2339 - debug:true
    ......（此处省略若干字）
    信息: [show tables][][1][13ms]
    Output file "/Users/suninformation/IdeaProjects/ymate-platform-examples/ymp-examples-webapp/src/main/java/net/ymate/platform/examples/model/User.java".
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 1.577s
    [INFO] Finished at: Fri Mar 25 00:25:08 CST 2016
    [INFO] Final Memory: 10M/163M
    [INFO] ------------------------------------------------------------------------
  

  通过插件生成的代码默认放置在src/main/java路径，当数据库表发生变化时，直接执行插件命令就可以快速更新数据实体对象，是不是很更方便呢，大家可以动手尝试一下！:p

事务（Transaction）

基于YMPv2.0的新特性，JDBC模块对数据库事务的处理更加灵活，任何被类对象管理器管理的对象都可以通过@Transaction注解支持事务；

• @Transaction注解：

  • 参数说明：

    value：事务类型（参考JDBC事务类型），默认为JDBC.TRANSACTION.READ_COMMITTED；

  • 使用方式：

    首先，需要数据库事务支持的类对象必须声明@Transaction注解；

    然后，在具体需要开启事务处理的类方法上添加@Transaction注解；

• 事务示例代码：

    public interface IUserService {
  
    	User doGetUser(String username, String pwd);
  
    	boolean doLogin(String username, String pwd);
    }
  
    @Bean
    @Transaction
    public class UserService implements IUserService {
  
    	public User doGetUser(final String username, final String pwd) {
    		return JDBC.get().openSession(new ISessionExecutor<User>() {
                public User execute(ISession session) throws Exception {
                    Cond _cond = Cond.create().eq("username").param(username).and().eq("pwd").param(pwd);
                    return session.findFirst(EntitySQL.create(User.class), Where.create(_cond));
                }
            });
    	}
  
    	@Transaction
    	public boolean doLogin(String username, String pwd) {
    		User _user = doGetUser(username, pwd);
    		if (_user != null) {
    			_user.setLastLoginTime(System.currentTimeMillis());
    			_user.update();
    			//
    			return true;
    		}
    		return false;
    	}
    }
  
    @Bean
    public class TransDemo {
  
    	@Inject
    	private IUserService __userService;
  
    	public boolean testTrans() {
    		return __userService.doLogin("suninformation", "123456");
    	}
  
    	public static void main(String[] args) throws Exception {
    		YMP.get().init();
    		try {
    			TransDemo _demo = YMP.get().getBean(TransDemo.class);
    			_demo.testTrans();
    		} finally {
    			YMP.get().destroy();
    		}
    	}
    }
  

会话（Session）

会话是对应用中具体业务操作触发的一系列与数据库之间的交互过程的封装，通过建立一个临时通道，负责与数据库之间连接资源的创建及回收，同时提供更为高级的抽象指令接口调用，基于会话的优点：

开发人员不需要担心连接资源是否正确释放；

严格的编码规范更利于维护和理解；

更好的业务封装性；

• 会话对象参数：

  • 数据库连接持有者（IConnectionHolder）：

    指定本次会话使用的数据源连接；

  • 会话执行器（ISessionExecutor）：

    以内部类的形式定义本次会话返回结果对象并提供Session实例对象的引用；

• 开启会话示例代码：

    // 使用默认数据源开启会话
    User _result = JDBC.get().openSession(new ISessionExecutor<User>() {
    	public User execute(ISession session) throws Exception {
    		// TODO 此处填写业务逻辑代码
    		return session.findFirst(EntitySQL.create(User.class));
    	}
    });
  
    // 使用指定的数据源开启会话
    IConnectionHolder _conn = JDBC.get().getConnectionHolder("oracledb");
    // 不需要关心_conn对象的资源释放
    IResultSet<User> _results = JDBC.get().openSession(_conn, new ISessionExecutor<IResultSet<User>>() {
    	public IResultSet<User> execute(ISession session) throws Exception {
    		// TODO 此处填写业务逻辑代码
    		return session.find(EntitySQL.create(User.class));
    	}
    });
  

• 基于ISession接口的数据库操作：

  示例代码是围绕用户(User)数据实体完成的CRUD(新增、查询、修改、删除)操作来展示如何使用ISession对象，数据实体如下：

    	@Entity("user")
    	public static class User extends BaseEntity<User, String> {
  
            @Id
            @Property
            private String id;
  
            @Property(name = "user_name")
            private String username;
  
            @Property(name = "pwd")
            private String pwd;
  
            @Property(name = "sex")
            private String sex;
  
            @Property(name = "age")
            private Integer age;
  
            // 忽略Getter和Setter方法
  
            public static class FIELDS {
                public static final String ID = "id";
                public static final String USER_NAME = "username";
                public static final String PWD = "pwd";
                public static final String SEX = "sex";
                public static final String AGE = "age";
            }
            public static final String TABLE_NAME = "user";
        }
  

  • 插入（Insert）：

      User _user = new User();
      _user.setId(UUIDUtils.UUID());
      _user.setUsername("suninformation");
      _user.setPwd(DigestUtils.md5Hex("123456"));
      _user.setAge(20);
      _user.setSex("F");
      // 执行数据插入
      session.insert(_user);
    
      // 或者在插入时也可以指定/排除某些字段
      session.insert(_user, Fields.create(User.FIELDS.SEX, User.FIELDS.AGE).excluded(true));
    

  • 更新（Update）：

      User _user = new User();
      _user.setId("bc19f5645aa9438089c5e9954e5f1ac5");
      _user.setPwd(DigestUtils.md5Hex("654321"));
      // 更新指定的字段
      session.update(_user, Fields.create(User.FIELDS.PWD));
    

  • 查询（Find）：

    • 方式一：通过数据实体设置条件（非空属性之间将使用and条件连接），查询所有符合条件的记录；

        User _user = new User();
        _user.setUsername("suninformation");
        _user.setPwd(DigestUtils.md5Hex("123456"));
        // 返回所有字段
        IResultSet<User> _users = session.find(_user);
        // 或者返回指定的字段
        _users = session.find(_user, Fields.create(User.FIELDS.ID, User.FIELDS.AGE));
      

    • 方式二：通过自定义条件，查询所有符合条件的记录；

        IResultSet<User> _users = session.find(
                EntitySQL.create(User.class)
                        .field(User.FIELDS.ID)
                        .field(User.FIELDS.SEX), 
                // 设置Order By条件
                Where.create()
                        .orderDesc(User.FIELDS.USER_NAME));
      

    • 方式三：分页查询；

        IResultSet<User> _users = session.find(
                EntitySQL.create(User.class)
                        .field(User.FIELDS.ID)
                        .field(User.FIELDS.SEX),
                Where.create()
                        .orderDesc(User.FIELDS.USER_NAME),
                // 查询第1页，每页10条记录，统计总记录数
                Page.create(1).pageSize(10).count(true));
      

    • 方式四：仅返回符合条件的第一条记录(FindFirst)；

        // 查询用户名称和密码都匹配的第一条记录
        User _user = session.findFirst(EntitySQL.create(User.class), 
                Where.create(
                        Cond.create()
                                .eq(User.FIELDS.USER_NAME).param("suninformation")
                                .and()
                                .eq(User.FIELDS.PWD).param(DigestUtils.md5Hex("123456"))));
      

    注：更多的查询方式将在后面的 “查询（Query）” 章节中详细阐述；

  • 删除（Delete）：

    • 根据实体主键删除记录：

        User _user = new User();
        _user.setId("bc19f5645aa9438089c5e9954e5f1ac5");
        //
        session.delete(_user);
      
        //
        session.delete(User.class, "bc19f5645aa9438089c5e9954e5f1ac5");
      

    • 根据条件删除记录：

        // 删除年龄小于20岁的用户记录
        session.executeForUpdate(
                SQL.create(
                        Delete.create(User.class).where(
                                Where.create(
                                        Cond.create()
                                                .lt(User.FIELDS.AGE).param(20)))));
      

  • 统计（Count）：

      	// 统计年龄小于20岁的用户记录总数
    
      	// 方式一：
      	long _count = session.count(User.class, 
                  Where.create(
                          Cond.create()
                                  .lt(User.FIELDS.AGE).param(20)));
    
      	// 方式二：
          _count = session.count(
                  SQL.create(
                          Delete.create(User.class).where(
                                  Where.create(
                                          Cond.create()
                                                  .lt(User.FIELDS.AGE).param(20)))));
    

  • 执行更新类操作（ExecuteForUpdate）：

    该方法用于执行ISession接口中并未提供对应的方法封装且执行操作会对数据库产生变化的SQL语句，执行该方法后将返回受影响记录行数，如上面执行的删除年龄小于20岁的用户记录：

      	int _effectCount =session.executeForUpdate(
                  SQL.create(
                          Delete.create(User.class).where(
                                  Where.create(
                                          Cond.create()
                                                  .lt(User.FIELDS.AGE).param(20)))));
    

  注：以上操作均支持批量操作，具体使用请阅读API接口文档和相关源码；

数据实体操作

上面阐述的是基于ISession会话对象完成一系列数据库操作，接下来介绍的操作过程更加简单直接，完全基于数据实体对象；

注意：本小节所指的数据实体对象必须通过继承框架提供BaseEntity抽象类；

插入（Insert）

User _user = new User();
_user.setId(UUIDUtils.UUID());
_user.setUsername("suninformation");
_user.setPwd(DigestUtils.md5Hex("123456"));
_user.setAge(20);
_user.setSex("F");
// 执行数据插入
_user.save();

// 或者在插入时也可以指定/排除某些字段
_user.save(Fields.create(User.FIELDS.SEX, User.FIELDS.AGE).excluded(true));

// 或者插入前判断记录是否已存在，若已存在则执行记录更新操作
_user.saveOrUpdate();

// 或者执行记录更新操作时仅更新指定的字段
_user.saveOrUpdate(Fields.create(User.FIELDS.SEX, User.FIELDS.AGE));

更新（Update）

User _user = new User();
_user.setId("bc19f5645aa9438089c5e9954e5f1ac5");
_user.setPwd(DigestUtils.md5Hex("654321"));
_user.setAge(20);
_user.setSex("F");
// 执行记录更新
_user.update();

// 或者仅更新指定的字段
_user.update(Fields.create(User.FIELDS.SEX, User.FIELDS.AGE));

查询（Find）

• 根据记录ID加载：

    User _user = new User();
    _user.setId("bc19f5645aa9438089c5e9954e5f1ac5");
    // 根据记录ID加载全部字段
    _user = _user.load();
  
    // 或者根据记录ID加载指定的字段
    _user = _user.load(Fields.create(User.FIELDS.USER_NAME, User.FIELDS.SEX, User.FIELDS.AGE));
  

• 通过数据实体设置条件（非空属性之间将使用and条件连接），查询所有符合条件的记录；

    User _user = new User();
    _user.setUsername("suninformation");
    _user.setPwd(DigestUtils.md5Hex("123456"));
    // 返回所有字段
    IResultSet<User> _users = _user.find();
  
    // 或者返回指定的字段
    _users = _user.find(Fields.create(User.FIELDS.ID, User.FIELDS.AGE));
  
    // 或者分页查询
    _users = _user.find(Page.create(1).pageSize(10));
  

• 分页查询：

    User _user = new User();
    _user.setSex("F");
  
    // 分页查询，返回全部字段
    IResultSet<User> _users = _user.find(Page.create(1).pageSize(10));
  
    // 或者分页查询，返回指定的字段
    _users = _user.find(Fields.create(User.FIELDS.ID, User.FIELDS.AGE), Page.create(1).pageSize(10));
  

• 仅返回符合条件的第一条记录(FindFirst)：

    User _user = new User();
    _user.setUsername("suninformation");
    _user.setPwd(DigestUtils.md5Hex("123456"));
  
    // 返回与用户名称和密码匹配的第一条记录
    _user = _user.findFirst();
  
    // 或者返回与用户名称和密码匹配的第一条记录的ID和AGE字段
    _user = _user.findFirst(Fields.create(User.FIELDS.ID, User.FIELDS.AGE));
  

删除（Delete）

User _user = new User();
_user.setId("bc19f5645aa9438089c5e9954e5f1ac5");

// 根据实体主键删除记录
_user.delete();

注：以上介绍的两种数据库操作方式各有特点，请根据实际情况选择更适合的方式，亦可混合使用；

结果集（ResultSet）

JDBC模块将数据查询的结果集合统一使用IResultSet接口进行封装并集成分页参数，下面通过一段代码介绍如何使用IResultSet对象：

IResultSet<User> _results = JDBC.get().openSession(new ISessionExecutor<IResultSet<User>>() {
    public IResultSet<User> execute(ISession session) throws Exception {
        return session.find(EntitySQL.create(User.class), Page.create(1).pageSize(10));
    }
});

// 返回当前是否分页查询
boolean _isPaginated = _results.isPaginated();

// 当前结果集是否可用，即是否为空或元素数量为0
boolean _isAvailable = _results.isResultsAvailable();

// 返回当前页号
int _pNumber = _results.getPageNumber();

// 返回每页记录数
int _pSize = _results.getPageSize();

// 返回总页数
int _pCount = _results.getPageCount();

// 返回总记录数
long _rCount = _results.getRecordCount();

// 返回结果集数据
List<User> _users = _results.getResultData();

注意：

• Page分页参数将影响总页数和总记录数的返回值是否为0；

当执行Page.create(1).pageSize(10).count(false)时，将不进行总记录数的count计算；

• 非分页查询时返回的分页参数值均为0；

查询（Query）

本节主要介绍YMP框架v2版本中新增的特性，辅助开发人员像写Java代码一样编写SQL语句，在一定程度上替代传统字符串拼接的模式，再配合数据实体的字段常量一起使用，这样做的好处就是降低字符串拼接过程中出错的机率，一些特定问题编译期间就能发现，因为Java代码就是SQL语句！

基础参数对象

• Fields：字段名称集合对象，用于辅助拼接数据表字段名称，支持前缀、别名等；

  示例代码：

    // 创建Fields对象
    Fields _fields = Fields.create("username", "pwd", "age");
    // 带前缀和别名
    _fields.add("u", "sex", "s");
    // 带前缀
    _fields = Fields.create().add("u", "id").add(_fields);
    // 标记集合中的字段为排除的
    _fields.excluded(true);
    // 判断是否存在排除标记
    _fields.isExcluded();
    // 输出
    System.out.println(_fields.fields());
  

  执行结果：

    [u.id, username, pwd, age, u.sex s]
  

• Params：参数集合对象，主要用于存储替换SQL语句中?号占位符；

  示例代码：

    // 创建Params对象，任何类型参数
    Params _params = Params.create("p1", 2, false, 0.1).add("param");
    // 
    _params = Params.create().add("paramN").add(_params);
    // 输出
    System.out.println(_params.params());
  

  执行结果：

    [paramN, p1, 2, false, 0.1, param]
  

• Pages：分页参数对象；

  示例代码：

    // 查询每1页, 默认每页20条记录
    Page.create(1);
    // 查询第1页, 每页10条记录
    Page.create(1).pageSize(10);
    // 查询第1页, 每页10条记录, 不统计总记录数
    Page.create(1).pageSize(10).count(false);
  

• Cond：条件参数对象，用于生成SQL条件和存储条件参数；

  示例代码：

  生成如下SQL条件：

  • (username like ? and age >= ?) or (sex = ? and age < ?)

    Cond _cond = Cond.create()
        .bracketBegin().like("username").param("%ymp%").and().gtEq("age").param(20).bracketEnd()
        .or()
        .bracketBegin().eq("sex").param("F").and().lt("age").param(18).bracketEnd();
  
    System.out.println("SQL: " + _cond.toString());
    System.out.println("参数: " + _cond.params().params());
  

  执行结果：

    SQL: ( username LIKE ? AND age >= ? )  OR  ( sex = ? AND age < ? ) 
    参数: [%ymp%, 20, F, 18]
  

• OrderBy：排序对象，用于生成SQL条件中的Order By语句；

  示例代码：

    OrderBy _orderBy = OrderBy.create().asc("age").desc("u", "birthday");
    //
    System.out.println(_orderBy.toSQL());
  

  执行结果：

    ORDER BY age, u.birthday DESC
  

• GroupBy：分组对象，用于生成SQL条件中的Group By语句；

  示例代码：

    GroupBy _groupBy = GroupBy.create(Fields.create().add("u", "sex").add("dept"))
        .having(Cond.create().lt("age").param(18));
  
    System.out.println("SQL: " + _groupBy.toString());
    System.out.println("参数: " + _groupBy.having().params().params());
  

  执行结果：

    SQL: GROUP BY u.sex, dept HAVING age < ?
    参数: [18]
  

• Where：Where语句对象，用于生成SQL语句中的Where子句；

  示例代码：

    Cond _cond = Cond.create()
            .like("username").param("%ymp%")
            .and().gtEq("age").param(20);
  
    OrderBy _orderBy = OrderBy.create().asc("age").desc("u", "birthday");
  
    GroupBy _groupBy = GroupBy.create(Fields.create().add("u", "sex").add("dept"));
  
    Where _where = Where.create(_cond).groupBy(_groupBy).orderDesc("username");
  
    _where.orderBy().orderBy(_orderBy);
    //
    System.out.println("SQL: " + _where.toString());
    System.out.println("参数: " + _where.getParams().params());
  

  执行结果：（为方便阅读，此处美化了SQL的输出格式:P）

    SQL: WHERE
    		 username LIKE ?
    	 AND age >= ?
    	 GROUP BY
    		 u.sex,
    		 dept
    	 ORDER BY
    		 username DESC,
    		 age,
    		 u.birthday DESC
    参数: [%ymp%, 20]
  

• Join：连接语句对象，用于生成SQL语句中的Join子句，支持left、right和inner连接；

  示例代码：

    Join _join = Join.inner("user_ext").alias("ue")
        .on(Cond.create().opt("ue", "uid", Cond.OPT.EQ, "u", "id"));
  
    System.out.println(_join);
  

  执行结果：

    INNER JOIN user_ext ue ON ue.uid = u.id
  

• Union：联合语句对象，用于将多个Select查询结果合并；

  示例代码：

    Select _select = Select.create("user").where(Where.create(Cond.create().eq("dept").param("IT")))
            .union(Union.create(
                    Select.create("user").where(Where.create(Cond.create().lt("age").param(18)))));
    //
    System.out.println("SQL: " + _select.toString());
    System.out.println("参数: " + _select.getParams().params());
  

  执行结果：

    SQL: SELECT  *  FROM user WHERE dept = ?  UNION SELECT  *  FROM user WHERE age < ?   
    参数: [IT, 18]
  

Select：查询语句对象

示例代码：

	Cond _cond = Cond.create()
            .like("u", "username").param("%ymp%")
            .and().gtEq("u", "age").param(20);
    //
    GroupBy _groupBy = GroupBy.create(Fields.create().add("u", "sex").add("u", "dept"));
    //
    Where _where = Where.create(_cond).groupBy(_groupBy).orderDesc("u", "username");
    //
    Join _join = Join.inner("user_ext").alias("ue")
            .on(Cond.create().opt("ue", "uid", Cond.OPT.EQ, "u", "id"));
	//
    Select _select = Select.create(User.class, "u")
            .field("u", "username").field("ue", "money")
            .where(_where)
            .join(_join)
            .distinct();
    //
    System.out.println("SQL: " + _select.toString());
    System.out.println("参数: " + _select.getParams().params());

执行结果：（为方便阅读，此处美化了SQL的输出格式:P）

	SQL: SELECT DISTINCT
				u.username,
				ue.money
			FROM
				USER u
			INNER JOIN user_ext ue ON ue.uid = u.id
			WHERE
				u.username LIKE ?
			AND u.age >= ?
			GROUP BY
				u.sex,
				u.dept
			ORDER BY
				u.username DESC 
	参数: [%ymp%, 20]

Insert：插入语句对象

示例代码：

	Insert _insert = Insert.create(User.class)
            .field(User.FIELDS.ID).param("123456")
            .field(User.FIELDS.AGE).param(18)
            .field(User.FIELDS.USER_NAME).param("suninformation");
    //
    System.out.println("SQL: " + _insert.toString());
    System.out.println("参数: " + _insert.params().params());

执行结果：

	SQL: INSERT INTO user (id, age, username) VALUES (?, ?, ?)
	参数: [123456, 18, suninformation]

Update：更新语句对象

示例代码：

	Update _update = Update.create(User.class)
            .field(User.FIELDS.PWD).param("xxxx")
            .field(User.FIELDS.AGE).param(20)
            .where(Where.create(
                    Cond.create().eq(User.FIELDS.ID).param("123456")));
    //
    System.out.println("SQL: " + _update.toString());
    System.out.println("参数: " + _update.getParams().params());

执行结果：

	SQL: UPDATE user SET pwd = ?, age = ? WHERE id = ? 
	参数: [xxxx, 20, 123456]

Delete：删除语句对象

示例代码：

	Delete _delete = Delete.create(User.class)
            .where(Where.create(
                    Cond.create().eq(User.FIELDS.ID).param("123456")));
    //
    System.out.println("SQL: " + _delete.toString());
    System.out.println("参数: " + _delete.getParams().params());

执行结果：

	SQL: DELETE  FROM user WHERE id = ? 
	参数: [123456]

SQL：自定义SQL语句

同时也用于ISession会话接口参数封装；

示例代码：

// 自定义SQL语句
SQL _sql = SQL.create("select * from user where age > ? and username like ?").param(18).param("%ymp%");
// 执行
session.find(_sql, IResultSetHandler.ARRAY);

// 或封装语句对象
SQL.create(_select);
SQL.create(_insert);
SQL.create(_update);
SQL.create(_delete);

BatchSQL：批量SQL语句对象

主要用于ISession会话对批量操作的参数封装；

示例代码：

// 定义批操作
BatchSQL _sqls = BatchSQL.create("INSERT INTO user (id, age, username) VALUES (?, ?, ?)")
        .addParameter(Params.create("xxxx", 18, "user0"))
        .addParameter(Params.create("xxx1", 20, "user1"))
        .addParameter(Params.create("xxxN", 20, "userN"))
        .addSQL("DELETE  FROM user WHERE age > 30")
        .addSQL("DELETE  FROM user WHERE age < 18");
// 执行
session.executeForUpdate(_sqls);

EntitySQL：实体参数封装对象

主要用于ISession会话的参数封装；

示例代码：

session.find(EntitySQL.create(User.class)
            .field(Fields.create(User.FIELDS.ID, User.FIELDS.USER_NAME)
                    .excluded(true)));

存储器（Repository）

为了能够更方便的维护和执行SQL语句，JDBC模块提供了存储器的支持，可以通过@Repository注解自定义SQL或自定义SQL语句或从配置文件中加载SQL并自动执行。

• @Repository注解：

  • 参数说明：

    dsName：数据源名称，默认为空则采用默认数据源；

    item：从资源文件中加载item指定的配置项，默认为空；

    value：自定义SQL配置(value的优先级高于item)；

    type：操作类型，默认为查询，可选值：Type.OPT.QUERY或Type.OPT.UPDATE

    useFilter：是否调用方法过滤, 默认为true

    dbType：指定当前存储器适用的数据库类型，默认为全部，否则将根据数据库类型进行存储器加载

• 存储器示例代码：

  • 存储器：

      @Repository
      public class DemoRepository implements IRepository {
    
          /**
           * 注入SQL配置文件(任意配置对象均可)
           */
          @Inject
          private DefaultRepoConfig _repoCfg;
    
          /**
           * 返回SQL配置文件对象, 若不需要配置文件请不要实现IRepository接口
           */
          public IConfiguration getConfig() {
              return _repoCfg;
          }
    
          /**
           * 自定义SQL
           */
          @Repository("select * from ymcms_attachment where hash = ${hash}")
          public IResultSet<Object[]> getSQLResults(String hash, IResultSet<Object[]> results) throws Exception {
              return results;
          }
    
          /**
           * 读取配置文件中的SQL
           */
          @Repository(item = "demo_query")
          public List<Attachment> getAttachments(String hash, IResultSet<Object[]>... results) throws Exception {
              final List<Attachment> _returnValues = new ArrayList<Attachment>();
              if (results != null && results.length > 0) {
                  ResultSetHelper _help = ResultSetHelper.bind(results[0]);
                  if (_help != null)
                      _help.forEach(new ResultSetHelper.ItemHandler() {
                          @Override
                          public boolean handle(ResultSetHelper.ItemWrapper wrapper, int row) throws Exception {
                              _returnValues.add(wrapper.toEntity(new Attachment()));
                              return true;
                          }
                      });
              }
              return _returnValues;
          }
      }
    

  • SQL配置文件对象：

      @Configuration("cfgs/default.repo.xml")
      public class DefaultRepoConfig extends DefaultConfiguration {
      }
    

  • SQL配置文件default.repo.xml内容：

      <?xml version="1.0" encoding="UTF-8"?>
      <properties>
          <category name="default">
              <property name="demo_query">
                  <value><![CDATA[select * from ymcms_attachment where hash = ${hash}]]></value>
              </property>
              <!-- 动态SQL也支持通过JavaScript脚本处理, 如下所示: -->
              <!--
              <property name="demo_query" language="javascript">
                  <value><![CDATA[
                      // 方法名称要与name属性名称一致
                      function demo_query(hash) {
                          var _sql = "select * from ymcms_attachment";
                          if (hash && hash != "admin") {
                              _sql += " where hash = ${hash}";
                          }
                          // 方式一：直接返回拼装后的SQL字符串
                          return _sql;
                          // 方式二：添加回调方法用于过滤查询结果集
                          /*
                          return {
                              "sql": function() { return _sql },
                              "filter": function(results) {
                                  var List = Java.type("java.util.ArrayList");
                                  var _list = new List();
                                  if (results && results.isResultsAvailable) {
                                      for (i=0; i< results.resultData.length; i++) {
                                          if (i % 2 == 0) {
                                              _list.add(results.resultData.get(i))
                                          }
                                      }
                                  }
                                  // 注意：返回的结果类型需与Java接口方法参数类型匹配
                                  return _list;
                              }
                          } */
                      }
                  ]]></value>
              </property>
              -->
          </category>
      </properties>
    

  • 在控制器中调用：在浏览器中访问http://localhost:8080/hello查看执行结果

      @Controller
      @RequestMapping("/hello")
      public class HelloController {
    
          /**
           * 注入存储器
           */
          @Inject
          private DemoRepository _repo;
    
          @RequestMapping("/")
          public IView hello() throws Exception {
              // 调用存储器方法
              return View.jsonView(_repo.getAttachments("44f5b005c7a94a0d42f53946f16b6bb2"));
          }
      }
    

• 说明：

  • 存储器类通过声明@Repository注解被框架自动扫描并加载；
  • 与其它被容器管理的@Bean一样支持拦截器、事务、缓存等注解；
  • 当useFilter=true时，存储器类方法的参数至少有一个参数(方法有多个参数时，采用最后一个参数)用于接收SQL执行结果；
  • 查询类型SQL的执行结果数据类型为IResultSet<Object[]>，更新类型SQL的执行结果数据类型为int；
  • 用于接收SQL执行结果的方法参数支持变长类型，如：IResultSet<Object[]> results和IResultSet<Object[]>... results是一样的；
  • 读取配置文件中的SQL配置时，配置项名称必须全部采用小写字符，如：demo_query；
  • 框架将优先加载以当前数据源连接的数据库类型名称作为后缀的配置项，如：demo_query_mysql、demo_query_oracle，若找不到则加载默认名称，即demo_query；

高级特性

多表查询及自定义结果集数据处理

JDBC模块提供的ORM主要是针对单实体操作，实际业务中往往会涉及到多表关联查询以及返回多个表字段，在单实体ORM中是无法将JDBC结果集记录自动转换为实体对象的，这时就需要对结果集数据自定义处理来满足业务需求。

若想实现结果集数据的自定义处理，需要了解以下相关接口和类：

• IResultSetHandler接口：结果集数据处理接口，用于完成将JDBC结果集原始数据的每一行记录进行转换为目标对象，JDBC模块默认提供了该接口的三种实现：

  EntityResultSetHandler：采用实体类存储结果集数据的接口实现，此类已经集成在ISession会话接口业务逻辑中，仅用于处理单实体的数据转换；

  BeanResultSetHandler：将数据直接映射到类成员属性的结果集处理接口实现；

  MapResultSetHandler：采用Map存储结果集数据的接口实现；

  ArrayResultSetHandler：采用Object[]数组存储结果集数据的接口实现；

• ResultSetHelper类：数据结果集辅助处理工具，用于帮助开发人员便捷的读取和遍历结果集中数据内容，仅支持由 ArrayResultSetHandler 和 MapResultSetHandler 产生的结果集数据类型；

下面通过简单的多表关联查询来介绍IResultSetHandler接口和ResultSetHelper类如何配合使用：

示例代码一：使用ArrayResultSetHandler或MapResultSetHandler处理结果集数据；

	IResultSet<Object[]> _results = JDBC.get().openSession(new ISessionExecutor<IResultSet<Object[]>>() {
        public IResultSet<Object[]> execute(ISession session) throws Exception {
            // 通过查询对象创建SQL语句:
            //
            // SELECT u.id id, u.username username, ue.money money 
            // 			FROM user u LEFT JOIN user_ext ue ON u.id = ue.uid
            //
            Select _uSelect = Select.create(User.class, "u")
                    .join(Join.left(UserExt.TABLE_NAME).alias("ue")
                            .on(Cond.create()
                                    .opt("u", User.FIELDS.ID, Cond.OPT.EQ, "ue", UserExt.FIELDS.UID)))
                    .field(Fields.create()
                            .add("u", User.FIELDS.ID, "id")
                            .add("u", User.FIELDS.USER_NAME, "username")
                            .add("ue", UserExt.FIELDS.MONEY, "money"));

            // 执行查询并指定采用Object[]数组存储结果集数据，若采用Map存储请使用：IResultSetHandler.MAP
            return session.find(SQL.create(_uSelect), IResultSetHandler.ARRAY);
        }
    });

    // 采用默认步长(step=1)逐行遍历
    ResultSetHelper.bind(_results).forEach(new ResultSetHelper.ItemHandler() {
        public boolean handle(ResultSetHelper.ItemWrapper wrapper, int row) throws Exception {
            System.out.println("当前记录行数: " + row);

            // 通过返回的结果集字段名取值
            String _id = wrapper.getAsString("id");
            String _uname = wrapper.getAsString("username");

            // 也可以通过索引下标取值
            Double _money = wrapper.getAsDouble(2);

            // 也可以直接将当前行数据赋值给实体对象或自定义JavaBean对象
            wrapper.toEntity(new User());

            // 当赋值给自定义的JavaBean对象时需要注意返回的字段名称与对象成员属性名称要一一对应并且要符合命名规范
            // 例如：对象成员名称为"userName"，将与名称为"user_name"的字段对应
            wrapper.toObject(new User());

            // 返回值将决定遍历是否继续执行
            return true;
        }
    });

    // 采用指定的步长进行数据遍历，此处step=2
    ResultSetHelper.bind(_results).forEach(2, new ResultSetHelper.ItemHandler() {
        public boolean handle(ResultSetHelper.ItemWrapper wrapper, int row) throws Exception {
            // 代码略......
            return true;
        }
    });

示例代码二：使用自定义IResultSetHandler处理结果集数据；

	// 自定义JavaBean对象，用于封装多表关联的结果集的记录
	public class CustomUser {

		private String id;

		private String username;

		private Double money;

		// 忽略Getter和Setter方法
	}

	// 修改示例一的代码，将结果集中的每一条记录转换成自定义的CustomUser对象
	IResultSet<CustomUser> _results = JDBC.get().openSession(new ISessionExecutor<IResultSet<CustomUser>>() {
        public IResultSet<CustomUser> execute(ISession session) throws Exception {
            Select _uSelect = Select.create(User.class, "u")
                    .join(Join.left(UserExt.TABLE_NAME).alias("ue")
                            .on(Cond.create()
                                    .opt("u", User.FIELDS.ID, Cond.OPT.EQ, "ue", UserExt.FIELDS.UID)))
                    .field(Fields.create()
                            .add("u", User.FIELDS.ID, "id")
                            .add("u", User.FIELDS.USER_NAME, "username")
                            .add("ue", UserExt.FIELDS.MONEY, "money"));

            // 通过实现IResultSetHandler接口实现结果集的自定义处理
            return session.find(SQL.create(_uSelect), new IResultSetHandler<CustomUser>() {
                public List<CustomUser> handle(ResultSet resultSet) throws Exception {
                    List<CustomUser> _results = new ArrayList<CustomUser>();
                    while (resultSet.next()) {
                        CustomUser _cUser = new CustomUser();
                        _cUser.setId(resultSet.getString("id"));
                        _cUser.setUsername(resultSet.getString("username"));
                        _cUser.setMoney(resultSet.getDouble("money"));
                        //
                        _results.add(_cUser);
                    }
                    return _results;
                }
            });
        }
    });

存储过程调用与结果集数据处理

针对于存储过程，JDBC模块提供了IProcedureOperator操作器接口及其默认接口实现类DefaultProcedureOperator来帮助你完成，存储过程有以下几种调用方式，举例说明：

• 有输入参数无输出参数：

    IConnectionHolder _conn = JDBC.get().getDefaultConnectionHolder();
    try {
        // 执行名称为`procedure_name`的存储过程，并向该存储过程转入两个字符串参数
        IProcedureOperator<Object[]> _opt = new DefaultProcedureOperator<Object[]>("procedure_name", _conn)
                .addParameter("param1")
                .addParameter("param2")
                .execute(IResultSetHandler.ARRAY);
        // 遍历结果集集合
        for (List<Object[]> _item : _opt.getResultSets()) {
            ResultSetHelper.bind(_item).forEach(new ResultSetHelper.ItemHandler() {
                public boolean handle(ResultSetHelper.ItemWrapper wrapper, int row) throws Exception {
                    System.out.println(wrapper.toObject(new ArchiveVObject()).toJSON());
                    return true;
                }
            });
        }
    } finally {
        _conn.release();
    }
  

• 有输入输出参数：

    IConnectionHolder _conn = JDBC.get().getDefaultConnectionHolder();
    try {
        // 通过addOutParameter方法按存储过程输出参数顺序指定JDBC参数类型
        new DefaultProcedureOperator("procedure_name", _conn)
                .addParameter("param1")
                .addParameter("param2")
                .addOutParameter(Types.VARCHAR)
                .execute(new IProcedureOperator.IOutResultProcessor() {
                    public void process(int idx, int paramType, Object result) throws Exception {
                        System.out.println(result);
                    }
                });
    } finally {
        _conn.release();
    }
  

• 另一种写法：

    JDBC.get().openSession(new ISessionExecutor<List<List<Object[]>>>() {
        public List<List<Object[]>> execute(ISession session) throws Exception {
            // 创建存储过程操作器对象
            IProcedureOperator<Object[]> _opt = new DefaultProcedureOperator<Object[]>("procedure_name", session.getConnectionHolder())
                    .addParameter("param1")
                    .addParameter("param2")
                    .addOutParameter(Types.VARCHAR)
                    .addOutParameter(Types.INTEGER)
                    .setOutResultProcessor(new IProcedureOperator.IOutResultProcessor() {
                        public void process(int idx, int paramType, Object result) throws Exception {
                            System.out.println(result);
                        }
                    }).setResultSetHandler(IResultSetHandler.ARRAY);
            // 执行
            _opt.execute();
            return _opt.getResultSets();
        }
    });
  

数据库锁操作

数据库是一个多用户使用的共享资源，当多个用户并发地存取数据时，在数据库中就会产生多个事务同时存取同一数据的情况，若对并发操作不加以控制就可能会造成数据的错误读取和存储，破坏数据库的数据一致性，所以说，加锁是实现数据库并发控制的一个非常重要的技术；

数据库加锁的流程是：当事务在对某个数据对象进行操作前，先向系统发出请求对其加锁，加锁后的事务就对该数据对象有了一定的控制，在该事务释放锁之前，其他的事务不能对此数据对象进行更新操作；

因此，JDBC模块在数据库查询操作中集成了针对数据库记录锁的控制能力，称之为IDBLocker，以参数的方式使用起来同样的简单！

首先了解一下IDBLocker提供的锁的类型：

• MySQL：

  IDBLocker.DEFAULT：行级锁，只有符合条件的数据被加锁，其它进程等待资源解锁后再进行操作；

• Oracle：

  IDBLocker.DEFAULT：行级锁，只有符合条件的数据被加锁，其它进程等待资源解锁后再进行操作；

  IDBLocker.ORACLE_NOWAIT：行级锁，不进行资源等待，只要发现结果集中有些数据被加锁，立刻返回“ORA-00054错误”；

• SQL Server：

  IDBLocker.SQLSERVER_NOLOCK：不加锁，在读取或修改数据时不加任何锁；

  IDBLocker.SQLSERVER_HOLDLOCK：保持锁，将此共享锁保持至整个事务结束，而不会在途中释放；

  IDBLocker.SQLSERVER_UPDLOCK：修改锁，能够保证多个进程能同时读取数据但只有该进程能修改数据；

  IDBLocker.SQLSERVER_TABLOCK：表锁，整个表设置共享锁直至该命令结束，保证其他进程只能读取而不能修改数据；

  IDBLocker.SQLSERVER_PAGLOCK：页锁；

  IDBLocker.SQLSERVER_TABLOCKX：排它表锁，将在整个表设置排它锁，能够防止其他进程读取或修改表中的数据；

• 其它数据库：

  可以通过IDBLocker接口自行实现；

下面通过示例代码展示如何使用锁：

示例代码一：通过EntitySQL对象传递锁参数；

session.find(EntitySQL.create(User.class)
        .field(Fields.create(User.FIELDS.ID, User.FIELDS.USER_NAME).excluded(true))
        .forUpdate(IDBLocker.DEFAULT));

示例代码二：通过Select查询对象传递锁参数；

Select _select = Select.create(User.class, "u")
        .field("u", "username").field("ue", "money")
        .where(Where.create(
                Cond.create().eq(User.FIELDS.ID).param("bc19f5645aa9438089c5e9954e5f1ac5")))
        .forUpdate(IDBLocker.DEFAULT);

session.find(SQL.create(_select), IResultSetHandler.ARRAY);

示例代码三：基于数据实体对象传递锁参数

//
User _user = new User();
_user.setId("bc19f5645aa9438089c5e9954e5f1ac5");
//
_user.load(IDBLocker.DEFAULT);

//
User _user = new User();
_user.setUsername("suninformation");
_user.setPwd(DigestUtils.md5Hex("123456"));
//
IResultSet<User> _users = _user.find(IDBLocker.DEFAULT);

注意：

请谨慎使用数据库锁机制，尽量避免产生锁表，以免发生死锁情况！

插件（Plugin）

插件模块采用独立的ClassLoader类加载器来管理私有JAR包、类、资源文件等，设计目标是在接口开发模式下，将需求进行更细颗粒度拆分，从而达到一个理想化可重用代码的封装形态；

每个插件都是封闭的世界，插件与外界之间沟通的唯一方法是通过业务接口调用，管理这些插件的容器被称之为插件工厂(IPluginFactory)，负责插件的分析、加载和初始化，以及插件的生命周期管理，插件模块支持创建多个插件工厂实例，工厂对象之间完全独立，无任何依赖关系；

Maven包依赖

<dependency>
    <groupId>net.ymate.platform</groupId>
    <artifactId>ymate-platform-plugin</artifactId>
    <version><VERSION></version>
</dependency>

注：在项目的pom.xml中添加上述配置，该模块已经默认引入核心包依赖，无需重复配置。

插件工厂

插件工厂分为两种，一种是以模块的形式封装，由YMP框架初始化时根据配置参数自动构建，称之为默认插件工厂(有且仅能存在一个默认工厂实例)，另一种是通过代码手动配置构建的自定义插件工厂，不同之处在于默认插件工厂与框架结合得更紧密，两种模式可以并存；

默认插件工厂

默认插件工厂是在插件模块被YMP框架初始化时自动创建的，其初始化参数及说明如下：

#-------------------------------------
# Plugin插件模块初始化参数
#-------------------------------------

# 插件主目录路径，可选参数，默认值为${root}/plugins
ymp.configs.plugin.plugin_home=

# 自动扫描包路径集合，多个包名之间用'|'分隔，默认与框架自动扫描的包路径相同
ymp.configs.plugin.autoscan_packages=

# 插件是否自动启动，默认为true
ymp.configs.plugin.automatic=

# 是否加载当前CLASSPATH内的所有包含插件配置文件的JAR包，默认为true
ymp.configs.plugin.included_classpath=

禁用默认插件工厂的方法：

# 在YMP框架配置文件中找到"模块排除列表"项，添加插件模块的名称，如：
ymp.excluded_modules=plugin

调用默认插件工厂的方法：

Plugins.get().getPluginFactory();

默认插件工厂的事件监听方法：

默认插件工厂是通过YMP框架的事件服务订阅进行处理，PluginEvent插件事件对象包括以下事件类型：

事务类型	说明
PLUGIN_INITED	插件初始化事件
PLUGIN_STARTED	插件启动事件
PLUGIN_SHUTDOWN	插件停止事件
PLUGIN_DESTROYED	插件销毁事件

自定义插件工厂

自定义插件工厂有两种方式：

• 通过@PluginFactory注解配置插件工厂，注解参数说明如下：

  |参数|说明| |---|---| |pluginHome|插件存放路径，必需提供；| |autoscanPackages|自动扫描路径，默认为插件工厂所在包路径；| |automatic|插件是否自动启动，默认为true；| |includedClassPath|是否加载当前CLASSPATH内的所有包含插件配置文件的JAR包，默认为false；| |listenerClass|插件生命周期事件监听器类对象, 可选配置；|

  示例代码：

        @PluginFactory(pluginHome = "${root}/plugins")
        public class DemoPluginFactory extends DefaultPluginFactory {
        }
  
        // 或者
  
        @PluginFactory(pluginHome = "${root}/plugins",
                autoscanPackages = {"com.company", "cn.company"},
                automatic = true,
                includedClassPath = false,
                listenerClass = DemoPluginEventListener.class)
        public class DemoPluginFactory extends DefaultPluginFactory {
        }
  

• 通过工厂配置对象实例化

  创建工厂配置对象：

        DefaultPluginConfig _conf = new DefaultPluginConfig();
        _conf.setPluginHome(new File(RuntimeUtils.replaceEnvVariable("${root}/plugins")));
        _conf.setAutomatic(true);
        _conf.setAutoscanPackages(Arrays.asList("com.company", "cn.company"));
        _conf.setIncludedClassPath(false);
        _conf.setPluginEventListener(new DefaultPluginEventListener());
  

  创建并初始化插件工厂实例对象：

        IPluginFactory _factory = new DefaultPluginFactory();
        _factory.init(_conf);
  

  自定义插件工厂的事件监听方法：

  自定义插件工厂的事件处理方式与默认插件工厂不同，须通过实现IPluginEventListener接口完成插件生命周期事件监听，IPluginEventListener接口事件方法及说明如下：

  |事件|说明| |---|---| |onInited|插件初始化事件；| |onStarted|插件启动事件；| |onShutdown|插件停止事件；| |onDestroy|插件销毁事件；|

  示例代码：

    public class DemoPluginEventListener implements IPluginEventListener {
  
        public void onInited(IPluginContext context, IPlugin plugin) {
            System.out.println("onInited: " + context.getPluginMeta().getName());
        }
  
        public void onStarted(IPluginContext context, IPlugin plugin) {
            System.out.println("onStarted: " + context.getPluginMeta().getName());
        }
  
        public void onShutdown(IPluginContext context, IPlugin plugin) {
            System.out.println("onShutdown: " + context.getPluginMeta().getName());
        }
  
        public void onDestroy(IPluginContext context, IPlugin plugin) {
            System.out.println("onDestroy: " + context.getPluginMeta().getName());
        }
    }
  

插件结构

插件有两种形式，一种是将插件以JAR包文件形式存储，这类插件可以直接与工程类路径下其它依赖包一起使用，另一种是将插件类文件及插件依赖包等资源放在插件目录结构下，这类插件可以放在工程路径以外，可以多模块共用插件，其目录结构如下：

<PLUGIN_HOME>\
    |--.plugin\
    |   |--lib\
    |   |   |--xxxx.jar
    |   |   |--...
    |   |--classes\
    |   |   |--...
    |   |--...
    |--<plugin_xxx>\
    |   |--lib\
    |   |   |--xxxx.jar
    |   |   |--...
    |   |--classes\
    |   |   |--...
    |   |--...
    |--<plugin_xxxx>\
    |--...

插件目录结构说明：

• 每一个插件工厂所指定的PLUGIN_HOME根路径下都可以通过一个名称为".plugin"的目录将一些JAR包或类等资源文件进行全局共享；

• 每一个插件都是一个独立的目录，一般以插件ID命名(不限于)，并将插件相关的JAR包和类文件等资源分别放置在对应的lib、classes或其它目录下；

插件

通过在一个实现了IPlugin接口的类上声明@Plugin注解来创建插件启动类，其将被插件工厂加载和管理，一个插件包可以包括多个插件启动类，每个插件启动类可以实现自己的业务接口对外提供服务；

• @Plugin注解参数说明：

  id：插件唯一ID，若未填写则使用初始化类名称进行MD5加密后的值做为ID；

  name：插件名称，默认为"";

  alias：插件别名，默认为"";

  author：插件作者，默认为"";

  email：联系邮箱，默认为"";

  version：插件版本，默认为"1.0.0";

  automatic：是否加载后自动启动运行，默认true;

  description：插件描述，默认为"";

• IPlugin接口方法说明：

  init：插件初始化；

  getPluginContext：返回插件环境上下文对象；

  isInited：返回插件是否已初始化；

  isStarted：返回插件是否已启动；

  startup：启动插件；

  shutdown：停止插件；

  destroy：销毁插件对象；

插件框架提供了一个封装了IPlugin接口的AbstractPlugin抽象类，建议直接继承，示例代码：

@Plugin
public class DemoPlugin extends AbstractPlugin {
    // 根据需要重写父类方法...
}

结合业务接口的插件示例：

// 定义一个业务接口
public interface IBusiness {
    void sayHi();
}

@Plugin(id = "demo_plugin",
        name = "DemoPlugin",
        author = "有理想的鱼",
        email = "suninformaiton#163.com",
        version = "1.0")
public class DemoPlugin extends AbstractPlugin implements IBusiness {

    @Override
    public void startup() throws Exception {
        super.startup();
        //
        System.out.println("started.");
    }

    @Override
    public void shutdown() throws Exception {
        super.shutdown();
        //
        System.out.println("shutdown.");
    }

    public void sayHi() {
        System.out.println("Hi, from Plugin.");
    }
}

插件的使用

上面我们已经创建了一个DemoPlugin插件并且实现了IBusiness业务接口，下面介绍如何使用插件和调用业务接口方法：

public static void main(String[] args) throws Exception {
    YMP.get().init();
    try {
        DemoPlugin _plugin = (DemoPlugin) Plugins.get().getPluginFactory().getPlugin("demo_plugin");
        // 或者 
        // _plugin = Plugins.get().getPluginFactory().getPlugin(DemoPlugin.class);
        //
        _plugin.sayHi();
        //
        IBusiness _business = Plugins.get().getPluginFactory().getPlugin(IBusiness.class);
        _business.sayHi();
    } finally {
        YMP.get().destroy();
    }
}

执行结果：

Hi, from Plugin.
Hi, from Plugin.
shutdown.

通过依赖注入引用插件

通过@PluginRefer注解指定注入插件实例，注解参数说明如下：

参数	说明
value	插件唯一ID，若不指定则默认根据成员对象类型查找插件

示例代码：

@Bean
public class App {

  @PluginRefer
  private IBusiness _business;

  public IBusiness getBusiness() {
      return _business;
  }

  public static void main(String[] args) throws Exception {
      try {
          YMP.get().init();
          //
          App _app = YMP.get().getBean(App.class);
          IBusiness _biz = _app.getBusiness();
          _biz.sayHi();
      } finally {
          YMP.get().destroy();
      }
  }
}

注：同一个插件可以实现多个业务接口，若多个插件实现同一个业务接口，根据插件加载顺序，最后加载的插件实例对象将替换前者；

服务（Serv）

服务模块（Serv）是一套基于NIO实现的通讯服务框架，提供TCP、UDP协议的客户端与服务端封装，灵活的消息监听与消息内容编/解码，简约的配置使二次开发更加便捷； 同时默认提供断线重连、链路维护(心跳)等服务支持，您只需了解业务即可轻松完成开发工作。

Maven包依赖

<dependency>
    <groupId>net.ymate.platform</groupId>
    <artifactId>ymate-platform-serv</artifactId>
    <version><VERSION></version>
</dependency>

注：在项目的pom.xml中添加上述配置，该模块已经默认引入核心包依赖，无需重复配置。

基础概念

会话（Session）

用于客户端与服务端之间连接状态的维护和消息发送的对象；

编/解码器（Codec）

目前提供以下两种编/解码器，开发者可通过实现ICodec接口自行扩展；

• NioStringCodec：采用字节byte[4]作为消息头，用于记录消息体长度的字符串消息编/解码器；

• TextLineCodec：用于解析以回车换行符(\r\n)做为消息结束标志的字符串消息的编/解码器；

内置服务（Service）

目前提供以下两种内置服务，更多服务在不断完善中...；

• IHeartbeatService：内置链路维护(心跳)服务，该服务将在与服务端成功建立连接后按参数配置的时间间隔向服务端发送心跳消息（心跳消息内容默认为0字符，心跳消息内容可以通过自定义参数heartbeat_message设置）；

• IReconnectService：内置断线重连服务，当服务的连接状态异常时将尝试重新与服务端建立连接；

服务端（Server）

服务端初始化参数：

#-------------------------------------
# 服务模块--服务端初始化参数
#-------------------------------------

# 服务端配置列表，多个服务端名称间用'|'分隔，默认为default
ymp.configs.serv.server.name_list=default

# 服务名称, 默认为default
ymp.configs.serv.server.default.name=default

# 绑定IP地址, 默认为0.0.0.0
ymp.configs.serv.server.default.host=0.0.0.0

# 监听端口号, 默认为8281
ymp.configs.serv.server.default.port=8281

# 编解码字符集, 默认为UTF-8
ymp.configs.serv.server.default.charset=UTF-8

# 缓冲区大小, 默认为4096
ymp.configs.serv.server.default.buffer_size=4096

# NIO选择器数量, 默认为1
ymp.configs.serv.server.default.selector_count=1

# 执行线程池大小, 默认为 Runtime.getRuntime().availableProcessors()
ymp.configs.serv.server.default.executor_count=10

# 空闲线程等待新任务的最长时间, 默认为 0
ymp.configs.serv.server.default.keep_alive_time=0

# 最大线程池大小，默认为 200
ymp.configs.serv.server.default.thread_max_pool_size=200

# 线程队列大小，默认为 1024
ymp.configs.serv.server.default.thread_queue_size=1024

# 自定义参数, 可选
ymp.configs.serv.server.default.params.xxx=xxx

通过在监听器实现类声明@Server注解来表示一个服务端，该注解有如下参数：

参数	说明
name	设置服务的名称，Serv框架将会根据该参数指定的名称加载对应的服务端参数配置，默认为default；
codec	设置编解码器，默认为NioStringCodec；
implClass	服务端实现类，默认为NioServer；

基于TCP协议的服务端，需要继承NioServerListener监听器类，支持监听如下事件：

事件	说明
onSessionAccepted	客户端成功接入服务端后触发该事件；
onBeforeSessionClosed	客户端会话被关闭之前触发该事件；
onAfterSessionClosed	客户端会话被关闭之后触发该事件；
onMessageReceived	收到客户端发送的消息时触发该事件；
onExceptionCaught	出现异常时触发该事件；

基于UDP协议的服务端，需要继承NioUdpListener监听器类，支持监听如下事件：

事件	说明
onSessionReady	客户端与服务端连接已建立并准备就绪时触发该事件；
onMessageReceived	收到客户端发送的消息时触发该事件；
onExceptionCaught	出现异常时触发该事件；

示例代码

TCP服务端

// 采用默认配置的TCP服务端
@Server
public class TcpServer extends NioServerListener {
	@Override
	public void onSessionAccepted(INioSession session) throws IOException {
	    super.onSessionAccepted(session);
	}
	
	@Override
	public void onMessageReceived(Object message, INioSession session) throws IOException {
	    super.onMessageReceived(message, session);
	    // 输出接收到的消息
	    System.out.println("Message received: " + message);
	    // 向客户端发送消息
	    session.send("Hi, guys!");
	}
	
	@Override
	public void onAfterSessionClosed(INioSession session) throws IOException {
	    super.onAfterSessionClosed(session);
	}
	
	@Override
	public void onBeforeSessionClosed(INioSession session) throws IOException {
	    super.onBeforeSessionClosed(session);
	}
}

UDP服务端

// 采用默认配置的UDP服务端，其中implClass参数必须指定为NioUpdServer.class
@Server(implClass = NioUdpServer.class, codec = TextLineCodec.class)
public class UdpServer extends NioUdpListener {

    public Object onSessionReady() throws IOException {
        // 此接口方法的返回值将作为消息发送至客户端
        return null;
    }

    public Object onMessageReceived(InetSocketAddress sourceAddr, Object message) throws IOException {
        // 输出接收到的消息
        System.out.println("Message received: " + message);
        // 此接口方法的返回值将作为消息发送至客户端
        return message;
    }

    public void onExceptionCaught(InetSocketAddress sourceAddr, Throwable e) throws IOException {
        System.out.println(sourceAddr + "--->" + e);
    }
}

客户端（Client）：

客户端初始化参数：

#-------------------------------------
# 服务模块--客户端初始化参数
#-------------------------------------

# 客户端配置列表，多个客户端名称间用'|'分隔，默认为default
ymp.configs.serv.client.name_list=default

# 服务名称, 默认为default
ymp.configs.serv.client.default.name=default

# 远程主机IP地址, 默认为0.0.0.0
ymp.configs.serv.client.default.host=0.0.0.0

# 远程主机端口号, 默认为8281
ymp.configs.serv.client.default.port=8281

# 编解码字符集, 默认为UTF-8
ymp.configs.serv.client.default.charset=UTF-8

# 缓冲区大小, 默认为4096
ymp.configs.serv.client.default.buffer_size=4096

# 执行线程池大小, 默认为 Runtime.getRuntime().availableProcessors()
ymp.configs.serv.client.default.executor_count=10

# 连接超时时间(秒), 默认为30
ymp.configs.serv.client.default.connection_timeout=30

# 心跳发送时间间隔(秒), 默认为60
ymp.configs.serv.client.default.heartbeat_interval=60

# 自定义参数, 可选
ymp.configs.serv.client.default.params.xxx=xxx

通过在监听器实现类声明@Client注解来表示一个客户端，该注解有如下参数：

事件	说明
name	设置客户端名称，Serv框架将会根据该参数指定的名称加载对应的客户端参数配置，默认为default；
codec	设置编解码器，默认为NioStringCodec；
implClass	客户端实现类，默认为NioClient；
reconnectClass	短线重连服务实现类，默认为NONE；
hearbeatClass	链路维护(心跳)服务实现类，默认为NONE；

基于TCP协议的客户端，需要继承NioClientListener监听器类，支持监听如下事件：

事件	说明
onSessionConnected	客户端成功接入服务端后触发该事件；
onBeforeSessionClosed	客户端会话被关闭之前触发该事件；
onAfterSessionClosed	客户端会话被关闭之后触发该事件；
onMessageReceived	收到服务端发送的消息时触发该事件；
onExceptionCaught	出现异常时触发该事件；

基于UDP协议的客户端，需要继承NioUdpListener监听器类，支持监听如下事件：

事件	说明
onSessionReady	客户端与服务端连接已建立并准备就绪时触发该事件；
onMessageReceived	收到服务端发送的消息时触发该事件；
onExceptionCaught	出现异常时触发该事件；

示例代码

TCP客户端

@Client(reconnectClass = DefaultReconnectService.class,
        hearbeatClass = DefaultHeartbeatService.class, codec = TextLineCodec.class)
public class TcpClient extends NioClientListener {

    @Override
    public void onSessionConnected(INioSession session) throws IOException {
        super.onSessionConnected(session);
        //
        session.send("Hello from client.");
    }

    @Override
    public void onMessageReceived(Object message, INioSession session) throws IOException {
        super.onMessageReceived(message, session);
        //
        System.out.println(session + "--->" + message);
    }

    @Override
    public void onExceptionCaught(Throwable e, INioSession session) throws IOException {
        System.out.println(session + "--->" + e.getMessage(), e);
    }
}

UDP客户端

@Client(implClass = NioUdpClient.class, codec = TextLineCodec.class)
public class UdpClient extends NioUdpListener {

    public Object onSessionReady() throws IOException {
        return "Hello from client.";
    }

    public Object onMessageReceived(InetSocketAddress sourceAddr, Object message) throws IOException {
        System.out.println(sourceAddr + "--->" + message);
        return null;
    }

    public void onExceptionCaught(InetSocketAddress sourceAddr, Throwable e) throws IOException {
        System.out.println(sourceAddr + "--->" + e);
    }
}

客户端和服务端对象的使用

YMP框架启动时将自动扫描并加载声明了@Server和@Client注解的类，并根据注解设置和对应的参数配置进行客户端或服务端对象的初始化，但此时的客户端和服务端程序并没有直正执行，需要手动完成启动动作，代码如下：

• 示例一：启动所有已加载的客户端、服务端服务

    public static void main(String[] args) throws Exception {
        YMP.get().init();
        //
        Servs.get().startup();
    }
  

• 示例二：获取指定的客户端或服务端服务，启动服务并向服务端发送消息

    public static void main(String[] args) throws Exception {
        YMP.get().init();
  
        // 获取服务端实例对象
        NioUdpServer _serv = Servs.get().getServer(UdpServer.class);
        // 启动服务
        _serv.start();
  
        // 获取客户端实例对象
        NioUdpClient _c = Servs.get().getClient(UdpClient.class);
        // 连接到远程服务
        _c.connect();
        // 通过客户端对象向服务端发送消息
        _c.send("Message from Client.");
    }
  

  注：YMP框架初始化过程中，若使用try...finally去执行YMP.get().destroy()销毁动作，则服务刚刚启动就被停止了。

验证（Validation）

验证模块是服务端参数有效性验证工具，采用注解声明方式配置验证规则，更简单、更直观、更友好，支持方法参数和类成员属性验证，支持验证结果国际化I18N资源绑定，支持自定义验证器，支持多种验证模式；

Maven包依赖

<dependency>
    <groupId>net.ymate.platform</groupId>
    <artifactId>ymate-platform-validation</artifactId>
    <version><VERSION></version>
</dependency>

注：在项目的pom.xml中添加上述配置，该模块已经默认引入核心包依赖，无需重复配置。

默认验证器及参数说明

@VCompare

​比较两个参数值，使用场景如：新密码与重复新密码两参数值是否一致的比较；

cond：比较条件，可选EQ和NOT_EQ，默认为EQ；

with：与之比较的参数名称；

withLabel：与之比较的参数标签名称 (用于在验证消息里显示的名称)，默认为空；

msg：自定义验证消息，默认为空；

@VDateTime

日期类型参数验证；

pattern：日期格式字符串，默认为yyyy-MM-dd HH:mm:ss

msg：自定义验证消息，默认为空；

@VEmail

邮箱地址格式验证；

msg：自定义验证消息，默认为空；

@VLength

字符串长度验证；

min：设置最小长度，0为不限制； max：设置最大长度，0为不限制； msg：自定义验证消息，默认为空；

@VNumeric

数值类型参数验证；

min：设置最小值，0为不限制； max：设置最大值，0为不限制； msg：自定义验证消息，默认为空；

@VRegex

正则表达式验证；

regex：正则表达式；

msg：自定义验证消息，默认为空；

@VRequired

必填项验证；

msg：自定义验证消息，默认为空；

注：

• 以上注解中的msg参数即可以是输出的消息内容，也可以是国际化资源文件中的键；
• 验证器是按注解声明的顺序执行的，请一定要注意！！！

默认国际化资源文件内容

验证框架的默认国际化资源文件名称为 validation.properties，其内容如下：

ymp.validation.compare_not_eq={0} can not eq {1}.
ymp.validation.compare_eq={0} must be eq {1}.

ymp.validation.datetime={0} not a valid datetime.

ymp.validation.email={0} not a valid email address.

ymp.validation.length_between={0} length must be between {1} and {2}.
ymp.validation.length_min={0} length must be gt {1}.
ymp.validation.length_max={0} length must be lt {1}.

ymp.validation.numeric={0} not a valid numeric.
ymp.validation.numeric_between={0} numeric must be between {1} and {2}.
ymp.validation.numeric_min={0} numeric must be gt {1}.
ymp.validation.numeric_max={0} numeric must be lt {1}.

ymp.validation.regex={0} regex not match.

ymp.validation.required={0} must be required.

验证框架使用示例

• 示例代码：

    @Validation(mode = Validation.MODE.FULL)
    public class UserBase {
  
        @VRequired(msg = "{0}不能为空")
        @VLength(min = 3, max = 16, msg = "{0}长度必须在3到16之间")
        @VField(label = "用户名称")
        private String username;
  
        @VRequired
        @VLength(max = 32)
        private String password;
  
        @VRequired
        @VCompare(cond = VCompare.Cond.EQ, with = "password")
        private String repassword;
  
        @VModel
        @VField(name = "ext")
        private UserExt userExt;
  
        //
        // 此处省略了Get/Set方法
        //
    }
  
    public class UserExt {
  
        @VLength(max = 10)
        private String sex;
  
        @VRequired
        @VNumeric(min = 18, max = 30)
        private int age;
  
        @VRequried
        @VEmail
        private String email;
  
        //
        // 此处省略了Get/Set方法
        //
    }
  
    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            Map<String, Object> _params = new HashMap<String, Object>();
            _params.put("username", "lz");
            _params.put("password", 1233);
            _params.put("repassword", "12333");
            _params.put("ext.age", "17");
            _params.put("ext.email", "@163.com");
  
            Map<String, ValidateResult> _results = Validations.get().validate(UserBase.class, _params);
            //
            for (Map.Entry<String, ValidateResult> _entry : _results.entrySet()) {
                System.out.println(_entry.getValue().getMsg());
            }
        } finally {
            YMP.get().destroy();
        }
    }
  

• 执行结果：

    username : 用户名称长度必须在3到16之间
    repassword : repassword must be eq password.
    ext.age : ext.age numeric must be between 30 and 18.
    ext.email : ext.email not a valid email address.
  

功能注解说明：

• @Validation：验证模式配置，默认为NORMAL； + NORMAL - 短路式验证，即出现验证未通过就返回验证结果； + FULL - 对目标对象属性进行全部验证后返回全部验证结果；

• @VField：自定义待验证的成员或方法参数名称； + name：自定义参数名称，在嵌套验证时上下层参数以'.'分隔； + label：自定义参数标签名称，若@VField嵌套使用时功能将不可用；

• @VModel：声明目标对象是否为JavaBean对象，将执行对象嵌套验证；

自定义验证器

写代码前先了解一个新的注解@Validator，它的作用是声明一个类为验证器，它的参数需要绑定自定义验证器对应的注解，这个注解的作用与@VRequried等注解是一样的，开发人员可以通过该注解配置验证规则；

本例中，我们创建一个简单的自定义验证器，用来验证当前用户输入的邮箱地址是否已存在；

• 创建自定义验证器注解：

    @Target({ElementType.FIELD, ElementType.PARAMETER})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    public @interface VEmailCanUse {
  
        /**
         * @return 自定义验证消息
         */
        String msg() default "";
    }
  

• 实现IValidator接口并声明@Validator注解：

    @Validator(VEmailCanUse.class)
    public class EmailCanUseValidator implements IValidator {
  
        public ValidateResult validate(ValidateContext context) {
            ValidateResult _result = null;
            if (context.getParamValue() != null) {
                // 假定邮箱地址已存在
                VEmailCanUse _anno = (VEmailCanUse) context.getAnnotation();
                _result = new ValidateResult(context.getParamName(), StringUtils.defaultIfBlank(_anno.msg(), "邮箱地址已存在"));
            }
            return _result;
        }
    }
  

• 测试代码：

    public class VEmailCanUseBean {
  
        @VRequried
        @VEmail
        @VEmailCanUse
        private String email;
  
        //
        // 此处省略了Get/Set方法
        //
    }
  
    public static void main(String[] args) throws Exception {
        YMP.get().init();
        try {
            Map<String, Object> _params = new HashMap<String, Object>();
            _params.put("ext.email", "demo@163.com");
  
            Map<String, ValidateResult> _results = Validations.get().validate(VEmailCanUseBean.class, _params);
            //
            for (Map.Entry<String, ValidateResult> _entry : _results.entrySet()) {
                System.out.println(_entry.getKey() + " : " + _entry.getValue().getMsg());
            }
        } finally {
            YMP.get().destroy();
        }
    }
  

• 执行结果：

    ext.email : 邮箱地址已存在
  

WebMVC

WebMVC模块在YMP框架中是除了JDBC模块以外的另一个非常重要的模块，集成了YMP框架的诸多特性，在功能结构的设计和使用方法上依然保持一贯的简单风格，同时也继承了主流MVC框架的基因，对于了解和熟悉SSH等框架技术的开发人员来说，上手极其容易，毫无学习成本。

其主要功能特性如下：

• 标准MVC实现，结构清晰，完全基于注解方式配置简单；
• 支持约定模式，无需编写控制器代码，直接匹配并执行视图；
• 支持多种视图技术(JSP、Freemarker、Velocity、Text、HTML、JSON、Binary、Forward、Redirect、HttpStatus等)；
• 支持RESTful模式及URL风格；
• 支持请求参数与控制器方法参数的自动绑定；
• 支持参数有效性验证；
• 支持控制器方法的拦截；
• 支持注解配置控制器请求路由映射；
• 支持自动扫描控制器类并注册；
• 支持事件和异常的自定义处理；
• 支持I18N资源国际化；
• 支持控制器方法和视图缓存；
• 支持控制器参数转义；
• 支持插件扩展；

Maven包依赖

<dependency>
    <groupId>net.ymate.platform</groupId>
    <artifactId>ymate-platform-webmvc</artifactId>
    <version><VERSION></version>
</dependency>

注：在项目的pom.xml中添加上述配置，该模块已经默认引入核心包、验证框架包和缓存包的依赖，无需重复配置。 若不想启用缓存服务只需在ymp-conf.properties中增加排除caches模块配置，如：ymp.excluded_modules=cache

模块初始化

在Web程序中监听器(Listener)是最先被容器初始化的，所以WebMVC模块是由监听器负责对YMP框架进行初始化：

监听器(Listener)：net.ymate.platform.webmvc.support.WebAppEventListener

处理浏览器请求并与模块中控制器匹配、路由的过程可分别由过滤器(Filter)和服务端程序(Servlet)完成：

过滤器(Filter)：net.ymate.platform.webmvc.support.DispatchFilter

服务端程序(Servlet)：net.ymate.platform.webmvc.support.DispatchServlet

首先看一下完整的web.xml配置文件：

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <listener>
        <listener-class>net.ymate.platform.webmvc.support.WebAppEventListener</listener-class>
    </listener>

    <filter>
        <filter-name>DispatchFilter</filter-name>
        <filter-class>net.ymate.platform.webmvc.support.DispatchFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>DispatchFilter</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
    </filter-mapping>
    
    <!--
    <servlet>
        <servlet-name>DispatchServlet</servlet-name>
        <servlet-class>net.ymate.platform.webmvc.support.DispatchServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>DispatchServlet</servlet-name>
        <url-pattern>/service/*</url-pattern>
    </servlet-mapping>
    -->

    <welcome-file-list>
        <welcome-file>index.html</welcome-file>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>
</web-app>

模块配置

WebMVC模块的基本初始化参数配置：

#-------------------------------------
# 基本初始化参数
#-------------------------------------

# 控制器请求映射路径分析器，可选值为已知分析器名称或自定义分析器类名称，默认为restful，目前支持已知分析器[default|restful|...]
ymp.configs.webmvc.request_mapping_parser_class=

# 控制器请求处理器，可选值为已知处理器名称或自定义处理器类名称，自定义类需实现net.ymate.platform.webmvc.IRequestProcessor接口，默认为default，目前支持已知处理器[default|json|xml|...]
ymp.configs.webmvc.request_processor_class=

# 异常错误处理器，可选参数，此类需实现net.ymate.platform.webmvc.IWebErrorProcessor接口
ymp.configs.webmvc.error_processor_class=

# 缓存处理器，可选参数，此类需实现net.ymate.platform.webmvc.IWebCacheProcessor接口
ymp.configs.webmvc.cache_processor_class=

# 默认字符编码集设置，可选参数，默认值为UTF-8
ymp.configs.webmvc.default_charset_encoding=

# 请求忽略正则表达式，可选参数，默认值为^.+\.(jsp|jspx|png|gif|jpg|jpeg|js|css|swf|ico|htm|html|eot|woff|woff2|ttf|svg)$
ymp.configs.webmvc.request_ignore_regex=

# 请求方法参数名称，可选参数， 默认值为_method
ymp.configs.webmvc.request_method_param=

# 请求路径前缀，可选参数，默认值为空
ymp.configs.webmvc.request_prefix=

# 请求参数转义模式是否开启（开启状态时，控制器方法的所有参数将默认支持转义，可针对具体控制器主法或参数设置忽略转义操作），可选参数，默认值为false
ymp.configs.webmvc.parameter_escape_mode=

# 执行请求参数转义顺序，可选参数，取值范围：before(参数验证之前)和after(参数验证之后)，默认值为after
ymp.configs.webmvc.parameter_escape_order=

# 控制器视图文件基础路径（必须是以 '/' 开始和结尾，默认值为/WEB-INF/templates/）
ymp.configs.webmvc.base_view_path=

说明：在服务端程序Servlet方式的请求处理中，请求忽略正则表达式request_ignore_regex参数无效；

模块事件

WebEvent事件枚举对象包括以下事件类型：

事务类型	说明
SERVLET_CONTEXT_INITED	容器初始化事件
SERVLET_CONTEXT_DESTROYED	容器销毁事件
SERVLET_CONTEXT_ATTR_ADDED
SERVLET_CONTEXT_ATTR_REMOVEED
SERVLET_CONTEXT_ATTR_REPLACED
SESSION_CREATED	会话创建事件
SESSION_DESTROYED	会话销毁事件
SESSION_ATTR_ADDED
SESSION_ATTR_REMOVEED
SESSION_ATTR_REPLACED
REQUEST_INITED	请求初始化事件
REQUEST_DESTROYED	请求销毁事件
REQUEST_ATTR_ADDED
REQUEST_ATTR_REMOVEED
REQUEST_ATTR_REPLACED
REQUEST_RECEIVED	接收控制器方法请求事件
REQUEST_COMPLETED	完成控制器方法请求事件

控制器（Controller）

控制器(Controller)是MVC体系中的核心，它负责处理浏览器发起的所有请求和决定响应内容的逻辑处理，控制器就是一个标准的Java类，不需要继承任何基类，通过类中的方法向外部暴露接口，该方法的返回结果将决定向浏览器响应的具体内容；

下面通过示例编写WebMVC模块中的控制器：

@Controller
public class DemoController {
	
	@RequestMapping("/sayhi")
	public IView sayHi() {
		return View.textView("Hi, YMPer!");
	}
}

启动Tomcat服务并访问http://localhost:8080/sayhi，得到的输出结果将是：Hi, YMPer!

从以上代码中看到有两个注解，分别是：

• @Controller：声明一个类为控制器，框架在启动时将会自动扫描所有声明该注解的类并注册为控制器；

  name：控制器名称，默认为“”（该参数暂时未被使用）；

  singleton：指定控制器是否为单例，默认为true；

• @RequestMapping：声明控制器请求路径映射，作用域范围：类或方法；

  value：控制器请求路径映射，必选参数；

  method[]：允许的请求方式，默认为GET方式，取值范围：GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE；

  header[]：请求头中必须存在的头名称；

  param[]：请求中必须存在的参数名称；

示例一：

创建非单例控制器，其中的控制器方法规则如下：

1. 控制器方法仅支持POST和PUT方式访问；
2. 请求头参数中必须包含x-requested-with=XMLHttpRequest(即判断是否AJAX请求)；
3. 请求参数中必须存在name参数；

@Controller(singleton = false)
@RequestMapping("/demo")
public class DemoController {
	
	@RequestMapping(value = "/sayhi",
        method = {Type.HttpMethod.POST, Type.HttpMethod.PUT},
        header = {"x-requested-with=XMLHttpRequest"},
        param = {"name=*"})
	public IView sayHi() {
		return View.textView("Hi, YMPer!");
	}
}

示例说明：

本例主要展示了如何使用@Controller和@RequestMapping注解来对控制器和控制器方法对进配置；

控制器方法必须使用public修饰，否则无效；

由于控制器上也声明了@RequestMapping注解，所以控制器方法的请求路径映射将变成：/demo/sayhi；

示例二：

上例中展示了对请求的一些控制，下面展示如何对响应结果进行控制，规则如下：

1. 通过注解设置响应头参数：

• from = "china"
• age = 18

2. 通过注解设置控制器返回视图及内容："Hi, YMPer!"

@Controller
@RequestMapping("/demo")
public class DemoController {
	
	@RequestMapping("/sayhi")
	@ResponseView(value = "Hi, YMPer!", type = Type.View.TEXT)
    @ResponseHeader({
            @Header(name = "from", value = "china"),
            @Header(name = "age", value = "18", type = Type.HeaderType.INT)})
	public void sayHi() {
	}
}

本例中用到了三个注解：

• @ResponseView：声明控制器方法默认返回视图对象, 仅在方法无返回值或返回值无效时使用

  name：视图模板文件路径，默认为""；

  type：视图文件类型，默认为Type.View.NULL；

• @ResponseHeader：设置控制器方法返回结果时增加响应头参数；

  value[]：响应头@Header参数集合；

• @Header：声明一个请求响应Header键值对，仅用于参数传递；

  name：响应头参数名称，必选参数；

  value：响应头参数值，默认为""；

  type：响应头参数类型，支持STRING, INI, DATE，默认为Type.HeaderType.STRING；

控制器参数（Parameter）

WebMVC模块不但让编写控制器变得非常简单，处理请求参数也变得更加容易！WebMVC会根据控制器方法参数或类成员的注解配置，自动转换与方法参数或类成员对应的数据类型，参数的绑定涉及以下注解：

基本参数注解

• @RequestParam：绑定请求中的参数；

• @RequestHeader：绑定请求头中的参数变量；

• @CookieVariable：绑定Cookie中的参数变量；

上面三个注解拥有相同的参数：

value：参数名称，若未指定则默认采用方法参数变量名；

prefix：参数名称前缀，默认为""；

defaultValue：指定参数的默认值，默认为""；

示例代码：

	@Controller
	@RequestMapping("/demo")
	public class DemoController {
		
		@RequestMapping("/param")
		public IView testParam(@RequestParam String name,
		                  @RequestParam(defaultValue = "18") Integer age,
		                  @RequestParam(value = "name", prefix = "user") String username,
		                  @RequestHeader(defaultValue = "BASIC") String authType,
		                  @CookieVariable(defaultValue = "false") Boolean isLogin) {

		    System.out.println("AuthType: " + authType);
		    System.out.println("IsLogin: " + isLogin);
			return View.textView("Hi, " + name + ", UserName: " + username + ", Age: " + age);
		}
	}

通过浏览器访问URL测试：

	http://localhost:8080/demo/param?name=webmvc&user.name=ymper

执行结果：

	控制台输出：
	AuthType: BASIC
	IsLogin: false
	
	浏览器输出：
	Hi, webmvc, UserName: ymper, Age: 18

特别的参数注解

• @PathVariable：绑定请求映射中的路径参数变量；

  value：参数名称，若未指定则默认采用方法参数变量名；

  示例代码：

    @Controller
    @RequestMapping("/demo")
    public class DemoController {
  
    	@RequestMapping("/path/{name}/{age}")
    	public IView testPath(@PathVariable String name,
    	                  @PathVariable(value = "age") Integer age,
    	                  @RequestParam(prefix = "user") String sex) {
  
    		return View.textView("Hi, " + name + ", Age: " + age + ", Sex: " + sex);
    	}
    }
  

  通过浏览器访问URL测试：

    http://localhost:8080/demo/path/webmvc/20?user.sex=F
  

  执行结果：

    Hi, webmvc, Age: 20, Sex: F
  

  注意：

  • 默认请求解析request_mapping_parser_class=default时，基于路径的参数变量必须是连续的：

    • 正确：/path/{name}/{age}

    • 错误：/path/{name}/age/{sex}

  • 当配置请求解析request_mapping_parser_class=restful时，则以下均能正确解析：

    • 正确：/path/{name}/{age}

    • 正确：/path/{name}/age/{sex}

  • 可以通过实现IRequestMappingParser接口自行定义控制器请求规则；

• @ModelBind：值对象参数绑定注解；

  prefix：绑定的参数名称前缀，可选参数，默认为""；

  示例代码：

    public class DemoVO {
  
    	@PathVariable
    	private String name;
  
    	@RequestParam
    	private String sex;
  
    	@RequestParam(prefix = "ext")
    	private Integer age;
  
    	// 省略Get和Set方法
    }
  
    @Controller
    @RequestMapping("/demo")
    public class DemoController {
  
    	@RequestMapping("/bind/{demo.name}")
    	public IView testBind(@ModelBind(prefix = "demo") DemoVO vo) {
    		String _str = "Hi, " + vo.getName() + ", Age: " + vo.getAge() + ", Sex: " + vo.getSex();
    		return View.textView(_str);
    	}
    }
  

  通过浏览器访问URL测试：

    http://localhost:8080/demo/bind/webmvc?demo.sex=F&demo.ext.age=20
  

  执行结果：

    Hi, webmvc, Age: 20, Sex: F
  

• @ParameterEscape：控制器方法参数转义注解；

  可以通过WebMVC模块配置参数parameter_escape_order设定是在控制器方法参数执行验证之前还是之后执行参数转义动作，参数取值范围为before或after，默认为after即参数验证之后进行转义；

  scope：字符串参数转义范围，默认为Type.EscapeScope.DEFAULT；

  • 取值范围包括：JAVA, JS, HTML, XML, SQL, CSV, DEFAULT；
  • 默认值DEFAULT，它完成了对SQL和HTML两项转义；

  skiped：通知父级注解当前方法或参数的转义操作将被忽略，默认为false；

  processor：自定义字符串参数转义处理器；

  • 可以通过IParameterEscapeProcessor接口实现自定义的转义逻辑；
  • 默认实现为DefaultParameterEscapeProcessor；

  示例代码一：

    @Controller
    @RequestMapping("/demo")
    @ParameterEscape
    public class DemoController {
  
    	@RequestMapping("/escape")
        public IView testEscape(@RequestParam String content,
                                @ParameterEscape(skiped = true) @RequestParam String desc) {
  
            System.out.println("Content: " + content);
            System.out.println("Desc: " + desc);
            return View.nullView();
        }
    }
  
    // 或者：(两段代码执行结果相同)
  
    @Controller
    @RequestMapping("/demo")
    public class DemoController {
  
    	@RequestMapping("/escape")
    	@ParameterEscape
        public IView testEscape(@RequestParam String content,
                                @ParameterEscape(skiped = true) @RequestParam String desc) {
  
            System.out.println("Content: " + content);
            System.out.println("Desc: " + desc);
            return View.nullView();
        }
    }
  

  通过浏览器访问URL测试：

    http://localhost:8080/demo/escape?content=<p>content$<br><script>alert("hello");</script></p>&desc=<script>alert("hello");</script>
  

  执行结果：(控制台输出)

    Content: <p>content$<br><script>alert("hello");</script></p>
    Desc: <script>alert("hello");</script>
  

  示例一说明：

  • 由于控制器类被声明了@ParameterEscape注解，代表整个控制器类中所有的请求参数都需要被转义，因此参数content的内容被成功转义；
  • 由于参数desc声明的@ParameterEscape注解中skiped值被设置为true，表示跳过上级设置，因此参数内容未被转义；

  示例代码二：

    @Controller
    @RequestMapping("/demo")
    @ParameterEscape
    public class DemoController {
  
        @RequestMapping("/escape2")
        @ParameterEscape(skiped = true)
        public IView testEscape2(@RequestParam String content,
                                @ParameterEscape @RequestParam String desc) {
  
            System.out.println("Content: " + content);
            System.out.println("Desc: " + desc);
            return View.nullView();
        }
    }
  

  通过浏览器访问URL测试：

    http://localhost:8080/demo/escape2?content=<p>content$<br><script>alert("hello");</script></p>&desc=<script>alert("hello");</script>
  

  执行结果：(控制台输出)

    Content: <p>content$<br><script>alert("hello");</script></p>
    Desc: &lt;script&gt;alert(&quot;hello&quot;);&lt;/script&gt;
  

  示例二说明：

  • 虽然控制器类被声明了@ParameterEscape注解，但控制器方法通过skiped设置跳过转义，这表示被声明的方法参数内容不进行转义操作，因此参数content的内容未被转义；
  • 由于参数desc声明了@ParameterEscape注解，表示该参数需要转义，因此参数内容被成功转义；

  注意：当控制器类和方法都声明了@ParameterEscape注解时，则类上声明的注解将视为无效；

非单例控制器的特殊用法

单例控制器与非单例控制器的区别：

• 单例控制器类在WebMVC模块初始化时就已经实例化；
• 非单例控制器类则是在每次接收到请求时都将创建实例对象，请求结束后该实例对象被释放；

基于以上描述，非单例控制器是可以通过类成员来接收请求参数，示例代码如下：

@Controller(singleton = false)
@RequestMapping("/demo")
public class DemoController {

	@RequestParam
	private String content;

    @RequestMapping("/sayHi")
    public IView sayHi(@RequestParam String name) {
        return View.textView("Hi, " + name + ", Content: " + content);
    }
}

通过浏览器访问URL测试：

http://localhost:8080/demo/sayHi?name=YMPer&content=Welcome!

此示例代码的执行结果：

Hi, YMPer, Content: Welcome!

注意：在单例模式下，WebMVC模块将忽略为控制器类成员赋值，同时也建议在单例模式下不要使用成员变量做为参数，在并发多线程环境下会发生意想不到的问题！！

环境上下文对象（WebContext）

为了让开发人员能够随时随地获取和使用Request、Response、Session等Web容器对象，YMP框架在WebMVC模块中提供了一个名叫WebContext的Web环境上下文封装类，简单又实用，先了解一下提供的方法：

直接获取Web容器对象：

• 获取ServletContext对象：

  	WebContext.getServletContext();
  

• 获取HttpServletRequest对象：

  	WebContext.getRequest();
  

• 获取HttpServletResponse对象：

  	WebContext.getResponse();
  

• 获取PageContext对象：

  	WebContext.getPageContext();
  

获取WebMVC容器对象：

• 获取IRequestContext对象：

  	WebContext.getRequestContext();
  

  WebMVC请求上下文接口，主要用于分析请求路径及存储相关参数；

• 获取WebContext对象实例：

  	WebContext.getContext();
  

WebContext将Application、Session、Request等Web容器对象的属性转换成Map映射存储，同时向Map的赋值也将自动同步至对象的Web容器对象中，起初的目的是为了能够方便代码移植并脱离Web环境依赖进行开发测试(功能参考Struts2)：

• WebContext.getContext().getApplication();

• WebContext.getContext().getSession();

• WebContext.getContext().getAttribute(Type.Context.REQUEST);

  原本可以通过WebContext.getContext().getRequest方法直接获取的，但由于设计上的失误，方法名已被WebContext.getRequest()占用，若变更方法名受影响的项目太多，所以只好委屈它了:D，后面会介绍更多的辅助方法来操作Request属性，所以可以忽略它的存在！

• WebContext.getContext().getAttributes();

• WebContext.getContext().getLocale();

• WebContext.getContext().getOwner();

• WebContext.getContext().getParameters();

WebContext操作Application的辅助方法：

• boolean getApplicationAttributeToBoolean(String name);

• int getApplicationAttributeToInt(String name);

• long getApplicationAttributeToLong(String name);

• String getApplicationAttributeToString(String name);

• <T> T getApplicationAttributeToObject(String name);

• WebContext addApplicationAttribute(String name, Object value)

WebContext操作Session的辅助方法：

• boolean getSessionAttributeToBoolean(String name);

• int getSessionAttributeToInt(String name);

• long getSessionAttributeToLong(String name);

• String getSessionAttributeToString(String name);

• <T> T getSessionAttributeToObject(String name);

• WebContext addSessionAttribute(String name, Object value)

WebContext操作Request的辅助方法：

• boolean getRequestAttributeToBoolean(String name);

• int getRequestAttributeToInt(String name);

• long getRequestAttributeToLong(String name);

• String getRequestAttributeToString(String name);

• <T> T getRequestAttributeToObject(String name);

• WebContext addRequestAttribute(String name, Object value)

WebContext操作Parameter的辅助方法：

• boolean getParameterToBoolean(String name);

• int getParameterToInt(String name)

• long getParameterToLong(String name);

• String getParameterToString(String name);

WebContext操作Attribute的辅助方法：

• <T> T getAttribute(String name);

• WebContext addAttribute(String name, Object value);

WebContext获取IUploadFileWrapper上传文件包装器：

• IUploadFileWrapper getUploadFile(String name);

• IUploadFileWrapper[] getUploadFiles(String name);

文件上传（Upload）

WebMVC模块针对文件的上传处理以及对上传的文件操作都非常的简单，通过注解就轻松搞定：

• @FileUpload：声明控制器方法需要处理上传的文件流；

  无参数，需要注意的是文件上传处理的表单enctype属性：

    <form action="/demo/upload" method="POST" enctype="multipart/form-data">
    ......
    </form>
  

• IUploadFileWrapper：上传文件包装器接口，提供对已上传文件操作的一系列方法；

示例代码：

@Controller
@RequestMapping("/demo)
public class UploadController {

	// 处理单文件上传
	@RequestMapping(value = "/upload", method = Type.HttpMethod.POST)
	@FileUpload
	public IView doUpload(@RequestParam
				          IUploadFileWrapper file) throws Exception {
		// 获取文件名称
		file.getName();
		
		// 获取文件大小
		file.getSize();
		
		// 获取完整的文件名及路径
		file.getPath();
		
		// 获取文件Content-Type
		file.getContentType();
		
		// 转移文件
		file.transferTo(new File("/temp", file.getName()));
		
		// 保存文件
		file.writeTo(new File("/temp", file.getName());
		
		// 删除文件
		file.delete();
		
		// 获取文件输入流对象
		file.getInputStream();
		
		// 获取文件输出流对象
		file.getOutputStream();
		
		return View.nullView();
	}

	// 处理多文件上传
	@RequestMapping(value = "/uploads", method = Type.HttpMethod.POST)
	@FileUpload
	public IView doUpload(@RequestParam
				          IUploadFileWrapper[] files) throws Exception {

		// ......

		return View.nullView();
	}
}

文件上传相关配置参数：

#-------------------------------------
# 文件上传配置参数
#-------------------------------------

# 文件上传临时目录，为空则默认使用：System.getProperty("java.io.tmpdir")
ymp.configs.webmvc.upload_temp_dir=

# 上传文件大小最大值（字节），默认值：10485760（注：10485760 = 10M）
ymp.configs.webmvc.upload_file_size_max=

# 上传文件总量大小最大值（字节）, 默认值：10485760（注：10485760 = 10M）
ymp.configs.webmvc.upload_total_size_max=

# 内存缓冲区的大小，默认值： 10240字节（=10K），即如果文件大于10K，将使用临时文件缓存上传文件
ymp.configs.webmvc.upload_size_threshold=

# 文件上传状态监听器，可选参数，默认值为空
ymp.configs.webmvc.upload_file_listener_class=

文件上传状态监听器(upload_file_listener_class)配置：

WebMVC模块的文件上传是基于Apache Commons FileUpload组件实现的，所以通过其自身提供的ProgressListener接口即可实现对文件上传状态的监听；

示例代码：实现上传文件的进度计算；

public class UploadProgressListener implements ProgressListener {

    public void update(long pBytesRead, long pContentLength, int pItems) {
        if (pContentLength == 0) {
            return;
        }
        // 计算上传进度百分比
        double percent = (double) pBytesRead / (double) pContentLength;
        // 将百分比存储在用户会话中
        WebContext.getContext().getSession().put("upload_progress", percent);
    }
}

• 将该接口实现类配置到 ymp.configs.webmvc.upload_file_listener_class 参数中；

• 通过Ajax定时轮循的方式获取会话中的进度值，并展示在页面中；

视图（View）

WebMVC模块支持多种视图技术，包括JSP、Freemarker、Velocity、Text、HTML、JSON、Binary、Forward、Redirect、HttpStatus等，也可以通过IView接口扩展实现自定义视图；

控制器视图的表示方法

• 通过返回IView接口类型；
• 通过字符串表达一种视图类型；
• 无返回值或返回值为空，将使用当前RequestMapping路径对应的JspView视图；

视图文件路径配置

控制器视图文件基础路径，必须是以 '/' 开始和结尾，默认值为/WEB-INF/templates/；

  ymp.configs.webmvc.base_view_path=/WEB-INF/templates/

视图对象操作示例

视图文件可以省略扩展名称，通过IView接口可以直接设置请求参数和内容类型；

  // 通过View对象创建视图对象
  IView _view = View.jspView("/demo/test")
          .addAttribute("attr1", "value")
          .addAttribute("attr2", 2)
          .addHeader("head", "value")
          .setContentType(Type.ContentType.HTML.getContentType());

  // 直接创建视图对象
  _view = new JspView("/demo/test");

  // 下面三种方式的结果是一样的，使用请求路径对应的视图文件返回
  _view = View.jspView();
  _view = JspView.bind();
  _view = new JspView();

WebMVC模块提供的视图

JspView：JSP视图；

  View.jspView("/demo/test.jsp");
  // = "jsp:/demo/test"

FreemarkerView：Freemarker视图；

  View.freemarkerView("/demo/test.ftl");
  // = "freemarker:/demo/test"

VelocityView：Velocity视图；

  View.velocityView("/demo/test.vm");
  // = "velocity:/demo/test"

TextView：文本视图；

  View.textView("Hi, YMPer!");
  // = "text:Hi, YMPer!"

HtmlView：HTML文件内容视图；

  View.htmlView("<p>Hi, YMPer!</p>");
  // = "html:<p>Hi, YMPer!</p>"

JsonView：JSON视图；

  // 直接传递对象
  User _user = new User();
  user.setId("...");
  ...
  View.jsonView(_user);

  // 传递JSON字符串
  View.jsonView("{id:\"...\", ...}");
  // = "json:{id:\"...\", ...}"

BinaryView：二进制数据流视图；

  // 下载文件，并重新指定文件名称
  View.binaryView(new File("/temp/demo.txt"))
  		.useAttachment("测试文本.txt");
  // = "binary:/temp/demo.txt:测试文本.txt"

若不指定文件名称，则回应头中将不包含 "attachment;filename=xxx"

ForwardView：请求转发视图；

  View.forwardView("/demo/test");
  // = "forward:/demo/test"

RedirectView：重定向视图；

  View.redirectView("/demo/test");
  // = "redirect:/demo/test"

HttpStatusView：HTTP状态视图

  View.httpStatusView(404);
  // = "http_status:404"

  View.httpStatusView(500, "系统忙, 请稍后再试...");
  // = "http_status:500:系统忙, 请稍后再试..."

NullView：空视图；

  View.nullView();

验证（Validation）

WebMVC模块已集成验证模块，控制器方法可以直接使用验证注解完成参数的有效性验证，详细内容请参阅 验证(Validation) 模块文档；

说明：

• 控制器的参数验证规则全部通过验证注解进行配置并按顺序执行，由WebMVC框架自动调用完成验证过程，无需手动干预；
• 参数验证过程将在控制器配置的拦截器执行完毕后执行，也就是说拦截器中获取的请求参数值并未验证过；

缓存（Cache）

集成缓存模块

WebMVC模块已集成缓存模块，通过@Cacheable注解即可轻松实现控制器方法的缓存，通过配置缓存模块的scope_processor_class参数可以支持APPLICATION和SESSION作用域；

# 设置缓存作用域处理器
ymp.configs.cache.scope_processor_class=net.ymate.platform.webmvc.support.WebCacheScopeProcessor

示例代码：将方法执行结果以会话(SESSION)级别缓存180秒；

	@Controller
	@RequestMapping("/demo")
	@Cacheable
	public class CacheController {
	
		@RequestMapping("/cache")
		@Cacheable(scope = ICaches.Scope.SESSION, timeout = 180)
		public IView doCacheable(@RequestParam String content) throws Exception {
			// ......
			return View.textView("Content: " + content);
		}
	}

注意：基于@Cacheable的方法缓存只是缓存控制器方法返回的结果对象，并不能缓存IView视图的最终执行结果；

自定义缓存处理器

WebMVC模块提供了缓存处理器IWebCacheProcessor接口，可以让开发者通过此接口对控制器执行结果进行最终处理，该接口作用于被声明@ResponseCache注解的控制器类和方法上；

说明: 框架提供IWebCacheProcessor接口默认实现net.ymate.platform.webmvc.support.WebCacheProcessor用以缓存视图执行结果， 但需要注意的是当使用它时, 请检查web.xml的过滤器DispatchFilter中不要配置<dispatcher>INCLUDE</dispatcher>，否则将会产生死循环；

@ResponseCache注解参数说明：

cacheName：缓存名称, 可选参数, 默认值为default；

key：缓存Key, 可选参数, 若未设置则由IWebCacheProcessor接口实现自动生成；

processorClass：自定义视图缓存处理器, 可选参数，若未提供则采用默认IWebCacheProcessor接口参数配置；

scope：缓存作用域, 可选参数，可选值为APPLICATION、SESSION和DEFAULT，默认为DEFAULT；

timeout：缓存数据超时时间, 可选参数，数值必须大于等于0，为0表示默认缓存300秒；

useGZip：是否使用GZIP压缩, 默认值为true

默认IWebCacheProcessor接口参数配置：

# 缓存处理器，可选参数
ymp.configs.webmvc.cache_processor_class=demo.WebCacheProc

框架默认提供了该接口的实现类：net.ymate.platform.webmvc.support.WebCacheProcessor

• 基于Cache缓存模块使其对@ResponseCache注解中的Scope.DEFAULT作用域支持Last-Modified等浏览器相关配置，并支持GZIP压缩等特性

示例代码：

package demo;

import net.ymate.platform.webmvc.*;
import net.ymate.platform.webmvc.view.IView;

public class WebCacheProc implements IWebCacheProcessor {
    public boolean processResponseCache(IWebMvc owner, ResponseCache responseCache, IRequestContext requestContext, IView resultView) throws Exception {
    	// 这里是对View视图自定义处理逻辑...
    	// 完整的示例代码请查看net.ymate.platform.webmvc.support.WebCacheProcessor类源码
        return false;
    }
}

@Controller
@RequestMapping("/demo")
public class CacheController {

	@RequestMapping("/cache")
	@ResponseCache
	public IView doCacheable(@RequestParam String content) throws Exception {
		// ......
		return View.textView("Content: " + content);
	}
}

说明：该接口方法返回布尔值，用于通知WebMVC框架是否继续处理控制器视图；

拦截器（Intercept）

WebMVC模块基于YMPv2.0的新特性，原生支持AOP方法拦截，通过以下注解进行配置：

@Before：用于设置一个类或方法的前置拦截器，声明在类上的前置拦截器将被应用到该类所有方法上；

@After：用于设置一个类或方的后置拦截器，声明在类上的后置拦截器将被应用到该类所有方法上；

@Around：用于同时配置一个类或方法的前置和后置拦截器；

@Clean：用于清理类上全部或指定的拦截器，被清理的拦截器将不会被执行；

@ContextParam：用于设置上下文参数，主要用于向拦截器传递参数配置；

@Ignored：声明一个方法将忽略一切拦截器配置；

说明: 声明@Ignored注解的方法、非公有方法和Object类方法及Object类重载方法将不被拦截器处理。

示例代码：

	// 创建自定义拦截器
    public class UserSessionChecker implements IInterceptor {
        public Object intercept(InterceptContext context) throws Exception {
            // 判断当前拦截器执行方向
            if (context.getDirection().equals(Direction.BEFORE)
            		&& WebContext.getRequest().getSession(false) == null) {
                return View.redirectView("/user/login");
            }
            return null;
        }
    }

	@Controller
	@RequestMapping("/user")
	@Before(UserSessionChecker.class)
	public class Controller {

		@RequestMapping("/center")
		public IView userCenter() throws Exception {
			// ......
			return View.jspView("/user/center");
		}

		@RequestMapping("/login")
		@Clean
		public IView userLogin() throws Exception {
			return View.jspView("/user/login");
		}
	}

Cookies操作

WebMVC模块针对Cookies这个小甜点提供了一个名为CookieHelper的小工具类，支持Cookie参数的设置、读取和移除操作，同时支持对编码和加密处理，并允许通过配置参数调整Cookie策略；

Cookie配置参数

#-------------------------------------
# Cookie配置参数
#-------------------------------------

# Cookie键前缀，可选参数，默认值为空
ymp.configs.webmvc.cookie_prefix=

# Cookie作用域，可选参数，默认值为空
ymp.configs.webmvc.cookie_domain=

# Cookie作用路径，可选参数，默认值为'/'
ymp.configs.webmvc.cookie_path=

# Cookie密钥，可选参数，默认值为空
ymp.configs.webmvc.cookie_auth_key=

# Cookie密钥验证是否默认开启, 默认值为false
ymp.configs.webmvc.default_enabled_cookie_auth=

# Cookie是否默认使用HttpOnly, 默认值为false
ymp.configs.webmvc.default_use_http_only=

示例代码：演示Cookie操作

// 创建CookieHelper对象
CookieHelper _helper = CookieHelper.bind(WebContext.getContext().getOwner());

// 设置开启采用密钥加密(将默认开启Base64编码)
_helper.allowUseAuthKey();

// 设置开启采用Base64编码(默认支持UrlEncode编码)
_helper.allowUseBase64();

// 设置开启使用HttpOnly
_helper.allowUseHttpOnly();

// 添加或重设Cookie，过期时间基于Session时效
_helper.setCookie("current_username", "YMPer");

// 添加或重设Cookie，并指定过期时间
_helper.setCookie("current_username", "YMPer", 1800);

// 获取Cookie值
BlurObject _currUsername = _helper.getCookie("current_username");

// 获取全部Cookie
Map<String, BlurObject> _cookies = _helper.getCookies();

// 移除Cookie
_helper.removeCookie("current_username");

// 清理所有的Cookie
_helper.clearCookies();

国际化（I18N）

基于YMPv2.0框架I18N支持，整合WebMVC模块并提供了默认II18NEventHandler接口实现，配置方法：

// 指定WebMVC模块的I18N资源管理事件监听处理器
ymp.i18n_event_handler_class=net.ymate.platform.webmvc.support.I18NWebEventHandler

// 语言设置的参数名称，可选参数，默认为空
ymp.params._lang=_lang

// 资源文件存放路径，可选参数，默认为${root}/i18n/
ymp.params.i18n_resources_home=${root}/i18n/

加载当前语言设置的步骤：

1. 尝试加载请求作用域中_lang参数；
2. 尝试加载框架自定义配置ymp.params._lang参数；
3. 尝试从Cookies里加载_lang的参数；
4. 使用系统默认语言设置；

约定模式（Convention Mode）

名词解释：约定优于配置（Convention Over Configuration），也称作按约定编程，是一种软件设计范式，通过命名规则之类的约束来减少程序中的配置，旨在减少软件开发人员需要做决定的数量，获得简单的好处，而又不失灵活性。

有些时候我们仅仅是为了能够访问一个视图文件而不得不编写一个控制器方法与之对应，当这种重复性的工作很多时，就变成了灾难，因此，在WebMVC模块中，通过开启约定模式即可支持直接访问base_view_path路径下的视图文件，无需编写任何代码；

WebMVC模块的约定模式默认为关闭状态，需要通过配置参数开启：

ymp.configs.webmvc.convention_mode=true

访问权限规则配置

在约定模式模式下，支持设置不同路径的访问权限，规则是：-号代表禁止访问，+或无符串代表允许访问，多个路径间用|分隔；

访问权限示例：禁止访问admin目录和index.jsp文件，目录结构如下：

WEB-INF\
|
|--templates\
|	|
|	+--admin\
|	|
|	+--users\
|	|
|	+--reports\
|	|
|	+--index.jsp
|	|
|	<...>

示例参数配置：

ymp.configs.webmvc.convention_view_paths=admin-|index-|users|reports+

拦截器规则配置

由于在约定模式下，访问视图文件无需控制器，所以无法通过控制器方法添加拦截器配置，因此，WebMVC模块针对约定模式单独提供了拦截器规则配置这一扩展功能，主要是通过@InterceptorRule配合IInterceptorRule接口使用；

拦截器规则设置默认为关闭状态，需要通过配置参数开启：

ymp.configs.webmvc.convention_interceptor_mode=true

拦截规则配置示例：

@InterceptorRule("/demo")
@Before(WebUserSessionCheck.class)
public class InterceptRuleDemo implements IInterceptorRule {

    @InterceptorRule("/admin/*")
    @Before(AdminTypeCheckFilter.class)
    public void adminAll() {
    }

    @Clean
    @InterceptorRule("/admin/login")
    public void adminLogin() {
    }

    @InterceptorRule("/user/*")
    public void userAll() {
    }

    @InterceptorRule("/mobile/person/*")
    public void mobilePersonAll() {
    }
}

说明：

@InterceptorRule：拦截器规则注解；

• 在实现IInterceptorRule接口的类上声明，表示该类为拦截规则配置；
• 在类方法上声明，表示针对一个具体的请求路径配置规则，与@RequestMapping的作用相似；

规则配置中支持的注解：

• @Before：约定模式下的拦截器仅支持@Before前置拦截；
• @Clean：清理上层指定的拦截器；
• @ContextParam：上下文参数；
• @ResponseCache：声明控制器方法返回视图对象的执行结果将被缓存；

注意：配置规则类的方法可以是任意的，方法本身无任何意义，仅是通过方法使用注解；

URL伪静态

WebMVC模块通过约定模式可以将参数融合在URL中，不再通过?传递参数，让URL看上去更好看一些；

伪静态模式默认为关闭状态，需要通过配置参数开启：

ymp.configs.webmvc.convention_urlrewrite_mode=true

参数传递规则：

• URL中通过分隔符_传递多个请求参数；
• 通过UrlParams[index]方式引用参数值；

伪静态示例：

URL原始格式：
http://localhost:8080/user/info/list?type=all&page=2&page_size=15

URL伪静态格式:
http://localhost:8080/user/info/list_all_2_15

请求参数的引用：

// 通过EL表达式获取参数
${UrlParams[0]}：all
${UrlParams[1]}：2
${UrlParams[2]}：15

注意：伪静态参数必须是连续的，UrlParams参数集合存储在Request作用域内；

约定模式完整的配置参数

#-------------------------------------
# 约定模式配置参数
#-------------------------------------

# 是否开启视图自动渲染（约定优于配置，无需编写控制器代码，直接匹配并执行视图）模式，可选参数，默认值为false
ymp.configs.webmvc.convention_mode=

# Convention模式开启时视图文件路径(基于base_view_path的相对路径，'-'号代表禁止访问，'+'或无符串代表允许访问)，可选参数，默认值为空(即不限制访问路径)，多个路径间用'|'分隔
ymp.configs.webmvc.convention_view_paths=

# Convention模式开启时是否采用URL伪静态(URL中通过分隔符'_'传递多个请求参数，通过UrlParams[index]方式引用参数值)模式，可选参数，默认值为false
ymp.configs.webmvc.convention_urlrewrite_mode=

# Convention模式开启时是否采用拦截器规则设置，可选参数，默认值为false
ymp.configs.webmvc.convention_interceptor_mode=

高级特性

控制器请求处理器

在WebMVC模块中除了支持标准Web请求的处理过程，同时也对基于XML和JSON协议格式的请求提供支持，有两种使用场景：

场景一：全局设置，将影响所有的控制器方法；

通过下面的参数配置，默认为default，可选值为[default|json|xml]，也可以是开发者自定义的IRequestProcessor接口实现类名称；

ymp.configs.webmvc.request_processor_class=default

场景二：针对具体的控制器方法进行设置；

@Controller
@RequestMapping("/demo")
public class DemoController {

    @RequestMapping("/sayHi")
    @RequestProcessor(JSONRequestProcessor.class)
    public IView sayHi(@RequestParam String name， @RequestParam String content) {
        return View.textView("Hi, " + name + ", Content: " + content);
    }
    
    @RequestMapping("/sayHello")
    @RequestProcessor(XMLRequestProcessor.class)
    public IView sayHello(@RequestParam String name， @RequestParam String content) {
        return View.textView("Hi, " + name + ", Content: " + content);
    }
}

通过POST方式向http://localhost:8080/demo/sayHi发送如下JSON数据：

{ "name" : "YMPer", "content" : "Welcome!" }

通过POST方式向http://localhost:8080/demo/sayHello发送如下XML数据：

<xml>
	<name>YMPer</name>
	<content><![CDATA[Welcome!]]></content>
</xml>

以上JSON和XML这两种协议格式的控制器方法，同样支持参数的验证等特性；

控制器执行结果自定义响应处理

通过@ResponseBody注解可以将控制器方法返回的执行结果对象（String或IView除外）进行自定义输出，默认将以JSON格式输出，可以通过IResponseBodyProcessor接口自定义实现输出方式；

• @ResponseBody注解说明：

  value：自定义对象输出处理器（即IResponseBodyProcessor接口实现类）, 默认为：DefaultResponseBodyProcessor.class；

  contentType：响应头是否携带Content-Type参数项，默认为：true；

  keepNull：是否保留空值参数项，默认为：true；

  quoteField：参数键名是否使有引号标识符，默认为：true；

• 示例代码：

   @Controller
   public class HelloController {
  
       @RequestMapping("/hello")
       @ResponseBody
       public DemoBean hello() throws Exception {
           DemoBean _result = new DemoBean();
           _result.setName("YMPer");
           _result.setAge(10);
           //
           return _result;
       }
   }
  

  执行结果：

   {"name":"YMPer","age":10}
  

异常错误处理器

方式一：WebMVC模块为开发者提供了一个IWebErrorProcessor接口，允许针对异常、验证结果和约定模式的URL解析逻辑实现自定义扩展；

通过下面的参数配置即可：

ymp.configs.webmvc.error_processor_class=net.ymate.framework.webmvc.WebErrorProcessor

示例代码：

public class WebErrorProcessor implements IWebErrorProcessor {

	/**
     * 异常时将执行事件回调
     *
     * @param owner 所属YMP框架管理器实例
     * @param e     异常对象
     */
    public void onError(IWebMvc owner, Throwable e) {
    	// ...你的代码逻辑
    }

	/**
     * @param owner   所属YMP框架管理器实例
     * @param results 验证器执行结果集合
     * @return 处理结果数据并返回视图对象，若返回null则由框架默认处理
     */
    public IView onValidation(IWebMvc owner, Map<String, ValidateResult> results) {
    	// ...你的代码逻辑
    	return View.nullView();
    }

	/**
     * 自定义处理URL请求过程
     *
     * @param owner          所属YMP框架管理器实例
     * @param requestContext 请求上下文
     * @return 可用视图对象，若为空则采用系统默认
     * @throws Exception 可能产生的异常
     */
    public IView onConvention(IWebMvc owner, IRequestContext requestContext) throws Exception {
    	// ...你的代码逻辑
    	return View.nullView();
    }
}

方式二：通过@ResponseErrorProcessor注解并配合IResponseErrorProcessor接口实现控制器类或方法指定自定义异常处理过程；

示例代码：

public class DemoRequestProcessor implements IResponseErrorProcessor {

    @Override
    public IView processError(IWebMvc owner, Throwable e) {
        return TextView.bind("Error: " + e.getMessage);
    }
}

@Controller
@RequestMapping("/demo")
public class DemoController {

    @RequestMapping("/sayHi")
    @ResponseErrorProcessor(DemoRequestProcessor.class)
    public IView sayHi(@RequestParam String name， @RequestParam String content) {
        // 模拟异常
        System.out.println(1 / 0);
        return View.textView("Hi, " + name + ", Content: " + content);
    }
}

控制器包配置

通过package-info.java为包中同级的控制器类添加通用配置，允许使用的注解：

• @RequestMapping：控制器请求路径映射；
• @RequestProcessor：控制器请求自定义处理器注解；
• @ParameterEscape：控制器方法参数转义注解；
• @ResponseCache：控制器方法返回视图对象执行结果缓存注解；
• @ResponseHeader：控制器方法返回结果时增加响应头参数；
• @ResponseView：控制器方法默认返回视图对象；
• @ResponseBody: 控制器方法返回结果对象自定义输出；
• @ResponseErrorProcessor：控制器方法的默认异常处理器；

示例代码：

本例将为net.ymate.demo.controller包指定统一的请求路径映射和响应头配置，其package-info.java内容如下：

@RequestMapping("/v1/api")
@ResponseHeader({
        @Header(name = "X-Request-Token", value = "c43e3bab82ab45278b0d5872d6c6d3b6"),
        @Header(name = "X-Request-Scope", value = "request")})
package net.ymate.demo.controller;

import net.ymate.platform.webmvc.annotation.Header;
import net.ymate.platform.webmvc.annotation.RequestMapping;
import net.ymate.platform.webmvc.annotation.ResponseHeader;

One More Thing

YMP不仅提供便捷的Web及其它Java项目的快速开发体验，也将不断提供更多丰富的项目实践经验。

感兴趣的小伙伴儿们可以加入 官方QQ群480374360，一起交流学习，帮助YMP成长！

了解更多有关YMP框架的内容，请访问官网：http://www.ymate.net/

转载于:https://my.oschina.net/robocop/blog/1785404