使用XDoclet开发EJB

   你开发过EJB么？当你去创建和操作EJB的XML部署描述以及接口时，是否受过挫折呢？我当然有过。
我近来正在用EJB开发一个叫Xbeans的开源项目，并且决定使用另外一个开源工具 -- XDoclet -- 来生成XML描述和EJB接口.

   使用XDoclet可以让你在J2EE框架内更高效的工作。你将有一个更简单的beans之间的视图和关系，
并且可以去除很多你在开发中的烦恼。
   这篇文章将讨论XDoclet,以及如何去使用和扩展它。在这里，我们将创建一个使用javadoc标记(tag)的会话(Session)Bean,并且使用XDoclet运行它。

什么是XDoclet？

   XDoclet是在Rickard Oberg创建的EJBDoclet基础上演化过来的一个工具。它的想法很简单：通过bean类本身来查看整个组件，而不是通过操作多个ejb文件。它是怎样做到的呢？java除了有javadoc标记外，并没有.NET所宣传的"属性"。我们可以在javadoc注释中放入特殊@标签，让一个Doclet的工具来寻找这些标签，让后根据bean给的信息集合来生成合适的XML描述和接口。XDoclet以EJBDoclet观念为基础，并且把此框架扩展在EJB领域之外，现在你可以生成Web Services,Web Applicaiton的描述，甚至通过扩展来满足你个人的需要。

   @标签有一个标准的格式：一个“命名空间(namespace)”和一个属于命名空间的“标签名称(tagname)",然后是经由 name="value"的属性传递给标签。
 下面是一个通用的示例：
  /**
 * @namespace:tag name="value" name2="value2" ...
 */

当前的命名空间有：
   ejb：标准EJB信息（不包括特定厂商）
   jboss:关于Jboss应用服务器的特定信息
   weblogic:关于BEA's Weblogic 应用服务器的特定信息
   wegSphere:关于IBM's WebSphere 应用服务器的特定信息
   orion:关于Orion应用服务器(Oracle)的特定信息
   castor:根据Castor框架生成相关的映射信息
   mvcsoft:根据MVCSoft EJB2.0的持久管理器生成相关的文件
   soap:生成SOAP描述
   structs:根据FORM和Action生成structs-config.xml
   web:根据Web Application生成web.xml配置
   jsp:生成tld信息
正如你看到的，除了EJB还支持很多其他的框架，所有EJBDoclet改名成XDoclet.（译者：当然了，现在支持的框架更多了，包括近来流行的spring,hibernate等，具体参考官方网站 http://xdoclet.sourceforge.net）

会话Bean:通过使用特殊的Javadoc标签创建一个会话Bean

    既然我们已经谈论了XDoclet，现在让我们来一个真实的示例吧。我们将以一个会话EJB开始。这个EJB是Xbeans框架的一部分，但是在这里，我们并不关心它是做什么的。我们仅仅关心怎样通过Javadoc标签把这个bean类标记出来，然后使用XDoclet来生成我们的元文件(meta files).

    ReceiverBean.java将包含方法：documentReady(Document doc).在这个XBean链表中，此方法使用一个DOM文档(document)参数，并且把它传递给下一个XBean。

 

类级别标签的定义

    在类级别中，我们需要定义：
   1。这是一个无状态的会话bean.
   2。JNDI的名称
   3。环境实体
   4。厂商的特定信息(Weblogic pooling信息）

标签：@ejb:bean

    在这个标签中，唯一要设置的XDoclet属性是bean的名称。我们还将定义bean的类型，绑定到客户桩的JNDI名称以及显示名称:

/**
 *   This is the EJB Receiver Xbean
 *
 *   @ejb:bean type="Stateless"
 *             name="ejbReceiver"
 *             jndi-name="org.xbeans.ejb.receiver.Receiver"
 *             display-name="EJB Receiver Xbean"
 *
 * ... other javadoc tags ...
 */
public class ReceiverBean implements SessionBean, DOMSource {

ejb:bean最常用的属性是：
   name:EJB的名称(在描述中使用)
   type:定义bean的”类型“，对会话bean，是Stateful或Stateless，对实体bean是CMP或BMP
   jndi-name:JNDI名称将在特定厂商的部署描述中使用(对远程接口来说)
   local-jndi-name:和jndi-name相似，除了给本地接口使用外。
   view-type:说明bean将支持的"接口视图(views)"，可以是remote,local或者both.
至于全部标签，可以查看XDoclet文档了解全部选项。

标签:@ejb:env-entry

这个标签定义一个经由特殊的java:comp/env上下文，被配置在JNDI的环境实体.我们将定义一个环境实体，在此实体中bean将在链表中寻找下一个Xbean.

/**
 *   This is the EJB Receiver Xbean
 *
 * ... other javadoc tags ...
 *
 *   @ejb:env-entry name="channelBean" type="java.lang.String"
 *                  value="com.your.ChannelBean"
 *
 * ... other javadoc tags ...
 */
public class ReceiverBean implements SessionBean, DOMSource {

标签：@weblogic:pool

现在我们将使用Weblogic的参数来配置特定厂商的池特征。为了表示我们在使用特定厂商，我么使用了weblogic命名空间：

/**
 *   This is the EJB Receiver Xbean
 *
 * ... other javadoc tags ...
 *
 *   @weblogic:pool max-beans-in-free-pool="1000"   
 *                  initial-beans-in-free-pool="10"
 *
 * ... other javadoc tags ...
 */
public class ReceiverBean implements SessionBean, DOMSource {
这个标签将在weblogic的部署描述文件(weblogic-ejb-jar.xml)里配置池的参数。

当然了，在部署中，还可以使用许多其他类级别(class-level)的标签。以下是经常被使用的标准标签的一瞥：

@ejb:bean
    这是唯一要求必须的标签，它用来配置bean的基本信息
@ejb:home
    这个标签提供了home接口的信息。你可以让XDoclet去继承一个自定义的接口，可以生成那种home接口(none,remote,local,or both),接口的package应该是什么，等等
@ejb:interface
    和home标签相似，除了可以配置相关接口的信息(远程和/或本地）。
@ejb:finder
    在实体beans的home接口中定义查找的方法
@ejb:select
    在实体beans的home接口中定义选择的方法
@ejb:pk
    为实体bean定义主键。XDoclet能够为你自动生成主键类。
@ejb:data-object
    通过这个标签，可以自动生成实体beans的数据对象。
@ejb:ejb-ref
    配置EJB的引用
@ejb:ejb-external-ref
    配置要引用在别的应用中的beans。在这里，你需要输入象bean的类型，home/remote接口的类等
@ejb:resource-ref
    配置资源引用。
@ejb:security-role-ref
    配置安全角色引用
@ejb:transaction
    为有事务行为的remote和home接口的所有方法定义事务类型。单独方法的事务标签可以覆盖。
@ejb:permission
    允许基于角色来调用remote和home接口的所有方法。
@ejb:security-identity
    用来指定在执行EJB的方法时，是否需要调用者的安全标识，或者是否需要一个特别的运行标识。

方法级别标签的定义

  如果我们想让一个方法成为remote接口的一部分，那么只需要通过一个方法级别的标签就可以了。示例如下：

  /**
   *  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
    定义了EJB2.0 CMP实体bean之间的关系
@ejb:home-method
    将方法定义为ejbHome*的方法
@ejb:persistent-field
    在生成的CMP层类型(layer of type)中创建CMP的字段"X"，并且具体实现getX/setX方法。
    对于BMP来说，它将生成保持脏标志(dirty flag)的getX/setX方法(以方便ejbStore在需要的时候调用)
@ejb:pk-field
    标志主键字段
@ejb:transaction
    给方法定义事务的行为（只能是以下有效属性：NotSupported|Supports|Required|RequiresNew|Mandatory|Never.
@ejb:permission
    定义方法的权限(以逗号分隔的角色列表将被允许访问这个方法)。

使用XDoclet来构建Bean

  现在我们已经有一个使用XDoclet做了标记的ReceiverBean.java的源文件。现在需要运行XDoclet来为生成所有我们需要的。更好的方法是使用Jakarta-Ant来构建系统。
Ant是一个基于java的普遍使用的构建系统。如果你还没有使用Ant,那么就到Jakarta官方网站下载一个，或者参考Open Source Java:Ant

  XDoclet的团体已经开发好了Ant任务(task),所以我们只需要简单加入到构建文件（build.xml)中就可以使用了.
主要有两个任务：
  
  和
  
  .既然我们在使用EJB，那就让我们在构建文件中仔细的研究一下ejbdoclet目标(target详细请参考Ant文档)。

  
  
   
   
         classname="xdoclet.ejb.EjbDocletTask" classpath="${java.class.path};${xdoclet.jar.path};
   
   
        ${log4j.jar.path};${ant.jar.path}"/>
  
  

  
  
   
   
sourcepath="${java.dir}"
   
   
destdir="${generated.java.dir}"
   
   
ejbspec="2.0">
  
  

  
  
   
   
            version="2.4" xmlencoding="UTF-8" />
   
   

   
   
    
    
            xmlencoding="UTF-8"
    
    
            validatexml="true"/>
    
    

    
    
    
    

    
    
   
   
  
  

在示例文件中有太多的信息，所以我们需要停下来讨论一些事项：

标签：
   
   

  我们需要让ant能够理解
  
  
   
   标签。我们需要定义标签的名字，实现标签的类，还要把此类传递到classpath中。
   
   
在示例中，我们使用在build.xml开始初始化的properties来指定我们需要的库(libraries).
   
   

   
   
    
    
classpath="${java.class.path};${xdoclet.jar.path};${log4j.jar.path};
    
    
${ant.jar.path}"/>
   
   
  
  

标签：
   
   

  最外边的标签让ant运行EJBDoclet任务。我们传人我们代码的位置，将要生成XML描述和Java源代码的位置，以及我们要引用的EJB规范的版本（我们再次使用properties):

  
  
   
   
 sourcepath="${java.dir}"
   
   
 destdir="${generated.java.dir}"
   
   
 ejbspec="2.0">
  
  

标签：
   
   

  我们使用
  
  
   
   指令(directive)来告诉
   
   
    
    在那里能够找到我们的beans.
    
    
在示例中，我们将在${java.dir}的子目录下查找所有名字为ReceiverBean.java的文件。
    
    

    
    
     
     
    
     
     
     
     
 
    
    
   
   
  
  

标准标签：接口和XML部署描述

  接下来的一系列标签将生成远程接口，home接口，以及标准的XML部署描述(ejb-jar.xml):

  
  

  
  

  
  

特定供应商的标签：接口和XML部署描述

  最后的这些标签生成特定厂商的部署描述。如果你仅仅部署一种EJB服务器，那么你只需要其中一个task就可以了。
既然我打算让Xbean EJB发布在尽可能多的应用服务器上，我在这里加入了所有主要的提供商的标签。

  
  
   
   
           version="2.4" xmlencoding="UTF-8" />
   
   

   
   
    
    
           xmlencoding="UTF-8" 
    
    
           validatexml="true"/>
    
    

    
    
    
    

    
    
   
   
  
  

  现在我只需要在我的构建文件的同一目录下运行ant，就可以构建Xbean EJB的所有事情了。
只不过我将确定ant库(ant.jar,jaxp.jar，一个XML解析器)和xdoclet.jar一定要在我的CLASSPATH环境变量里
比如在Windows环境中：
% set CLASSPATH=%CLASSPATH%;c:/lib/ant.jar;c:/lib/jaxp.jar;c:/lib/xerces.jar;
  c:/lib/xdoclet.jar;c;/lib/log4j.jar;c:/lib/ejb.jar

% ant ejbdoclet
[runs ant on the ejbdoclet task]

% ant
[runs ant on the default task. In this case it will generate the source, xml descriptors, then compile them, and package everything as an ejb-jar file]

下载源代码

关于作者

Dion Almaer是The Middleware Company的资深技术专家，TheServerSide.Com的J2EE社区的主要设计师