2010年11月26日

Maven、Java 1.5 與 xdoclet 的相處之道

最近幾年來的 Java 專案都使用 Maven 2 進行自動化部署程序,講白一點就是不想每次都要依環境差異而透過手工進行設定調整及打包程序。不過有趣的是還是有很多軟體開發人員仍然堅持手工打造然後因為一點疏失就上錯程式捅下漏子!
但是不知道為什麼,整個 Maven 中的 xdoclet plugin 預設一直使用舊版的 xjavadoc 套件,導致在處理 JDK 1.5 新增的泛型特性(Generics)時因為不認識角括號 < 而吐出一大堆錯誤訊息,並連帶使的 Maven 原本提供的 javadoc 操作失敗(產生的 javadoc 不完整),對開發公用程式庫且必須提供 javadoc 的人員來講就變的很困擾。
一直逃避不是辦法,所以今天花了點時間找了網路上的資料後試出了解決方法。基本上是參考 解決xdoclet-maven-plugin於jdk5上跑發生問題 的說法,但文中所提的 plugin 來源 http://quebbemann.kicks-ass.net/maven2/repository/ 被 威猛的趨勢科技世界級創新Smart Protection Network主動式雲端截毒技術 擋在門外... 只好另外找其他的 plugin 來源。
總之,要讓 xdoclet 叫用新版的 xjavadoc 模組的方法是覆寫 xdoclet-maven-plugin 的相依性設定,使 xdoclet-maven-plugin 正確叫用新版的 xjavadoc 1.5 去解析 Java 原始碼,因此需要在 xdoclet-maven-plugin 設定區塊下新增相依性設定如下:
<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>xdoclet-maven-plugin</artifactId> <version>1.0</version> <dependencies> <dependency> <groupId>ant</groupId> <artifactId>ant</artifactId> <version>1.6.5</version> </dependency> <dependency> <groupId>xdoclet</groupId> <artifactId>xjavadoc</artifactId> <version>1.5-snapshot050611</version> </dependency> </dependencies> <executions> <execution> <id>xdoclet</id> <phase>generate-sources</phase> <goals> <goal>xdoclet</goal> </goals> <configuration> <outputEncoding>UTF-8</outputEncoding> <tasks> <webdoclet destDir="${basedir}/src/main/webapp/WEB-INF" encoding="UTF-8" docencoding="UTF-8" mergeDir="${basedir}/src/main/resources/webdoclet" verbose="true" force="true"> <fileset dir="${basedir}/src/main/java" includes="**/*.java" /> <deploymentdescriptor displayname="${project.name}" xmlencoding="UTF-8" description="${project.description}"> </deploymentdescriptor> </webdoclet> </tasks> </configuration> </execution> </executions> </plugin>
但是光這樣還不夠,因為 Maven 官方的套件庫中並未包含 xjavadoc 1.5 相關資訊,所以必須另外指定去那邊下載 xjavadoc 套件,這只要在 pom.xml 中加入以下設定區塊即可。唯一要注意的是這個套件庫有可能隨時不見... XD
<pluginRepositories> <pluginRepository> <id>jahia</id> <url>http://maven.jahia.org/maven2/</url> </pluginRepository> </pluginRepositories>
好了,經由以上設定後 xdoclet 就不會因為程式碼使用到 JDK1.5 的泛型功能時只會吐出一堆 warning 了!