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)