用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 &#169; 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。