Spring 系列教程之自定义标签的解析

Spring 系列教程之自定义标签的解析

在之前的章节中，我们提到了在 Spring 中存在默认标签与自定义标签两种，而在上一章节中我们分析了 Spring 中对默认标签的解析过程，相信大家一定已经有所感悟。那么，现在将开始新的里程，分析 Spring 中自定义标签的加载过程。同样，我们还是先再次回顾一下，当完成从配置文件到 Document 的转换并提取对应的 root 后，将开始了所有元素的解析，而在这一过程中便开始了默认标签与自定义标签两种格式的区分，函数如下：

protected void parseBeanDefinitions(Element root, BeanDefinitionParserDelegate delegate) {
    if (delegate.isDefaultNamespace(root)) {
        NodeList nl = root.getChildNodes();
        for (int i = 0; i < nl.getLength(); i++) {
            Node node = nl.item(i);
            if (node instanceof Element) {
                Element ele = (Element) node;
                if (delegate.isDefaultNamespace(ele)) {
                    parseDefaultElement(ele, delegate);
                }
                else {
                    delegate.parseCustomElement(ele);
                }
            }
        }
    }
    else {
        delegate.parseCustomElement(root);
    }
}

在本章中，所有的功能都是围绕其中的一句代码 delegate.parseCustomElement(root) 开展的。从上面的函数我们可以看出，当 Spring 拿到一个元素时首先要做的是根据命名空间进行解析，如果是默认的命名空间，则使用 parseDefaultElement() 方法进行元素解析，否则使用 parseCustomElement() 方法进行解析。在分析自定义标签的解析过程前，我们先了解一下自定义标签的使用过程。

4.1 自定义标签使用

在很多情况下，我们需要为系统提供可配置化支持，简单的做法可以直接基于 Spring 的标准 bean 来配置，但配置较为复杂或者需要更多丰富控制的时候，会显得非常笨拙。一般的做法会用原生态的方式去解析定义好的的 XML 文件，然后转化为配置对象。这种方式当然可以解决所有问题，但实现起来比较繁琐，特别是在配置非常复杂的时候，解析工作是一个不得不考虑的负担。 Spring 提供了可扩展 Schema 的支持，这是一个不错的折中方案，扩展 Spring 自定义标签配置大致需要以下几个步骤(前提是要把 Spring 的 core 包加入项目中)：

(1) 创建一个需要扩展的组件。

(2) 定义一个 XSD 文件描述组件内容。

(3) 创建一个文件，实现 BeanDefinitionParser 接口，用来解析 XSD 文件中的定义和组件定义。

(4) 创建一个 Handler 文件，扩展自 NamespaceHandlerSupport，目的是将组件注册到 Spring 容器。

(5) 编写 Spring.handlers和 Spring.schemas 文件。

现在我们就按照上面的步骤带领读者一步步地体验自定义标签的过程。

(1) 首先我们创建一个普通的 POJO，这个 POJO 没有任何特别之处，只是用来接收配置文件。

public class User {
    private String username;
    private String email;

    // 省略 getter/setter 方法
}

(2) 定义一个 XSD 文件描述组件内容。

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://com.github.binarylei/schema/user"
        xmlns:tns="http://com.github.binarylei/schema/user"
        elementFormDefault="qualified">

    <element name="user">
        <complexType>
            <attribute name="id" type="string"/>
            <attribute name="userName" type="string"/>
            <attribute name="email" type="string"/>
        </complexType>
    </element>
</schema>

在上面的 XSD 文件中描述了一个新的 targetNamespace，并在这个空间中定义了一个 name 为 user 的 element，user有3个属性 id、 username 和 email，其中 email 的类型为 string。这3个类主要用于验证 Spring 配置文件中自定义格式。XSD 文件是 XML DTD 的替代者，使用 XML Schema 语言进行编写，这里对 XSD Schema 不做太多解释，有兴趣的读者可以参考相关的资料

(3) 创创建一个文件，实现 BeanDefinitionParser 接口，用来解析 XSD 文件中的定义和组件定义

public class UserBeanDefinitionParser extends AbstractSingleBeanDefinitionParser {

    protected Class<?> getBeanClass(Element element) {
        return User.class;
    }

    protected void doParse(Element element, BeanDefinitionBuilder bean) {
        String username = element.getAttribute("username");
        String email = element.getAttribute("email");

        // 将提取的数据放入到时 BeanDefinitionBuilder 中
        // 待完成所有 bean 的解析后统一注册到 beanFactory
        if (StringUtils.hasText(username)) {
            bean.addPropertyValue("username", username);
        }

        if (StringUtils.hasText(email)) {
            bean.addPropertyValue("email", email);
        }
    }
}

(4) 创建一个 Handler 文件，扩展自 NamespaceHandlerSupport，目的是将组件注册到，目的是将组件注册到 Spring 容器。

public class NamespaceHandler extends NamespaceHandlerSupport {
    @Override
    public void init() {
        registerBeanDefinitionParser("user", new UserBeanDefinitionParser());
    }
}

(5) 在工程的 META-INF 文件夹下新建 Spring.handlers 和 Spring.schemas 两个文件，内容如下：

• Spring.handlers

  http://com.github.binarylei/schema/user=spring.custom_bean.NamespaceHandler

• Spring.schemas

  http://com.github.binarylei/schema/user.xsd=spring/custom_bean/user.xsd

到这里，自定义的配置就结束了，而 Spring 加载自定义的大致流程是遇到自定义标签然后就去 spring.handlers 和 spring.schemas 中去找对应的 handler 和 XSD，默认位置是 META-NF 下，进而有找到对应的 handler 以及解析元素的 Parser，从而完成了整个自定义元素的解析，也就是说自定义与 Spring 中默认的标准配置不同在于 Spring 将自定义标签解析的工作委托给了用户去实现。

(6) 创建测试配置文件，在配置文件中引入对应的命名空间以及 XSD 后，便可以直接使用自定义标签了。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:myname="http://com.github.binarylei/schema/user"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://com.github.binarylei/schema/user http://com.github.binarylei/schema/user.xsd">

    <myname:user id="testBean" userName="binarylei" email="[e-mail]"/>
</beans>

(7) 测试

public static void main(String[] args) {
    ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext(
            "spring/custom_bean/user.xml");
    User test = (User) context.getBean("testBean");
    System.out.println(test.getEmail());
}

不出意外的话，你应该看到了我们期待的结果，控制台上打印出：[e-mail]。

在上面的例子中，我们实现了通过自定义标签实现了通过属性的方式将 user 类型的 Bean 赋值，在 Spring 中自定义标签非常常用，例如我们熟知的事务标签:tx(tx:annotation-driven)

4.2 自定义标签解析

了解了自定义标签的使用后，我们带着强烈的好奇心来探究一下自定义标签的解析过程。

public BeanDefinition parseCustomElement(Element ele) {
    return parseCustomElement(ele, null);
}

// containingBd 为父类 bean，对顶层元素的解析就设置为 null
public BeanDefinition parseCustomElement(Element ele, BeanDefinition containingBd) {
    // 获取对应的命名空间
    String namespaceUri = getNamespaceURI(ele);
    // 根据命名空间找到对应的 NamespaceHandler
    NamespaceHandler handler = this.readerContext.getNamespaceHandlerResolver().resolve(namespaceUri);
    if (handler == null) {
        error("Unable to locate Spring NamespaceHandler for XML schema namespace [" + namespaceUri + "]", ele);
        return null;
    }
    // 调用自定义的 NamespaceHandler 进行解析
    return handler.parse(ele, new ParserContext(this.readerContext, this, containingBd));
}

相信了解了自定义标签的使用方法后，或多或少会对自定义标签的实现过程有一个自己的想法。其实思路非常的简单，无非是根据对应的 bean 获取对应的命名空间，根据命名空间解析对应的处理器，然后根据用户自定义的处理器进行解析。可是有些事情说起来简单做起来难，我们先看看如何获取命名空间吧。

4.2.1 获取标签的命名空间

标签的解析是从命名空间的提起开始的，无论是区分 Spring 中默认标签和自定义标签还是区分自定义标签中不同标签的处理器都是以标签所提供的命名空间为基础的，而至于如何提取对应元素的命名空间其实并不需要我们亲自去实现，在 org.w3c.dom.Node 中已经提供了方法供我们直接调用：

public String getNamespaceURI(Node node) {
    return node.getNamespaceURI();
}

4.2.2 提取自定义标签处理器

有了命名空间，就可以进行 NamespaceHandler 的提取了，继续之前的 parseCustomElement() 函数的跟踪，分析 NamespaceHandler handler = this.readerContext.getNamespaceHandlerResolver().resolve(namespaceUri)，在 readerContext 初始化的日时候其属性 namespacehandlerresolver 已经被初始化为了 DefaultNamespaceHandlerreSolver 的实例，所以，这里调用的 resolve() 方法其实调用的是 Defaultnamespacehandlerresolver 类中的方法。我们进人 DefaultNamespaceHandlerreSolver 的 resolve() 方法进行查看。

@Override
public NamespaceHandler resolve(String namespaceUri) {
    Map<String, Object> handlerMappings = getHandlerMappings();
    Object handlerOrClassName = handlerMappings.get(namespaceUri);
    if (handlerOrClassName == null) {
        return null;
    }
    else if (handlerOrClassName instanceof NamespaceHandler) {
        return (NamespaceHandler) handlerOrClassName;
    }
    else {
        String className = (String) handlerOrClassName;
        try {
            Class<?> handlerClass = ClassUtils.forName(className, this.classLoader);
            if (!NamespaceHandler.class.isAssignableFrom(handlerClass)) {
                throw new FatalBeanException("Class [" + className + "] for namespace [" + namespaceUri +
                        "] does not implement the [" + NamespaceHandler.class.getName() + "] interface");
            }
            NamespaceHandler namespaceHandler = (NamespaceHandler) BeanUtils.instantiateClass(handlerClass);
            namespaceHandler.init();
            handlerMappings.put(namespaceUri, namespaceHandler);
            return namespaceHandler;
        }
        catch (ClassNotFoundException ex) {
            throw new FatalBeanException("NamespaceHandler class [" + className + "] for namespace [" +
                    namespaceUri + "] not found", ex);
        }
        catch (LinkageError err) {
            throw new FatalBeanException("Invalid NamespaceHandler class [" + className + "] for namespace [" +
                    namespaceUri + "]: problem with handler class file or dependent class", err);
        }
    }
}