XDoclet是一个代码生成工具，它可以把你从Java开发过程中繁重的重复劳动中解脱出来。XDoclet可以让你的应用系统开发的更加快速，而你只要付比原先更少的努力。你可以把你手头上的冗长而又必需的代码交给它帮你完成，你可以逃脱“deployment descriptor地狱”，你还可以使你的应用系统更加易于管理。而你所要做的，只不过是在你的注释里，多加一些类javadoc属性。然后，你会惊讶于XDoclet为了做到的一切。
讨论XDoclet，有一点比较容易产生混淆，那就是XDoclet不但是一系统的代码生成应用程序，而且它本身还是一个代码生成框架。虽然每个应用系统的细节千变万化（比如EJB代码生成和Struts代码生成是不一样的，而JMX代码生成又是另一番景象），但这些代码生成的核心概念和用法却是类似的。
在这一章里，我们将会看到渗透到所有XDoclet代码生成程序当中的XDoclet框架基础概念。但在之前，我们先从一个例子入手。
2.1 XDoclet in action
每一个程序员都会认识到，他们的程序永远也不会完成。总会有另一些的功能需要添加，另一些的BUG需要修正，或者需要不断的进行重构。所以，在代码里添加注释，提醒自己（或者其他的程序员）有哪些任务需要完成已成为一个共识。
如何来跟踪这些任务是否完成了呢？理想情况下，你会收集整理出来一个TODO任务列表。在这方面，XDoclet提供了一个强大的TODO生成器，来帮助你完成这个任务。这是一个把XDoclet引入项目的好机会。
2.1.1 一个公共的任务
假设你正在开发一个使用了勺子的类。
public class Matrix {
// TODO ? 需要处理当没有勺子的情况
public void reload() {
// ...
Spoon spoon = getSpoon();
// ...
}
}
理想情况下，你在下一次阅读这段代码的时候，你会处理这个“空勺子”(null spoon)的问题。但如果你过了很久才回来看这段代码，你还会记得在这个类里还有一些工作要做吗？当然，你可以在你的源码里全局搜索TODO，甚至你的集成开发环境有一个内建的TODO列表支持。但如果你想把任务所在的类和方法也标注出来的话，XDoclet可以是另一种选择。XDoclet可以为你的项目生成一个TODO报表。
2.1.2 添加XDoclet标签
为了把你的TODO项目转换成另一种更加正式的格式，你需要对代码进行一些细微的改动。如下所示：
public class Matrix {
/** @todo 需要处理当没有勺子的情况 */
public void reload() {
// ...
}
}
这里加入了一个XDoclet需要的类javadoc标签。XDoclet会使用这些标签标记的信息，以及在这种情况下标签所处的类和方法，来生成TODO报表。
2.1.3 与Ant集成
要生成TODO报表，你需要确保在你的机器上正确安装了XDoclet。
在Ant任务里，最少要包含一个目标（例如init目标）定义<documentdoclet>任务，这是一个Ant自定义任务，例如：
<taskdef name=”documentdoclet”
classname=”xdoclet.modules.doc.DocumentDocletTask”
classname=”xdoclet.lib.path” />
这个<documentdoclet>任务是XDoclet核心代码生成应用程序中的一个。
现在，你可以在Ant构建文件中加入一个todo目标调用这个任务来生成TODO报表，如：
<target name=”todo” depends=”init”>
<documentdoclet destdir=”todo”>
<fileset dir=”${dir.src}”>
<include name=”**/*.java” />
</fileset>
<info/>
</documentdoclet>
</target>
<info>子任务会遍历你的源文件，查找todo标签，并在todo子目录下生成HTML格式的TODO报表。
2.1.4 创建一个更加职业化的TODO报表
XDoclet生成的TODO报表可以有一个更加职业化的外表。报表会列出一个概览，显示在哪个包哪个类里有todo项（以及todo项的个数）。Todo项可以跟在方法、类和域上，从报表上可以清楚的区别它们。类级别的todo项会标注class，方法级别的todo项会在方法签名上标注M。构造函数和域相关的todo项也会进行相似的标注。
这个任务看起来很简单，但考虑到你所需要做的只是在注释上添加一些格式化的@todo标签，相对于那种只有人才可以理解的无格式的松散的注释，这种标签是机器可读的，也更容易编程处理。生成的输出也更容易阅读并且更加的商业化。
2.2 任务和子任务
生成todo报表，只是XDoclet可以完成的事情当中的冰山一角。当初，XDoclet因为可以自动生成EJB繁杂的接口和布署描述文件而声名鹊起。然而，现在的XDoclet已经发展成了一个全功能的、面向属性的代码生成框架。J2EE代码生成只是XDoclet的一个应用方面，它可以完成的任务已经远远超越了J2EE和项目文档的生成。
2.2.1 XDoclet 任务
到现在为止，我们一直在讨论使用XDoclet生成代码，但事实上，更确切的说法应该是，我们使用XDoclet的一个特定的任务来生成代码，比如<ejbdoclet>。每一个XDoclet任务关注于一个特定的领域，并提供这个领域的丰富的代码生成工具。
[定义：任务（Tasks）是XDoclet里可用的代码生成应用程序的高层概念。]
在XDoclet里，目前已有如下所示的七个核心任务。
<ejbdoclet>：面向EJB领域，生成EJB、工具类和布署描述符。
<webdoclet>：面向Web开发，生成serlvet、自定义标签库和web框架文件。
<hibernatedoclet>：Hibernate持续，配置文件、Mbeans
<jdodoclet>：JDO，元数据，vender configuration
<jmxdoclet>：JMX，MBean接口，mlets，配置文件。
<doclet>：使用用户自定义模板来生成代码。
<documentdoclet>：生成项目文件（例如todo列报表）
这其中，<ejbdoclet>最常用，并且很多项目也仅仅使用XDoclet来进行EJB代码生成。<webdoclet>是其次一个常用的代码生成任务。当然，在一个项目中同时使用几个XDoclet任务是可能的（并且也是推荐的），但在这些任务之间是完全独立的，它们彼此之间并不能进行直接的交流。
2.2.2 XDoclet子任务
XDoclet的任务是领域相关的，而在某个特定领域的XDoclet任务，又由许许多多紧密耦合在一起的子任务组成的，这些子任务每个都仅仅执行一个非常特定和简单的代码生成任务。
[定义：子任务（subtasks）是由任务提供的单目标的代码生成过程]
任务提供子任务执行时的上下文，并且把这些相关的子任务组织管理了起来。任务会依赖这些子任务来生成代码。在一个任务当中调用多个子任务来协同完成各种各样比较大型的代码生成任务是非常常见的。比如，在开发EJB时，你可能想要为每一个bean生成一个home接口，一个remote接口以及ejb-jar.xml布署描述符文件。这就是在<ejbdoclet>任务的上下文环境中的三个独立的代码生成子任务。
子任务可以随意的组合排列，以满足项目代码生成的需要。某个XDoclet任务包含的子任务经常会共享功能和在源文件中使用相同的XDoclet标签。这意味着当你开始一个任务的时候，你可以很容易的集成进一个相关的子任务，而不需要很大的改动。
子任务交互
让我们以<ejbdoclet>任务为例，看一下相关的子任务之间是如何进行关联的。假设你正在开发一个CMP（容器管理持久化）实体Bean。你想要使用一些<ejbdoclet>的子任务：
?<deploymentdescriptor>：生成ejb-jar.xml布署描述符文件。
?<localhomeinterface>：生成local home接口。
?<localinterface>：生成local接口。
在执行如上子任务的时候，你需要标记出你的实体Bean的CMP域。当你发布你的bean的时候，你还需要在开发商相关的布署描述符中提供某个特定的关系数据库中的特定表和列与你的CMP实体Bean的映射关系。XDoclet可以让你在原先已存在的CMP XDoclet属性基础上再加上一些关系映射属性，然后，你就可以在任务中加入一个开发商相关的子任务（例如<jboss>或者<weblogic>）来生成布署描述符文件。XDoclet提供了几乎所有的应用服务器的支持，你只需要一些初始化的小改动，就可以进行这些应用服务器相关的代码生成了。
但那只是冰山一角。你还可以使用<entitycmp>子任务为为你的bean生成一个实体bean接口的实现子类。如果你使用<valueobject>子任务来为了你的bean生成值对象，<entityemp>子任务还会为你的值对象生成方法的实现代码。
觉得不可思议了吧。可惜XDoclet没有提供<cupofcoffee>子任务，要不然我们可以喝杯咖啡，休息一下啦。
这里不是想向你介绍<ejbdoclet>所有的子任务或者<ejbdoclet>可以完成的所有代码生成功能，而仅仅是想向你展示一下任务的子任务之间是如何工作在一起的。一旦你开始并熟悉了一个XDoclet 子任务，熟悉另一个子任务会变得非常简单- 那种每个子任务都是孤立的相比，使用这种可以相互协作的子任务，开发成本会显著的降低，效果也更加的立竿见影。
2.3 使用Ant执行任务
XDoclet“嫁”给了Ant。XDoclet任务就是Ant的自定义任务，除此以外，没有其他运行XDoclet任务的方法。所幸的是，Ant已经成为了Java构建工具事实上的标准，所以这不算什么限制。事实上，反过来，XDoclet与Ant的这种“亲密”关系使得XDoclet可以参与到任何Ant构建过程当中去。
2.3.1 声明任务
XDoclet并没有和Ant一起发布，所以如果你想要使用XDoclet的话，就需要单独的下载和安装。在使用任何一个XDoclet的任务之前，你首先需要在使用Ant的<taskdef>任务来声明它。例如：
<taskdef name=”ejbdoclet”
classname=”xdoclet.modules.ejb.EjbDocletTask”
classpathref=”xdoclet.lib.path”/>
如果你熟悉Ant的话，你就会知道这段代码是告诉Ant加载<ejbdoclet>的任务定义。当然，你也可以以你喜欢的任何方式来命名这个自定义任务，但最好还是遵守标准的命名规律以免发生混淆。classname和classpathref属性告诉Ant到哪里去找实现这个自定义任务的XDoclet类。如果你想使用其他的XDoclet任务，就必须要类似这样首先声明这个任务。
一般共通的做法是，把所有需要使用的XDoclet任务都放在Ant的一个目标里声明，这样在其他的目标里如果需要使用这些任务，只要depends这个任务就可以了。你可能已经在Ant的构建文件里包含了init目标，这就是放置XDoclet任务声明的好地方（当然如果你没有，你也可以建一个）。下面的例子就是在一个init目标里加入了<ejbdoclet>和<webdoclet>的声明：
<target name=”init”>
<taskdef name=”documentdoclet”
classname=”xdoclet.modules.doc.DocumentDocletTask”
classpathref=”xdoclet.lib.path” />
<taskdef name=”ejbdoclet”
classname=”xdoclet.modules.ejb.EjbDocletTask”
classpathref=”xdoclet.lib.path” />
<taskdef name=”webdoclet”
classname=”xdoclet.modules.web.WebDocletTask”
classpathref=”xdoclet.lib.path” />
</target>
现在，任务声明好了，XDoclet“整装待发”。
2.3.2 使用任务
你可以在任何目标里使用声明好的任务。在任务的上下文环境里，可以调动相关的子任务。让我们看一个例子，这个例子调用了<ejbdoclet>任务。不要担心看不懂语法的细节，现在你只需要关心一些基础概念就可以了。
<target name=”generateEjb” depends=”init”>
<ejbdoclet destdir=”${gen.src.dir}”>
<fileset dir=”${src.dir}”>
<include name=”**/*Bean.java”/>
</fileset>
<deploymentdescriptor destdir=”${ejb.deployment.dir}”/>
<homeinterface/>
<remoteinterface/>
<localinterface/>
<localhomeinterface/>
</ejbdoclet>
</target>
把任务想像成一个子程序运行时需要的一个配置环境（记住，子任务才是真正进行代码生成工作的）。当调用一个子任务时，子任务从任务继承上下文环境，当然，你也可以根据需要随意的覆盖这些值。在上面的例子里，因为<deploymentdescriptor>子任务生成的布署描述符文件和其他生成各种接口的子任务生成的Java源文件需要放在不同的位置，所以覆盖了destdir的属性值。布署描述符文件需要放在一个在打包EJB JAR文件的时候可以容易包含进来的地方，而生成的Java代码则需要放置在一个可以调用Java编译器进行编译的地方。需要这些子任务之间是紧密关联的，但只要你需要，你可以有足够的自主权控制任务的生成环境。
<fileset>属性同样被应用到所有的子任务。这是一个Ant的复杂类型（相对于文本和数值的简单类型），所以以子元素的方式在任务中声明。不要把它和子任务混为一谈。当然，如果你想在某个子任务中另外指定一个不同的输入文件集，你也可以在这个子任务中放置一个<fileset>子元素来覆盖它。
子任务的可配置选项远远不止这些。我们会在下一章继续介绍所有的任务和子任务，以及常用的配置选项。
2.4 用属性标注你的代码
可重用的代码生成系统需要输入来生成感兴趣的输出。一个解析器生成器也需要一个语言描述来解析生成解析器。一个商务对象代码生成器需要领域模型来知道要生成哪些商务对象。XDoclet则需要Java源文件做为输出来生成相关的类或者布署/配置文件。
然而，源文件可能并没有提供代码生成所需要的所有信息。考虑一个基于servlet的应用，当你想生成web.xml文件的时候，servlet源文件仅可以提供类名和适当的servlet接口方法。其他的信息比如URI pattern映射、servlet需要的初始化参数等信息并没有涵盖。显而易见，如果class并没有提供这些信息给你，你就需要自己手动在web.xml文件时填写这些信息。
XDoclet当然也不会知道这些信息。幸运的是，解决方法很简单。如果所需信息在源文件时没有提供，那就提供它，做法就是在源文件里加入一些XDoclet属性。XDoclet解析源文件，提取这些属性，并把它们传递给模板，模板使用这些信息生成代码。
2.4.1 剖析属性
XDoclet属性其实就是javadoc的扩展。它们在外表上和使用上都有javadoc属性一样，可以放置在javadoc文档注释里。文档注释以/**开始，*/结尾。下面是一个简单的例子：
/**
* 这是一段javadoc注释。
* 注释可以被分解成多行，每一行都以星号开始。
*/
在注释里的所有文本都被视为javadoc注释，并且都能够被XDoclet访问到。注释块一般都与Java源文件中的某个实体有关，并紧跟在这个实体的前面。没有紧跟实体的注释块将不会被处理。类（或者接口）可以有注释块，方法和域也可以有自己的注释块，比如：
/**
* 类注释块
*/
public class SomeClass {
/** 域注释块 */
private int id;
/**
* 构造函数注释块
*/
public SomeClass() {
// ...
}
/**
* 方法注释块
*/
public int getId() {
return id;
}
}
注释块分成两部分：描述部分和标签部分。当遇到第一个javadoc标签时，标签部分开始。Javadoc标签也分成两部分：标签名和标签描述。标签描述是可选的，并且可以多行。例如：
/**
* 这是描述部分
* @tag1 标签部分从这里开始
* @tag2
* @tag3 前面一个标签没有标签描述。
* 这个标签有多行标签描述。
*/
XDoclet使用参数化标签扩展了javadoc标签。在XDoclet里，你可以在javadoc标签的标签描述部分加入name=”value”参数。这个微小的改动大大增强了javadoc标签的表达能力，使得javadoc标签可以用来描述复杂的元数据。下面的代码显示了使用XDoclet属性描述实体Bean方法：
/**
* @ejb.interface-method
* @ejb.relation
* name=”blog-entries”
* role-name=”blog-has-entries”
* @ejb.value-object
* compose=”com.xdocletbook.blog.value.EntryValue”
* compose-name=”Entry”
* members=”com.xdocletbook.blog.interfaces.EntryLocal”
* members-name=”Entries”
* relation=”external”
* type=”java.util.Set”
*/
public abstract Set getEntries();
参数化标签允许组合逻辑上相关联的属性。你可以加入描述这个类的元信息，使得这个类的信息足够生成代码。另外，程序员借由阅读这样的元信息，可以很快的理解这个类是如何使用的。（如果这个例子上的元信息你看不懂，不要担心，在第4章里，我们会学到EJB相关的标签以及它们的涵意。）
另外，请注意上面的例子中，所有的标签名都以ejb开头。XDoclet使用namespace.tagname的方式给标签提供了一个命名空间。这样做除了可以跟javadoc区别开来以外，还可以把任务相关的标签组织起来，以免任务之间的标签产生混淆。
2.5 代码生成模式
XDoclet是一种基于模板的代码生成引擎。从高层视图上来看，输出文件其实就是由解析执行各式各样的模板生成出来的。如果你理解了模板以及它所执行的上下文环境，就可以确切的认识到，XDoclet可以生成什么，不可以生成什么。如果你正在评估XDoclet平台，理解这些概念是非常重要的。要不然，你可能会错过XDoclet的许多强大的功能，也可能会被XDoclet的一些限制感到迷惑。
XDoclet运行在在Ant构建文件环境中，它提供了Ant自定义任务和子任务来与XDoclet引擎交互。任务是子任务的容器，子任务负责执行代码生成。子任务调用模板。模板提供了你将生成代码的饼干模子。XDoclet解析输入的源文件，提取出源文件中的XDoclet属性元数据，再把这些数据提供给模板，驱动模板执行。除此之外，模板还可以提供合并点(merge points)，允许用户插入一些模板片断(合并文件merge files)来根据需要定制代码生成。
2.5.1 模板基础
XDoclet使用代码模板来生成代码。模板(template)是你想生成文件的原型。模板里使用一些XML标签来指导模板引擎如何根据输入类以及它们的元数据来调整代码的生成。
[定义：模板(template)是生成代码或描述文件的抽象模视图。当模板被解析的时候，指定的细节信息会被填入。]
模板一般情况下会有一个执行环境。模板可能应用在一个类环境(转换生成transform generation)，也有可能应用在一个全局环境(聚集生成aggregate generation)。转换生成和聚集生成是XDoclet的两种类型的任务模式，理解它们之间的区别对于理解XDoclet是非常重要的。
当你使用XDoclet生成布置描述符文件时，你使用的是聚集生成。布置描述符文件并不仅仅只与一个类相关，相反，它需要从多个类里聚集信息到一个输入文件。在这种生成模式里，解析一次模板只会生成一个输出文件，不管有多少个输入文件。
在转换生成模式里，模板遇到每一个源文件就会解析一次，根据该文件类的上下文环境生成输出。这种生成模式会为每一个输入文件生成一个输出文件。
转换生成模式的一个很好的例子是生成EJB的local和remote接口。显然，接口是和Bean类一一相关的。从每一个类里提取信息(类以及它的方法、域、接口以及XDoclet属性等信息)转换出接口。除此以外，不需要其他的信息。
从实现里提取出接口似乎有点反向。如果你手写程序的话，一般来说会先定义一个接口，然后再写一个类来关现它。但XDoclet做不到，XDoclet不可能帮你实现一个已有接口，因为它不可能帮你生成你的业务逻辑。当然，如果业务逻辑可以从接口本身得到(比如JavaBean的get/set访问器)或者使用XDoclet属性声明好，那么生成业务逻辑代码来实现一个接口也不是不可能。但一般情况下，这样做不太现实。相比而言，提供一个实现，并描述接口与这个实现之间的关联就容易多了。
聚集生成和转换生成主要区别在它们的环境信息上。即使一个代码生成任务中生成一个Java文件，一般也不常用聚集生成，因为生成一个Java类还需要一些重要信息如类所处的包以及你想生成的类名，在这种环境下是无法提供的。如果一定要使用聚集生成的话，那就需要在另一个单独的地方提供好配置信息了。
2.5.2 模板标签
在还没见到模板长啥样子之前，我们已经比较深入的认识它了。那模板文件究竟长啥样子呢？它有点像JSP文件。它们都包含文件和XML标签，生成输出文件时XML标签会被解析，然后生成文本并显示在XML标签所处的位置上。除了以XDt为命名空间打头的XML标签会被XDoclet引擎解析以外，其余的XML标签XDoclet会忽略不管。下面的代码片断显示了XDoclet模板的“经典造型”：
public class
<XDtClass:classOf><XDtEjbFacade:remoteFacadeClass/></XDtClass:classOf>
Extends Observabe {
static <XDtClass:classOf><XDtEjbFacade:remoteFacadeClass/></XDtClass:classOf>
_instance = null;
public static <XDtClass:classOf><XDtEjbFacade:remoteFacadeClass/></XDtClassOf>
getInstance() {
if (_instance == null) {
_instance =
new <XDtClass:classOf><XDtEjbFacade:remoteFacadeClass/>
</XDtClass:classOf>();
｝
return _instance;
}
}
研究一下这个模板，你会发现，它生成的是一个类定义。这个类里定义了一个静态变量instance，并且使用一个静态方法来控制这个静态文件的访问。借助Java语法，你可以很容易的推断出那些XDoclet模板标签的目录是生成类名，虽然对于这个标签如何工作你还并不是很了解。
即使你从没打算过要自己写模板，但理解模板是如何被解析运行的还是很有必要的。迟早你会调用到一个运行失败的XDoclet任务，没有产生你所期望的输出，那么最快捷的找出原因的方法就是直接检查模板文件，看看是哪里出了问题。
让我们看一下生成静态域定义的片断：
static <XDtClass:classOf><XDtEjbFacade:remoteFacadeClass/></XDtClass:classOf>
_instance = null;
在XDoclet的眼里，这段模板代码很简单，那就是：
static <tag/> _instance = null;
XDoclet解析执行标签，如果有输出的话，把输入置回到文本里去。有些标签会执行一些运算，把输出放回到一个流里。这样的标签称之为内容标签(content tags)，因为它们产生内容。
另一种类型的标签称之为BODY标签。BODY标签在开始和结束标签之间存在文本。而BODY标签强大就强大在这些文本自己也可以是一断可以由外围标签解析的模板片断。比如在上面的例子里，XDtClass:classOf标签，它们的内容就是模板片断：
<XDtEjbFacade:remoteFacadeClass/>
classOf标签解析这段模板，提取出全限制的内容，然后剃除前面的包面，只输出类名。BODY标签并不总是会解析它的内容，在做这件事之前，它们会事先检查一些外部判断条件(比如检查检查你正在生成的是一个接口还是一个类)。这里标标签称之为条件标签(conditional tags)。还有一些BODY标签提供类似迭代的功能，它的内容会被解析多次。比如一个标签针对类里的每一个方法解析一次内容。
XDoclet标签提供了许多高层次的代码生成功能，但是有时候，它们可能显得不够灵活，或者表达能力满足不了你的需要。这时候，相对于另外开发一套通用功能的模板引擎相比，你可以选择扩展XDoclet模板引擎。你可以使用更具表述能力、功能更加强大的Java平台开发你自己的一套标签。
2.6 使用合并定制
代码生成系统之所以使用的不多，主要原因就在于它们往往只能生成一些死板的、不够灵活的代码。大多数代码生成系统不允许你改动它们生成的代码；如果，如果这个系统不够灵活，你所能做到的最好的扩展就是应用继承扩展生成的代码，或者使用一些共通的设计模式(比如Proxy和Adaptor)来满足你的需要。无论如此，这都不是产生你想生成的代码的好办法。代码生成器最好能做到所生成即所得WYGIWYG(what you generate is what you get)，来取代你需要花费大量的时间来粉饰生成出来的并不满足要求的代码。所以，对于代码生成器来说，支持灵活的定制，是生成能够完全满足要求的代码的前提条件。
XDoclet通过合并点(merge points)支持定制??合并点是在模板文件定义里允许运行时插入定制代码的地方。有时候，合并点甚至可以影响到全局代码的生成，不但允许你添加一些定制内容，还可以从根本上改变将要生成出来的东西。
[定义：合并点(Merge points)是模板预先定义的允许你在代码生成的运行时加入定制内容的扩展点]
让我们研究一段从XDoclet源代码里摘取出来的模板代码。在为实体Bean生成主键的模板末尾，定义了这样一个合并点：
<XDtMerge:merge file=”entitypk-custom.xdt”></XDtMerge:merge>
如果你在你的merge目录下创建了一个名为entitypk-custom.xdt文件，那么这个模板文件的内容将会在这个合并点被包含进来。你的定制可以执行高层模板可以执行的所有强大功能，可以进行所有模板可以进行的运算(包括定义自定义标签，定义它们自己的合并点)。
上面的这种合并点，为所有的类环境使用了同一个文件。当然，也可以为每一个类环境使用不同的合并文件。如果你不想定制全部的类文件，或者你不想为了某些改动而重写模板的时候，这会很有用。不管动机是什么，逐类的合并点很容易识别出来：他们会在名字里包含一个XDoclet的逐类标记{0}。这里有一个生成ejb-jar.xml文件里的安全角色引用的例子：
<XDtMerge:merge file=”ejb-sec-rolerefs-{0}.xml”>
<XDtClass:forAllClassTags tagName=”ejb:security-role-ref”>
<security-role-ref>
<role-name>
<XDtClass:classTagValue
tagName=”ejb:security-roleref”
paramName=”role-name”/>
</role-name>
<role-link>
<XDtClass:classTagValue
tagName=”ejb:security-roleref”
paramName=”role-link”/>
</role-link>
</security-role-ref>
</XDtClass:forAllClassTags>
</XDtMerge:merge>
这段模板会遍历工程里的所有Bean。对于每一个Bean，XDoclet先从Bean的文件名里提取出Bean名，然后替换{0}，再根据替换后的文件名去寻找合并文件。例如，如果你有一个名为BlogFacadeBean的Bean，XDoclet会尝试寻找一个名为ejb-src-rolerefs-BlogFacade.xml的合并文件。
如果找不到这个合并文件，则这个<merge>标签的内容模板会被解析。这意味着合并点不仅可以提供定制内容，还可以在一个模板文件里定义一个替换点，当定制内容不存在的时候使用替换点里的内容。不是所有的XDoclet任务都提供了有替换内容的合并点，一般来说，它们更倾向于只提供一个简单的合并点，仅仅当合并文件存在的时候解析并导入合并文件的内容。这取决于任务的开发者觉得哪种合并点更符合他的要求。
还有一点没有介绍到的是XDoclet如何定位合并文件，每一个XDoclet任务或者子任务都会提供一个mergeDir属性，这个属性用于设置你存放合并文件的目录。