Spring源码阅读-- 解析自定义命名空间的标签

在上一篇， Spring源码阅读– IOC容器资源解析 我们分析到使用默认命名空间，即http://www.springframework.org/schema/beans命名空间的标签解析过程。这一篇我们开始探讨一下spring如何处理其它命名空间的xml标签，比如spring扩展的http://www.springframework.org/schema/context、http://www.springframework.org/schema/p和http://www.springframework.org/schema/aop命名空间。

上一篇，我们知道DefaultBeanDefinitionDocumentReader类中的parseBeanDefinitions方法主要事情是区分节点标签是否是默认命名空间的标签。如果是默认命名空间的则调用DefaultBeanDefinitionDocumentReader方法parseDefaultElement处理，否则调用BeanDefinitionParserDelegate 的parseCustomElement方法来处解析自定义命名空间的标签。

//代码片段1
protected void parseBeanDefinitions(Element root, BeanDefinitionParserDelegate delegate) {
    // 检查root节点的命名空间是否为默认命名空间
    // spring配置文件中默认的命名空间为"http://www.springframework.org/schema/beans"
    if (delegate.isDefaultNamespace(root)) {
        NodeList nl = root.getChildNodes();
         // 遍历root节点下的所有子节点
        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 {
                    //没有使用 Spring 默认的 XML 命名空间， 则使用用户自定义的解析规则解析元素节点
                    delegate.parseCustomElement(ele);
                }
            }
        }
    }
    else {
        //Document 的根节点没有使用 Spring 默认的命名空间， 则使用用户自定义的
        delegate.parseCustomElement(root);
    }
}

自定义的命名空间标签会调用BeanDefinitionParserDelegate.parseCustomElement(Element ele)来处理其它命名空间下的元素,源码如下:

//代码片段2
public BeanDefinition parseCustomElement(Element ele) {
    return parseCustomElement(ele, 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));
}

1、NamespaceHandler注册

NamespaceHandler handler = this.readerContext.getNamespaceHandlerResolver().resolve(namespaceUri);根据命名空间查找对应的NamespaceHandler,那么NamespaceHandler何时注册呢？
在Spring源码阅读– IOC容器资源解析的”2.2.1、分析别名注册中心”章节中分析到XmlBeanDefinitionReader在createReaderContext方法中将默认的NamespaceHandlerResolver(命名处理器解析器)传给了ReaderContext，如：

//代码片段3
public XmlReaderContext createReaderContext(Resource resource) {
    return new XmlReaderContext(resource, this.problemReporter, this.eventListener,
            this.sourceExtractor, this, getNamespaceHandlerResolver());
}
public NamespaceHandlerResolver getNamespaceHandlerResolver() {
    if (this.namespaceHandlerResolver == null) {
        this.namespaceHandlerResolver = createDefaultNamespaceHandlerResolver();//创建默认的命名空间处理器解析器
    }
    return this.namespaceHandlerResolver;
}
protected NamespaceHandlerResolver createDefaultNamespaceHandlerResolver() {
    return new DefaultNamespaceHandlerResolver(getResourceLoader().getClassLoader());
}

Spring定义了NamespaceHandlerResolver接口来获取命名空间处理器，并且Spring给出了一个默认的实现，那就是DefaultNamespaceHandlerResolver类，我们来看看这个类的resolve(String namespaceUri)方法

//代码片段4
@Override
public NamespaceHandler resolve(String namespaceUri) {
    //获取所有已经配置的handler映射  
    Map<String, Object> handlerMappings = getHandlerMappings();
    //根据命名空间找到对应的处理器对象或者Class
    Object handlerOrClassName = handlerMappings.get(namespaceUri);
    if (handlerOrClassName == null) {
        return null;
    }
    else if (handlerOrClassName instanceof NamespaceHandler) {
        //是否是NamespaceHandler对象实例，所有的自定义命名空间处理器必须实现NamespaceHandler接口
        //以前已经生成处理器对象，直接返回缓存的处理器对象
        return (NamespaceHandler) handlerOrClassName;
    }
    else {
        //没有做过解析，则返回的是类路径  
        String className = (String) handlerOrClassName;
        try {
            //根据类路径加载处理器Class
            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();
            //以命名空间uri为key值，理器对象为value值，保存到一个map中
            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);
        }   
    }
}

上面代码主要通过调用getHandlerMappings()方法获得NamespaceHandler对象与命名空间URI的映射表，并从这个映射表中取出对象，判断是否已经生成了NamespaceHandler对象。若已生成NamespaceHandler对象，则立即返回该对象，否则生成NamespaceHandler对象，并把它存放到刚才的映射表中，这样下次再获取就不用再生成对象了。那何时建立NamespaceHandler对象与命名空间URI的映射呢？我们继续跟踪getHandlerMappings()方法。

//代码片段5
private Map<String, Object> getHandlerMappings() {
    if (this.handlerMappings == null) {
        synchronized (this) {
            if (this.handlerMappings == null) {
                try {
                    //handlerMappingsLocation默认为"META-INF/spring.handlers"
                    Properties mappings = PropertiesLoaderUtils.loadAllProperties(this.handlerMappingsLocation, this.classLoader);
                    if (logger.isDebugEnabled()) {
                    logger.debug("Loaded NamespaceHandler mappings: " + mappings);
                    }
                    Map<String, Object> handlerMappings = new ConcurrentHashMap<String, Object>(mappings.size());
                    // 把Properties对象中的key-value复制到handlerMappings中
                    CollectionUtils.mergePropertiesIntoMap(mappings, handlerMappings);
                    this.handlerMappings = handlerMappings;
                }
                catch (IOException ex) {
                    throw new IllegalStateException("Unable to load NamespaceHandler mappings from location [" + this.handlerMappingsLocation + "]", ex);
                }
            }
        }
    }
    return this.handlerMappings;
}

上面代码使用PropertiesLoaderUtils.loadAllProperties()从handlerMappingsLocation指定的handlers文件加载命名空间名称和具体NamespaceHandler之间的关联配置。handlerMappingsLocation默认的路径是jar包下的META-INF目录下的spring.handlers文件。

我们看到spring-beans、spring-context、spring-aop、spring-tx、spring-jdbc、 spring-webmvc包下都有spring.handlers文件。我们仅看一下spring-context包的spring.handlers文件内容：

http\://www.springframework.org/schema/context=org.springframework.context.config.ContextNamespaceHandler
http\://www.springframework.org/schema/jee=org.springframework.ejb.config.JeeNamespaceHandler
http\://www.springframework.org/schema/lang=org.springframework.scripting.config.LangNamespaceHandler
http\://www.springframework.org/schema/task=org.springframework.scheduling.config.TaskNamespaceHandler
http\://www.springframework.org/schema/cache=org.springframework.cache.config.CacheNamespaceHandler

由此，当解析到http://www.springframework.org/schema/context命名空间时，PropertiesLoaderUtils.loadAllProperties()就会将以http://www.springframework.org/schema/context为key，org.springframework.context.config.ContextNamespaceHandler处理器类的全限定名作为value存进handlerMappings这个Map中。当第一次调用DefaultNamespaceHandlerResolver类，的resolve(String namespaceUri)方法获取到处理器类的全限定名，再根据处理器类的全限定名生成处理器对象，并把该对象保存进handlerMappings中，这样下一次再获取就不会生成对象了。这样就完成了命名空间处理器注册了。

自定义命名空间的查找如下图

2、自定义命名空间标签的解析

上面分析到所有的自定义命名空间处理器必须实现NamespaceHandler接口，NamespaceHandler接口如下：

public interface NamespaceHandler {

    /**
     * 实例化一个NamespaceHandler对象的后会调用此方法
     */
    void init();

    /**
     * 解析指定的的Element对象，并返回一个BeanDefinition对象。
     */
    BeanDefinition parse(Element element, ParserContext parserContext);

    /**
     * 解析指定的节点，并装饰指定的BeanDefinitionHolder对象，最后返回一个已经装饰的BeanDefinitionHolder对象。
     * 这个方法在parse方法之后被调用
     */
    BeanDefinitionHolder decorate(Node source, BeanDefinitionHolder definition, ParserContext parserContext);

}

找到了自定义命名空间的处理器类全限定名后，会实例化该类对象，然后调用该对象init()方法进行注册具体标签解析器。如命名空间http://www.springframework.org/schema/context 的处理器类org.springframework.context.config.ContextNamespaceHandler的init方法：

public class ContextNamespaceHandler extends NamespaceHandlerSupport {
    @Override
    public void init() {
        // 注册property-placeholder标签的的解析器
        registerBeanDefinitionParser("property-placeholder", new PropertyPlaceholderBeanDefinitionParser());
        registerBeanDefinitionParser("property-override", new PropertyOverrideBeanDefinitionParser());
         注册annotation-config标签的的解析器(注解解析)
        registerBeanDefinitionParser("annotation-config", new AnnotationConfigBeanDefinitionParser());
        // 注册annotation-config标签的的解析器(组件扫描)
        registerBeanDefinitionParser("component-scan", new ComponentScanBeanDefinitionParser());
        registerBeanDefinitionParser("load-time-weaver", new LoadTimeWeaverBeanDefinitionParser());
        registerBeanDefinitionParser("spring-configured", new SpringConfiguredBeanDefinitionParser());
        registerBeanDefinitionParser("mbean-export", new MBeanExportBeanDefinitionParser());
        registerBeanDefinitionParser("mbean-server", new MBeanServerBeanDefinitionParser());
    }
}

ContextNamespaceHandler类init()方法注册各个元素和对应处理类注册到Map<String, BeanDefinitionParser> parsers这个Map中。处理类实现了BeanDefinitionParser接口,该接口提供一个BeanDefinition parse(Element element, ParserContext parserContext);方法。当调用ContextNamespaceHandler对象parse()方法对自定义标签进行解析时，会调用父类NamespaceHandlerSupport的parse()方法:

public BeanDefinition parse(Element element, ParserContext parserContext) {
    //findParserForElement()根据元素名称来查找之前在init()方法中注册的BeanDefinitionParser对象
    //然后调用该对象的parse()方法实际处理元素
    return findParserForElement(element, parserContext).parse(element, parserContext);
}

如spring bean的配置文件里有这样的配置项：<context:property-placeholder location="classpath:jdbc.properties" />,最终调用到PropertyPlaceholderBeanDefinitionParser对象的parse()方法，此方法在父类AbstractBeanDefinitionParser实现：

public final BeanDefinition parse(Element element, ParserContext parserContext) {
    //解析自己内部自定义的标签
    AbstractBeanDefinition definition = parseInternal(element, parserContext);
    if (definition != null && !parserContext.isNested()) {
        try {
            String id = resolveId(element, definition, parserContext);
            if (!StringUtils.hasText(id)) {
                parserContext.getReaderContext().error(
                "Id is required for element '" + parserContext.getDelegate().getLocalName(element)
                        + "' when used as a top-level tag", element);
            }
            String[] aliases = null;
            if (shouldParseNameAsAliases()) {
                String name = element.getAttribute(NAME_ATTRIBUTE);
                if (StringUtils.hasLength(name)) {
                    aliases = StringUtils.trimArrayElements(StringUtils.commaDelimitedListToStringArray(name));
                }
            }
            //生成BeanDefinition对象包装类
            BeanDefinitionHolder holder = new BeanDefinitionHolder(definition, id, aliases);
            //往容器里注册BeanDefinition
            registerBeanDefinition(holder, parserContext.getRegistry());
            if (shouldFireEvents()) {
                BeanComponentDefinition componentDefinition = new BeanComponentDefinition(holder);
                //组件注册完成后，调用后置处理器
                postProcessComponentDefinition(componentDefinition);

                parserContext.registerComponent(componentDefinition);
            }
        }
        catch (BeanDefinitionStoreException ex) {
            parserContext.getReaderContext().error(ex.getMessage(), element);
            return null;
        }
    }
    return definition;
}

parseInternal(element, parserContext);是抽象方法，留给子类实现具体标签解析逻辑，因此最终调用到PropertyPlaceholderBeanDefinitionParser对象的doParse()方法。

protected void doParse(Element element, BeanDefinitionBuilder builder) {
    String location = element.getAttribute("location");
    if (StringUtils.hasLength(location)) {
        String[] locations = StringUtils.commaDelimitedListToStringArray(location);
        builder.addPropertyValue("locations", locations);
    }

    String propertiesRef = element.getAttribute("properties-ref");
    if (StringUtils.hasLength(propertiesRef)) {
        builder.addPropertyReference("properties", propertiesRef);
    }

    String fileEncoding = element.getAttribute("file-encoding");
    if (StringUtils.hasLength(fileEncoding)) {
        builder.addPropertyValue("fileEncoding", fileEncoding);
    }

    String order = element.getAttribute("order");
    if (StringUtils.hasLength(order)) {
        builder.addPropertyValue("order", Integer.valueOf(order));
    }

    builder.addPropertyValue("ignoreResourceNotFound",
            Boolean.valueOf(element.getAttribute("ignore-resource-not-found")));

    builder.addPropertyValue("localOverride",
            Boolean.valueOf(element.getAttribute("local-override")));

    builder.setRole(BeanDefinition.ROLE_INFRASTRUCTURE);
    //省略其他代码
}

这样完成了对自定义标签的解析，返回bean定义(BeanDefinition)对象，接着生成BeanDefinition对象包装类BeanDefinitionHolder，最后往容器里注册BeanDefinition对象。

3、总结

从上面的代码分析，要实现自定义的命名空间标签定义，我们一般进行如下操作：
1. 实现BeanDefinitionParser接口，实现对具体的标签进行解析。（具体的标签一般在XSD文件中的定义，这样编写spring配置文件时，就找到对应标签的约束）
2. 创建自定义命名空间处理器NamespaceHandler，一直直接继承自NamespaceHandlerdSupport，目的是将标签元素和上一步定义的解析器(BeanDefinitionParser)关联起来(注册到Map中)。
3. 在classpath的META-INF/路径下编写spring.handlers,将自定义的命名空间名称与上一步创建的命名空间处理器NamespaceHandler关联起来。