ibatis配置文件解析过程中对DTD的加载处理

一、背景知识

使用JAXP（Java API for XML Parsing）来解析XML文档，支持基于对象和基于事件的两种解析方式。基于对象的解析，目前只支持W3C DOM解析，基于事件的解析，只有SAX解析模式被支持。

SAX是一种基于事件的解析模式，解析文档的时候，当遇到开始标签，结束标签或字符等，SAX都会产生相应的事件。一个SAX解释器解析XML文档的时候，把文档看作为一个流，依次产生相应的事件报告给已注册的content handler（实现org.xml.sax.ContentHandler接口）；如果有错误，错误会报告给error handler（实现org.xml.sax.ErrorHandler接口）。如果你不注册一个error handler，那你根本不会知道在解析XML文档的时候有没有出错。SAX解析文档时，一个典型的事件被触发的顺序是：startDocument、startElement、characters、endElement、endDocument。startDocument和endDocument仅仅被触发一次。

DOM解析是基于对象的原理，当用DOM解析XML文档时，它会在内存中生成一个树形的结构来表示一个XML文档。树上的每个节点代表着XML文档的一个节点。大部分DOM解析器允许你抽取XML文档的一部分来生成DOM树，而不是把整个XML文档在内存中建立对应的DOM树。

DTD是XML文档的语法。如果一份XML文档声明了DOCTYPE，并且想在解析的时候根据DTD校验文档，那你必须在适当的factory里启用根据DTD校验文档（validation）这个特性。例如：

DocumentBuilderFactory dbfactory = DocumentBuilderFactory.newInstance();
dbfactory.setValidating(true);

或者

SAXParserFactory spfactory = SAXParserFactory.newInstance();
spfactory.setValidating(true);

注意，如果XML文档声明了一个DTD ，即使你不启用校验（validation）这个特性，解析器总是试着去读入这个DTD。
这样做的目的是为了保证XML文档中entity reference被正确的扩展了，否则会导致格式不正确的XML文档，只有在XML文档序言部分的声明中standalone属性被置为true时，外部的DTD才会被完全忽略掉。例如：

<?xml version="1.1" encoding="UTF-8" standalone="yes"?>

二、ibatis配置文件解析过程中对DTD的加载处理
ibatis的xml配置文件示例：

<?xml version="1.0" encoding="GB2312" ?>
<!DOCTYPE sqlMap PUBLIC "-//ibatis.apache.org//DTD SQL Map 2.0//EN" "http://ibatis.apache.org/dtd/sql-map-2.dtd">
<sqlMap namespace="mySpace">
...
</sqlMap>

在解析该xml文档时，需要获取DTD文件，便于进行验证。由于该DTD文件是通过一个远程的URL获取的，这不但会影响文档解析的速度，而且当没有联网的时候，将导致解析失败。那么是否存在一种方法，在本地提供DTD文件，这样在解析文档的时候，只需要访问本地的DTD文件即可，省去了网络的访问过程？ 确实有这样的方法，而且ibatis的代码（以ibatis 2.3.0这个版本为例）在解析其配置文件时，也是这么做的。
ibatis定义了一个类SqlMapClasspathEntityResolver，它负责在解析XML文档时，去加载DTD文件。该类实现了SAX定义的接口：org.xml.sax.EntityResolver。该接口定义如下：

package org.xml.sax;
public interface EntityResolver {
public InputSource resolveEntity(String publicID, String systemID) throws SAXException;
}

这个接口中的唯一方法resolveEntity，提供了获取外部实体引用的方式。SqlMapClasspathEntityResolver的源代码如下：

/**
* Offline entity resolver for the iBATIS DTDs
*/
public class SqlMapClasspathEntityResolver implements EntityResolver {

private static final String SQL_MAP_CONFIG_DTD = "com/ibatis/sqlmap/engine/builder/xml/sql-map-config-2.dtd";
private static final String SQL_MAP_DTD = "com/ibatis/sqlmap/engine/builder/xml/sql-map-2.dtd";

private static final Map doctypeMap = new HashMap();

static {
doctypeMap.put("http://www.ibatis.com/dtd/sql-map-config-2.dtd".toUpperCase(), SQL_MAP_CONFIG_DTD);
doctypeMap.put("http://ibatis.apache.org/dtd/sql-map-config-2.dtd".toUpperCase(), SQL_MAP_CONFIG_DTD);
doctypeMap.put("-//iBATIS.com//DTD SQL Map Config 2.0//EN".toUpperCase(), SQL_MAP_CONFIG_DTD);
doctypeMap.put("-//ibatis.apache.org//DTD SQL Map Config 2.0//EN".toUpperCase(), SQL_MAP_CONFIG_DTD);

doctypeMap.put("http://www.ibatis.com/dtd/sql-map-2.dtd".toUpperCase(), SQL_MAP_DTD);
doctypeMap.put("http://ibatis.apache.org/dtd/sql-map-2.dtd".toUpperCase(), SQL_MAP_DTD);
doctypeMap.put("-//iBATIS.com//DTD SQL Map 2.0//EN".toUpperCase(), SQL_MAP_DTD);
doctypeMap.put("-//ibatis.apache.org//DTD SQL Map 2.0//EN".toUpperCase(), SQL_MAP_DTD);
}

/**
* Converts a public DTD into a local one
*
* @param publicId Unused but required by EntityResolver interface
* @param systemId The DTD that is being requested
* @return The InputSource for the DTD
* @throws SAXException If anything goes wrong
*/
public InputSource resolveEntity(String publicId, String systemId)
throws SAXException {

if (publicId != null) publicId = publicId.toUpperCase();
if (systemId != null) systemId = systemId.toUpperCase();

InputSource source = null;
try {
String path = (String) doctypeMap.get(publicId);
source = getInputSource(path, source);
if (source == null) {
path = (String) doctypeMap.get(systemId);
source = getInputSource(path, source);
}
} catch (Exception e) {
throw new SAXException(e.toString());
}
return source;
}

private InputSource getInputSource(String path, InputSource source) {
if (path != null) {
InputStream in = null;
try {
in = Resources.getResourceAsStream(path);
source = new InputSource(in);
} catch (IOException e) {
// ignore, null is ok
}
}
return source;
}

}

通过源码可以看出，在获取DTD文件的时候，根据映射关系，将远程的url转成本地的DTD文件路径，从而直接从本地jar中获取到DTD文件，而不是通过访问url来获取DTD文件。
ibatis对XML配置文件的解析，是通过com.ibatis.sqlmap.engine.builder.xml.SqlMapConfigParser类的parse方法来完成的。而在构造SqlMapConfigParser对象时，正是通过设置SqlMapClasspathEntityResolver来定位DTD文件的：

public SqlMapConfigParser(XmlConverter sqlMapConfigConv, XmlConverter sqlMapConv) {
super(new Variables());
parser.setValidation(true); // 需要使用DTD文件验证XML是否合法
parser.setEntityResolver(new SqlMapClasspathEntityResolver()); // 用来定位DTD文件

vars.sqlMapConfigConv = sqlMapConfigConv;
vars.sqlMapConv = sqlMapConv;
vars.delegate = new SqlMapExecutorDelegate();
vars.typeHandlerFactory = vars.delegate.getTypeHandlerFactory();
vars.client = new SqlMapClientImpl(vars.delegate);
registerDefaultTypeAliases();
addSqlMapConfigNodelets();
addGlobalPropNodelets();
addSettingsNodelets();
addTypeAliasNodelets();
addTypeHandlerNodelets();
addTransactionManagerNodelets();
addSqlMapNodelets();
addResultObjectFactoryNodelets();
}