http://xdoclet.sourceforge.net/xdoclet/using.html ──────────────────────────────── TonyQ按： 同上篇，主要是文件的翻译，这篇比较偏操作说明的实用文章， 文中还是有一些地方看不太懂，也欢迎同好互相分享交流一下。 ──────────────────────────────── Using XDoclet is simple. Just as you write JavaDoc tags for your code (you do comment your code, don't you?), you now add XDoclet tags too. These tags are used by XDoclet as providers of meta-data that is then used to generate other files as required. 使用XDoclet很简单。就像你写JavaDoc的注解一样（你应该会写注解吧？）， 你现在可以增加XDoclet注解。 这些注解会被XDoclet使用，当作产生其他档案的meta资料供应者， For a thorough example of how to use XDoclet, consult the samples. However, this page should give you enough of a start to XDoclet your code. 一个完整的XDoclet范例，参考这范例， 无论如何，这个指引应该会给你足够的资讯去使用XDoclet在你的程式码内。 A typical XDoclet comment might look like this: 一个正常的XDoclet注解应该看起来像这样 /** * This is the Account entity bean. It is an example of how to use the * EJBDoclet tags. * * @see Customer * * @ejb.bean * name="bank/Account" * type="CMP" * jndi-name="ejb/bank/Account" * local-jndi-name="ejb/bank/LocalAccount" * primkey-field="id" * * @ejb.finder * signature="java.util.Collection findAll()" * unchecked="true" * * @ejb.transaction * type="Required" * * @ejb.interface * remote-class="test.interfaces.Account" * * @ejb.value-object * match="*" * * @version 1.5 */ There are three parts to that comment: The comment, the javadoc tag, and the XDoclet tags. The first two are your standard documentation. Just because you are using XDoclet doesn't mean that you stop doing normal documentation. The third part of the comment is the part that we are interested in. An XDoclet tag is comprised of the following parts: 这段注解有三个部份，注解、javadoc标签，以及XDoclet标签， 前面两个是标准的文件说明，因为用了XDoclet不代表你停止做文件说明。 这第三部份是我们所关注的， 一个XDoclet标签是由底下这些部份组成的 @namespace.tag-name attribute-name="attribute value" The concept is similar to an XML element, which has a tag name and an optional set of attributes. The difference is the syntax. 这概念跟XML的element有点像，有一个tag name， 以及一个可自订的属性集合，不同之处是语法结构。 Tags are grouped by namespaces, and have names that are unique within that namespace. Tags can have zero or more attributes, which are grouped in name="value" pairs. Looking at the above example, we find the first tag is in the ejb namespace, and is called bean. The ejb.bean tag defines data relating to Enterprise Java Beans. Every EJB will require a name, and it is specified here. The namespace is a mechanism for making sure no name collision happens. Namespaces include ejb, web, jboss, weblogic, struts and so on. So it's simply a way to group related tags. For details on individual tags, consult the Tag Reference. 标签由namespace所分类，并且拥有该namespace中唯一的名字， tags可以有0个以上的属性，用 名称 = "内容" 的方式分类， 看看前面的范例，我们找到第一个tag在ejb namespace，并且他被称作bean。 这个ejb.bean标签定义资料关联着 Enterprise Java Beans(EJB)， 每个EJB都会要求要有个名字，他在这里被定义。 namespce是确认没有名称冲突发生的一种手段， 他包括如 ejb ,web,jboss,weblogic,struts 以及其他尚未列到的namespace。 所以他是一个简单的方式去分类彼此有关联的tag， 每个tag的细节，请参考 Tag 参考资料。 Tag values can be specified as ant properties. For example: 内容可以用ant的属性，比方说底下的例子： @jboss.create-table create="${jboss.create.table}" Where the jboss.create.table is a property defined in the ant project. For more information on ant properties consult the Jakarta Ant documentation. jboss.create.table 是ant 专案中的一个被定义好的属性， 更多关於ant属性的资料请参考 Jakarta Ant 说明文件。 Tags exist at both class and method level (and in some rare cases even on the field or constructor level). As a general rule, if information can be determined by the name or type of a class, then it will be - and hence there will not be a requirement to specify that information with a tag. An example of this is the type attribute of the ejb.bean tag example above. The type in this instance refers to the Entity type (CMP or BMP), but if the class implemented the javax.ejb.SessionBean interface the type would be Stateful or Stateless. So in the above example, the type can be omitted. Tags同时存在 class 跟 method 的部份， 在一些罕见的案例甚至使用在成员或建构子上。 像平常一般，如果资讯可以用class的名字或型态被定义， 那就不需要用一个tag写起来。 （TonyQ按：这一段其实不完全懂...） 一个范例是前面提到的 ejb.bean 标签 的 type属性，这 type在这个例子中 关联到 Entyty type (CMP or BMP )， 但是当这个类别实作 javax.ejb.SessionBean 介面时， 型态会是 statefull或stateless，所以在前面的例子， type可以被省略。 To start using XDoclet you must first determine what it is you wish to use it for. The two most popular usages are EJBDoclet and WebDoclet. Generally you should define the XDoclet task for Ant, setup the configuration parameter. Here is an example: 要开始使用 XDoclet，你首先应该要确定你想要使用他， 两个最常见的用途是 EJBDoclet跟 WebDoclet ， 一般来说你应该要为Ant 定义 XDoclet task，设定需要的参数，底下是一个范例： ──────────────────────────────── <path id="project.class.path"> <fileset dir="${lib.dir}"> <include name="*.jar"/> </fileset> </path> <target name="ejbdoclet" depends="prepare"> <taskdef name="ejbdoclet" classname="xdoclet.modules.ejb.EjbDocletTask" classpathref="project.class.path" /> <tstamp> <format property="TODAY" pattern="d-MM-yy"/> </tstamp> <ejbdoclet destdir="${generated.java.dir}" excludedtags="@version,@author" addedtags="@xdoclet-generated at ${TODAY}" ejbspec="2.0" > <fileset dir="${java.dir}"> <include name="**/*Bean.java"/> </fileset> <dataobject/> <packageSubstitution packages="persistence" substituteWith="interfaces"/> <remoteinterface pattern="{0}Remote"/> <localinterface pattern="{0}"/> <homeinterface /> <localhomeinterface/> <entitypk/> <entitycmp/> <deploymentdescriptor destdir="${build.dir}/ejb/META-INF"/> <jboss version="3.0" securityDomain="java:/jaas/samples" preferredRelationMapping="relation-table" datasource="java:/DefaultDS" datasourcemapping="Hypersonic SQL" destdir="${build.dir}/ejb/META-INF" /> </ejbdoclet> </target> <target name="compile" depends="ejbdoclet"> <!-- Compile EJBs --> <javac srcdir="${java.dir}:${generated.java.dir}" destdir="${build.dir}/ejb" includes="test/ejb/*.java, test/interfaces/*.java" > </target> ──────────────────────────────── Here the compile target depends on the ejbdoclet target. This means that before compiling anything all home/local/remote interfaces, primary key, data-objects and deployment descriptors are generated. The first thing you have to do is define the ejbdoclet task for Ant. （Tony按：不懂again） 编译 target 依赖着 ejbdoclet target ， 这代表着在编译前任何 home/local/remote 介面,p k,资料物件， 以及开发叙述已经被产生。 第一件你必需要做的事情就是定义ant的 ejbdoclet task. To do so you use taskdef, where you specify xdoclet.modules.ejb.EjbDocletTask as the class implementing ejbdoclet task. Note that the classpathref points to the path with id "project.class.path". This path should have all XDoclet jar files and commons-logging.jar. 所以你使用 taskdef ，定义用xdoclet.modules.ejb.EjbDocletTask这个class 扩充 ejbdoclet task 。 记得 classpathref 指向的 path， 应该要拥有所有 XDoclet 的jar档，以及 commons-logging.jar。 Next you declare ejbdoclet task, with a set of configuration parameters and nested elements. For example, destdir specifies where to put generated files. As you can see there's an inheritance mechanisms also, you can override this destdir parameter for each nested element (or as we call it sub-task). 接下来你定义 ejbdoclet task，以及一堆设定参数和巢状的元素们。 举例而言，destdir设定哪里去放置产生的档案， 就像你看到的，这也是一个继承结构， 你可以复写每一个巢状元素的destdir。（或者我们叫这些元素为sub-task） <deploymentdescriptor/> does exactly that; put the generated ejb-jar.xml file somewhere else than where generated java sources for home/remote/pk/etc are placed. For a complete list of configurable parameters consult the Ant Task Reference for each task and sub-task. <deploymentdescriptor/> 就是做这些事情，把产生的ejb-jar.xml档案和 从home/remote/pk/etc产生的source 放置到不同地方。 完整的设定参数清单请参考每一个task跟sub-task的 Ant Task参考资料 。 By default each task has some built-in sub-tasks. Some of them are mandatory, for example <remoteinterface/> and <localinterface/>, can you imagine an EJB without a remote or local (EJB 2.0 only) interface? Some other tasks may be optional, for example <jboss/> is optional if you're not using JBoss Application Server. 预设每个task有一些固定的sub-task，有一些是强制的， 比方说 <remoteinterface/> 跟 <localinterface/>， 你可以想像一个 EJB 没有一个remote or local (EJB 2.0专属) 介面吗？ 一些其他的task可能是可自由选择的，比方说 <jboss/> 是非必须的， 如果你不是使用 JBoss Application Server 。 There's even a third form of sub-tasks: <template/>. This is useful for cases where you want to design your own template file and generate a customized file. So, you need a simple way to let XDoclet use your template file. Here is an example: 这里甚至有第三种形式的 sub-task， <template/>， 当你想设计你自己的样本档案，并且产生一个自订的档案，这是非常有用的。 所以，你需要一个简单的方法让XDoclet使用你的样本档案，底下是一个范例： ──────────────────────────────── <taskdef name="templatedoclet" classname="xdoclet.DocletTask" classpathref="project.class.path" /> <templatedoclet destdir="${generated.java.dir}" excludedtags="@version,@author" > <fileset dir="${java.dir}"> <include name="**/*Bean.java"/> </fileset> <template templateFile="/mytemplate.xdt" destinationfile="mygeneratedfile.txt" /> </templatedoclet> ──────────────────────────────── So you put a <template/> element in the task, specify the path to your template file and output file name (which will we stored in the directory specified in destdir parameter). This is very useful for those creative people who want to easily take advantage of XDoclet's framework-like capabilities and define their own set of @tags and templates generating something from those @tags. 所以你放置一个 <template/> 元素在这个task， 指明你的样本档案路径跟输出档案的档名， （将会存在destdir参数中所设定的资料夹）， 这对那些想要轻松使用由XDoclet类Framework特性所带来的优点， 并具有创造力的人们是非常有用的，可以自订他们的tag 集合 以及templates， 并从中产生一些资料。 So whenever you build, ejbdoclet (and/or whatever other task) is run and generates up-to-date files. 所以当你build，ejbdoclet被执行（与其他task一起与否）并且产生最新的档案。 Quick checklist of things to get XDoclet running: * Modify (creating if required) your build.xml script (see Jakarta Ant web site for details). * Add XDoclet tags to your source code. * Stop worrying about all that boring code you used to write! XDoclet does it all for you now. 让XDoclet运作的检查清单： *修改（如果不存在则建立）你的build.xml script（细节详见 Jakarta Ant网站） *增加XDoclet tags 到你的程式码中 *停止担心过去你写的那些无聊的程式码，XDoclet现在都帮你完成了！ The mailing lists provide a wealth of knowledge, and the developers are lurking on the xdoclet-user list, so feel free to ask questions, make suggestions, or just generally discuss XDoclet. 这个mailing lists 提供丰富的知识，并且开发者阅读在这 xdoclet-user 清单， 所以请尽情询问问题、提供建议，或者就是讨论关於XDcolet的议题。 -- http://tony1223.no-ip.org:1986/JSPWiki/Wiki.jsp?page=XDoclet_2 -- What do you want to have ? / What do you have? 从书本中，你可以发现我的各种兴趣。 从ＣＤ中，你可以了解我所喜欢的偶像明星。 或许从文字你很难以了解一个人，但从物品可以。 My PPolis , My past. http://ppolis.tw/user/Tony1223 --

※ 发信站: 批踢踢实业坊(ptt.cc) ◆ From: 220.134.27.68 ※ 编辑: TonyQ 来自: 220.134.27.68 (06/08 14:34)