????使用xdoclet，你能够在j2ee环境下更加高效地工作，你所看到的bean以及bean之间的关系将更加简单，许多繁杂的事情将远离你的ejb开发过程。本文讨论的是如何使用和扩展xdoclet。在这篇文章中，我们将创建一个使用javadoc标记的会话bean，然后利用xdoclet处理这个bean。
　　
　　
　　一、什么是xdoclet
　　
　　
　　xdoclet从rickard oberg创建的ejbdoclet工具发展而来，它的设想很简单：避免为每个ejb提供多个文件，而是从单一bean类文件中提供组件需要的所有信息。那么，这是如何实现的呢？java没有.net吹嘘的“属性”，但java有javadoc标记。我们可以把一个特殊的@标记放入javadoc注释，然后让一个doclet工具处理这些标记。由工具为指定的bean生成合适的xml描述器文件和接口文件。xdoclet建立在ejbdoclet思想的基础上，但适用范围不再局限于ejb。现在，我们已经可以用xdoclet生成web服务、web应用描述器，甚至还可以对它进行扩展，满足自己的特殊需要。
　　
　　
　　@标记有一个标准的格式，包含一个“名称空间”以及一个属于该名称空间的“标记名称”。标记的属性以“名字=值”的形式在标记中指定。下面是一个例子：
　　
　　
　　
　　/**
　　
　　* @namespace:tag name="value" name2="value2" ...
　　
　　*/
　　
　　
　　
　　
　　
　　当前可用的名称空间包括：
　　
　　
　　
　　ejb
　　
　　标准的ejb信息（非厂商私有的信息）
　　
　　jboss
　　
　　面向jboss应用服务器的信息。
　　
　　weblogic
　　
　　面向bea weblogic应用服务器的信息。
　　
　　websphere
　　
　　面向ibm websphere应用服务器的信息。
　　
　　orion
　　
　　面向orion应用服务器（oracle）的信息。
　　
　　castor
　　
　　为castor框架生成映射信息。
　　
　　mvcsoft
　　
　　为mvcsoft ejb 2.0持久化管理器生成文件。
　　
　　soap
　　
　　生成soap描述器。
　　
　　struts
　　
　　生成struts-config.xml。
　　
　　web
　　
　　为web应用生成web.xml配置文件。
　　
　　jsp
　　
　　生成标记库扩展描述器信息。
　　
　　从上面的清单可以看出，除了ejb之外，xdoclet还提供了许多其它方面的支持（因此它的名字也从ejbdoclet变成了xdcolet）。
　　
　　二、用javadoc标记标注会话bean
　　
　　
　　前面我们讨论了xdoclet工具的基本情况，下面来看一个实例。我们从一个会话ejb开始。这个ejb是xbeans框架的一部分，但对于本文来说，bean有什么样的功能其实无关紧要。我们关心的是如何在bean类的基础上，用javadoc标记进行适当的标注，然后用xdoclet生成我们需要的各种文件。
　　
　　
　　receiverbean.java文件包含了一个documentready(document doc)方法，这个方法接收一个dom文档并把它传递给链上面的下一个xbean。
　　
　　
　　2.1 在类这一级上的定义
　　
　　
　　在类这一层次上，我们必须定义：
　　
　　
　　
　　声明bean的类型，本例是无状态会话bean。
　　
　　jndi名称。
　　
　　环境变量。
　　
　　面向厂商的信息（例如weblogic 缓冲池信息）。
　　
　　2.1.1 @ejb:bean标记
　　
　　
　　该标记唯一必需的属性是把bean的名字告诉xdoclet。此外，我们还将定义bean的类型、jndi名称和显示的名称（display-name）：
　　
　　
　　
　　/**
　　
　　* this is the ejb receiver xbean
　　
　　*
　　
　　* @ejb:bean type="stateless"
　　
　　* name="ejbreceiver"
　　
　　* jndi-name="org.xbeans.ejb.receiver.receiver"
　　
　　* display-name="ejb receiver xbean"
　　
　　*
　　
　　* ... 其他javadoc标记 ...
　　
　　*/
　　
　　public class receiverbean implements sessionbean, domsource {
　　
　　
　　
　　
　　
　　ejb:bean标记最常用的属性是：
　　
　　
　　
　　name
　　
　　ejb的名字（用于描述器）。
　　
　　type
　　
　　定义bean的类型。对于会话bean，bean的类型是stateful或者stateless；对于实体bean，它是cmp或bmp。
　　
　　jndi-name
　　
　　提供bean的jndi名字，它将被用于厂商私有的部署描述器（用于远程接口）。
　　
　　local-jndi-name
　　
　　与jndi-name相同，但用于本地接口。
　　
　　view-type
　　
　　表示应当支持哪一种bean的“视图”。可以是remote或local，或者both。
　　
　　要查看所有标记的完整说明，请访问xdoclet的文档。
　　
　　
　　2.1.2 @ejb:env-entry标记
　　
　　
　　这个标记定义了将在jndi中通过java:comp/env上下文配置的环境变量。下面我们将定义一个环境变量，bean用它来查找链上面的下一个xbean：
　　
　　
　　
　　/**
　　
　　* this is the ejb receiver xbean
　　
　　*
　　
　　* ... 其他javadoc标记 ...
　　
　　*
　　
　　* @ejb:env-entry name="channelbean" type="java.lang.string"
　　
　　* value="com.your.channelbean"
　　
　　*
　　
　　* ... 其他javadoc标记 ...
　　
　　*/
　　
　　public class receiverbean implements sessionbean, domsource {
　　2.1.3 @weblogic:pool标记
　　
　　
　　下面我们将配置面向特定厂商的缓冲池特征，为便于讨论，我们将使用weblogic。为表示声明仅对特定厂商有效，我们先声明weblogic名称空间：
　　
　　
　　
　　/**
　　
　　* this is the ejb receiver xbean
　　
　　*
　　
　　* ... 其他javadoc标记 ...
　　
　　*
　　
　　* @weblogic:pool max-beans-in-free-pool="1000"
　　
　　* initial-beans-in-free-pool="10"
　　
　　*
　　
　　* ... 其他javadoc标记 ...
　　
　　*/
　　
　　public class receiverbean implements sessionbean, domsource {
　　
　　
　　
　　
　　
　　这个标记将在面向weblogic的部署描述器（weblogic-ejb-jar.xml）中配置缓冲池参数。
　　
　　
　　还有其他许多类这一级的标记，这些标记使得我们能够调整任何可以在部署描述器中指定的选项。下面概要地介绍了可能在部署过程中要用到的一些“标准”标记：
　　
　　
　　
　　@ejb:bean：唯一必需的标记，配置有关bean的基本信息。
　　
　　@ejb:home：提供有关home接口的信息。可以要求xdoclet扩展一个定制的接口，或者把接口放入指定的包，等等。
　　
　　@ejb:interface：类似于home标记，但用来配置与组件接口（远程的和/或本地的）有关的信息。
　　
　　@ejb:finder：在实体bean home接口上定义查找器方法。
　　
　　@ejb:select：在实体bean home接口上定义select方法。
　　
　　@ejb:pk：为实体bean定义主键。xdoclet能够生成主键类。
　　
　　@ejb:data-object：数据对象（也就是值对象）可以通过这个标记自动生成。
　　
　　@ejb:ejb-ref：配置ejb引用。
　　
　　@ejb:ejb-external-ref：配置对其他应用中的ejb的引用，这里必需指定bean的类型等信息。
　　
　　@ejb:resource-ref：配置资源引用。
　　
　　@ejb:security-role-ref：配置安全角色引用。
　　
　　@ejb:transaction：为当前bean的home接口和remote接口中的所有方法定义事务属性。可以通过为单个方法提供的事务标记覆盖。
　　
　　@ejb:permission：允许role-name中指定的角色调用该bean的home接口和remote接口中的所有方法。
　　
　　@ejb:security-identity：指定是否用调用者的安全标识符执行ejb的方法，还是用另外一个特定的安全标识符。
　　
　　2.2 在方法这一级上的定义
　　
　　
　　下面我们来看看方法级的标记。要让某个方法成为远程接口的一部分，我们只需通过一个方法级的标记告诉xdoclet：
　　
　　
　　
　　/**
　　
　　* the method that the sender uses to pass the document
　　
　　*
　　
　　* @ejb:interface-method view-type="remote"
　　
　　*/
　　
　　public void documentready(document incomingdocument) {
　　
　　
　　
　　
　　
　　这个标记经常要用到。一般地，我们依次检查bean类里面每一个方法，如果某个方法应该让客户程序调用，则在该方法声明的前面加上这个标记。如果希望客户程序通过本地接口访问这个方法，只需把view-type值改成local就可以了。
　　
　　
　　下面是另外几个常用的ejb方法级的标记：
　　
　　
　　
　　@ejb:relation：为ejb 2.0 cmp实体bean定义一个关系。
　　
　　@ejb:home-method：把方法定义为ejbhome*方法。
　　
　　@ejb:pk-field：标示主键域。
　　
　　@ejb:transaction：为当前的方法定义事务行为（指定一个合法的事务属性：notsupported，supports，required,requiresnew，mandatory，或者never）。 <