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才会被完全忽略掉。例如：    

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

ibatis的xml配置文件示例：

     ...

    在解析该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();
  }