用UmlGraph在Javadoc中嵌入UML图表
最近在看《Java Power Tools》，对UmlGraph很感兴趣，于是小研究了下。
UmlGraph可以将由源代码生成的UML图表（这里就是类图）嵌入在javadoc中，这样的好处就是不需要人工维护，每次都是从源代码自动生成。
以下就是一个使用UmlGraph在javadoc生成UML图表的效果图：
在图表上点击相应的类图，则会跳转到对应类的页面，真的很好很强大。
那么，该如何使用UmlGraph呢？
一。下载与安装
UmlGraph官方网站：http://www.umlgraph.org/
现在下载的最新版本为：5.4
下载后解压到任意目录即可，比如：E:/UMLGraph-5.4。
另外，要想使用UmlGraph，还需要安装Graphviz。
Graphviz官网地址：http://www.graphviz.org/
在windows下安装Graphviz比较简单，下载到graphviz-2.26.3.msi（目前的最新版本），双击，一步步安装就行。
在linux下安装Graphviz稍显复杂，具体的安装步骤请参看：linux下graphviz的安装 。
二。ant配置
的在ant中使用UmlGraph很方便，只需要在<javadoc>任务中嵌入<doclet>标签，并使用<param>标签指定参数，以下是一个示例：
<!-- 生成javadoc -->
<target name="javadoc" depends="compile" description="javadoc run">
<echo message="javadoc run" />
<delete dir="${reports.javadoc.dir}" />
<mkdir dir="${reports.javadoc.dir}" />
<javadoc sourcepath="${src.dir}" destdir="${reports.javadoc.dir}" encoding="UTF-8" charset="UTF-8" docencoding="UTF-8" author="true" version="true" use="true" access="private" linksource="true" windowtitle="${ant.project.name} API">
<classpath>
<path refid="compile.classpath" />
<pathelement path="${compile.classes.dir}" />
</classpath>
<doctitle>
<![CDATA[<H1>${ant.project.name}</H1>]]></doctitle>
<bottom>
<![CDATA[<i>Copyright © 2010 All Rights Reseverd.</i>]]></bottom>
<doclet name="org.umlgraph.doclet.UmlGraphDoc" path="E:/UMLGraph-5.4/UmlGraph.jar">
<param name="-inferrel" />
<param name="-inferdep" />
<!-- 不显示详细日志信息，出问题时可以注释掉 -->
<param name="-quiet" />
<param name="-hide" value="java.*" />
<param name="-collpackages" value="java.util.*" />
<param name="-postfixpackage" />
<param name="-nodefontsize" value="9" />
<param name="-nodefontpackagesize" value="7" />
<param name="-qualify" />
<param name="-attributes" />
<param name="-operations" />
<param name="-enumerations" />
<param name="-enumconstants" />
<!-- 检索生成的html页面时使用的编码，默认为ISO-8859-1，
在向页面中插入图表时需要进行正则匹配，如果要匹配中文需要将其设置为UTF-8
<param name="-outputencoding" value="UTF-8" />
-->
<param name="-types" />
<param name="-visibility" />
<!-- 提供外部javadoc地址，可以直接导航过去 -->
<param name="-link" value="http://download.oracle.com/javaee/6/api/" />
<param name="-link" value="http://static.springsource.org/spring/docs/2.5.x/api/" />
<param name="-link" value="http://docs.jboss.org/hibernate/core/3.6/javadocs/" />
<param name="-link" value="http://logging.apache.org/log4j/1.2/apidocs/" />
</doclet>
</javadoc>
<echo message="javadoc completed!" />
</target>
以上<param>配置的比较完整了，可以在javadoc中嵌入一个相当完整和详细的UML图表。
三。问题
使用过程中发现这样的问题，就是用ant生成javadoc时，只能在package页中嵌入UNL图表，而每一个具体的类页面中却不能实现嵌入，这是为什么呢？
于是乎，注释掉quiet参数查看详细日志
<!-- 是否显示详细日志信息，出问题时可以打开进行查看 <param name="-quiet" /> -->
结果发现，日志打印如下信息
[javadoc] Warning, could not find a line that matches the pattern '(Class|Interface|Enum) MultipartFileValidator.*'. [javadoc] Class diagram reference not inserted
意思是没有成功进行正则匹配，导致图表没有插入。这就比较奇怪，为什么插入包图表时没有问题呢？
ok，还是看下源码吧，问题出在org.umlgraph.doclet.UmlGraphDoc中。
图表插入包中的正则匹配规则是
Pattern.compile("</H2>")
而图表插入类中的匹配规则是
Pattern.compile("(Class|Interface|Enum) " + classDoc.name() +".*")
因为javadoc是使用UTF-8编码生成的，所以在html页面中“Class”变成了“类”，所以匹配不上。
清楚了这一点后对源码做了如下修改：
方法一：
Pattern.compile("(Class|Interface|Enum|类|接口|枚举) " + classDoc.name() +".*")
不过这时doclet中的参数outputencoding要设置为UTF-8:
<param name="-outputencoding" value="UTF-8" />
方法二：
Pattern.compile(".*" + classDoc.name() +"</H2>.*")
这与包匹配规则类似，不过确实很好用，推荐使用第二种方式进行修改。
ok，重新编译，打jar包，附件中为使用第二种方式打的jar包。
补充说明一下：编译UmlGraph需要用到JAVA_HOME/lib下的tools.jar。