dom4j 是一套開放原始碼的 Java XML 工具包。它會把整份 XML 文件在記憶體中還原成一棵樹狀物件模型,讓程式可以用「導覽」的方式自由走訪節點;在此之上,dom4j 還提供了完整的 XPath 與 XSLT 支援,並整合了 SAX、JAXP 與 DOM,因此在 Java 專案裡處理 XML 時格外順手。
另一個值得注意的設計重點是:dom4j 幾乎完全以介面為基礎。只要自行實作一個 DocumentFactory,就能替換掉預設的 XML 樹實作。這種面向介面的架構,讓你在擴充、客製化功能時可以大量重用既有程式碼,而不必推翻整個模型。
以下整理自實際專案中的使用經驗,以程式碼範例為主軸,希望能與網路上既有的文件互相補充。
最常見的情境就是把一份 XML 讀進記憶體,再用 XPath 取出感興趣的節點。有了 SAXReader,這件事只要幾行:
public void readXMLSimple(File file) throws DocumentException {
// 以 SAXReader 讀入 XML 文件
SAXReader sr = new SAXReader();
Document doc = sr.read(file);
// 取得根元素後,用相對路徑挑選節點
Element root = doc.getRootElement();
List entryList1 = root.selectNodes("entry");
// 也可以直接從 Document 用絕對路徑挑選
List entryList2 = doc.selectNodes("/feed/entry");
}
反過來,要「產生」一份 XML 並存檔,同樣只需要很少的程式碼。以下範例假設手上已經有一批從別份文件取得的 entry 節點,我們把它們掛到新文件底下,再以漂亮的縮排格式寫到磁碟:
public void createXMLSimple(List entries, File f)
throws FileNotFoundException,
UnsupportedEncodingException,
IOException {
Document doc = DocumentHelper.createDocument();
doc.addElement("feed");
Element root = doc.getRootElement();
Iterator i = entries.iterator();
while (i.hasNext()) {
// 來自其他 Document 的 Element 各自帶有自己的 root,
// 因此必須先建立副本,才能掛到新的 Document 上
root.add(((Element) i.next()).createCopy());
}
FileOutputStream os = new FileOutputStream(f);
OutputFormat of = OutputFormat.createPrettyPrint();
XMLWriter xmlw = new XMLWriter(os, of);
xmlw.write(doc);
}
如果上一段範例讀的其實是符合 Atom 1.0 規範的 Feed,情況就複雜一些——它的根節點帶有預設命名空間 https://www.w3.org/2005/Atom。網路上這類範例很多,但真正好用的不多;實作過就會發現,很難寫得像想像中那麼乾淨。
關鍵在於:必須先把命名空間對應表交給文件的 XPath 引擎,後續的 XPath 運算式才會帶上前綴:
public void treatDefaultNamespace(File f) throws DocumentException {
SAXReader sr = new SAXReader();
// 註冊命名空間前綴與 URI 的對應
Map ns = new HashMap();
ns.put("atom", "https://www.w3.org/2005/Atom");
sr.getDocumentFactory().setXPathNamespaceURIs(ns);
// Element 介面支援迭代器,這裡順便示範
Element root = sr.read(f).getRootElement();
Iterator i = root.elementIterator();
while (i.hasNext()) {
Element e = (Element) i.next();
// 一旦指定了 Namespace,使用 XPath 時就必須帶上前綴,
// 即使是預設的 Namespace 也一樣。前綴名稱建議盡量短(例如 a),
// 撰寫運算式時會方便許多
String title = e.selectSingleNode("atom:title").getText();
System.out.println(title);
}
}
建立帶有預設命名空間的文件相當微妙。因為建立 Element 的方式有很多種——用 addElement、用預設建構、或透過 DocumentHelper——而每種寫法產出的結果都不一樣,往往出乎意料。網路上這類「各種寫法、各種結果」的討論已經很多,這裡只提供一個能產出乾淨 XML 的版本:
public void createXMLWithDefaultNamespace(List entries) {
Document d = DocumentHelper.createDocument();
d.addElement("feed", "https://www.w3.org/2005/Atom");
Element root = d.getRootElement();
// 此處省略迭代 entries 的程式碼
root.addElement("title").add(DocumentHelper.createCDATA(title));
root.addElement("id").add(DocumentHelper.createText(guid));
root.addElement("category").add(DocumentHelper.createText(category));
root.addElement("link").add(DocumentHelper.createText(permalink));
root.addElement("updated").add(DocumentHelper.createText(updated));
}
以下列出範例中出現的 dom4j 類別及其套件位置,未列出的部分皆屬於 J2SE 標準庫:
import org.dom4j.Document;
import org.dom4j.DocumentException;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;
import org.dom4j.io.OutputFormat;
import org.dom4j.io.SAXReader;
import org.dom4j.io.XMLWriter;
整體來說,dom4j 的 API 直覺、學習曲線平緩,加上 XPath 的加持,讓「讀取、查詢、產生、輸出」這四件 XML 日常任務都能用可讀性極高的程式碼完成,是 Java 專案中值得信賴的選擇。