解組器和平時的寫法差異其實很小:建立 Unmarshaller 實例時傳入 Book.class,告訴它要還原的頂層類別是哪一個(這個類別對應到 mapping 中的 map-to 元素),接著設定對應關係,最後呼叫 unmarshal() 的非靜態版本。
本文延續系列第一篇的環境設定。最省事的做法就是照著第一篇的步驟把 Castor 下載、安裝、設定好,並用那幾個簡單的類跑過一次測試。
你也可以直接挑自己專案裡的類來試,把物件轉成 XML 再轉回來。本文與前一篇都提供了範例,但要真正掌握 Castor,最好的方式還是把這裡學到的東西套用到自己的程式碼上。建議從簡單的實體類開始——人、唱片、圖書之類具體的東西——先跑通基本流程,再逐步加入更複雜的結構。
Castor 最基本的操作,就是取一個 Java 類的實例,把它編組成 XML。類本身通常會成為最外層的容器元素,例如 Book 類很可能對應出一個名為 book 的根元素。
類的每個屬性也各自對應成 XML 中的元素。所以 title 屬性的值若是「Power Play」,就會產生:
<title>Power Play</title>
由此不難推想出整個 XML 文件會長成什麼樣子。
動手之前有個觀念必須釐清:能編組的只有類的實例,而不是類本身。類是一種結構定義,角色等同於 DTD 或 XML Schema 這樣的約束模型——它本身不含資料,只規範資料的形狀與存取方式。
把類實例化(直接 new,或透過工廠等機制)之後,它才有了具體形體,接著再用真實資料填入欄位。每個實例各自獨立,彼此結構相同但內容不同。圖 1 把這個關係畫得很清楚。
圖 1. 類提供結構,實例承載資料
因此編組的對象只能是實例。後面會說明如何用約束模型與對應檔改變 XML 的結構;現階段先讓 XML 的結構(元素、屬性)與 Java 的結構(欄位)保持對齊即可。
package ibm.xml.castor;
public class Book {
/** The book's ISBN */
private String isbn;
/** The book's title */
private String title;
/** The author's name */
private String authorName;
public Book(String isbn, String title, String authorName) {
this.isbn = isbn;
this.title = title;
this.authorName = authorName;
}
public String getIsbn() { return isbn; }
public void setTitle(String title) { this.title = title; }
public String getTitle() { return title; }
public void setAuthorName(String authorName) {
this.authorName = authorName;
}
public String getAuthorName() { return authorName; }
}
編譯後得到 Book.class。這個類只有三個屬性:ISBN、標題、作者姓名。光有類別還不夠,Castor 需要幾行程式把實例轉成 XML。
package ibm.xml.castor;
import java.io.FileWriter;
import org.exolab.castor.xml.Marshaller;
public class BookMarshaller {
public static void main(String[] args) {
try {
Book book = new Book("9780312347482", "Power Play", "Joseph Finder");
FileWriter writer = new FileWriter("book.xml");
Marshaller.marshal(book, writer);
} catch (Exception e) {
System.err.println(e.getMessage());
e.printStackTrace(System.err);
}
}
}
編譯並執行,會得到 book.xml:
<?xml version="1.0" encoding="UTF-8"?>
<book><author-name>Joseph Finder</author-name>
<isbn>9780312347482</isbn><title>Power Play</title></book>
(為了可讀性我加了換行;實際輸出的 author-name 結束標記與 isbn 開始標記之間並沒有斷行。)
在改良這個例子之前,先看看 XML 裡少了哪些東西:
那又如何?既然不重要,忽略掉有什麼關係?事實上這些資訊很重要,因為它們換來了意料之外的靈活性。這份 XML 可以被解組進任何滿足最低條件的類:
就這樣。試著寫幾個都符合這些條件的類,改掉其他欄位、換掉套件宣告、加上各種方法——你很快會體會到這種寬鬆程度讓 Castor 有多靈活。
Book 類最明顯的缺陷是無法容納多位作者。改成集合並不難:
package ibm.xml.castor;
import java.util.LinkedList;
import java.util.List;
public class Book {
private String isbn;
private String title;
/** The authors' names */
private List authorNames;
public Book(String isbn, String title, List authorNames) {
this.isbn = isbn;
this.title = title;
this.authorNames = authorNames;
}
public Book(String isbn, String title, String authorName) {
this.isbn = isbn;
this.title = title;
this.authorNames = new LinkedList();
authorNames.add(authorName);
}
public String getIsbn() { return isbn; }
public void setTitle(String title) { this.title = title; }
public String getTitle() { return title; }
public void setAuthorNames(List authorNames) {
this.authorNames = authorNames;
}
public List getAuthorNames() { return authorNames; }
public void addAuthorName(String authorName) {
authorNames.add(authorName);
}
}
若使用 Java 5 或 6,編譯時會出現未檢查/不安全操作的提示,因為這裡沒有使用參數化 List。願意的話可以自己補上。
值得注意的是,這類修改完全不需要更動編組程式碼。為了確認 Castor 應付得來集合,我們讓 BookMarshaller 多處理一本雙作者的作品:
package ibm.xml.castor;
import java.io.FileWriter;
import java.util.ArrayList;
import java.util.List;
import org.exolab.castor.xml.Marshaller;
public class BookMarshaller {
public static void main(String[] args) {
try {
Book book = new Book("9780312347482", "Power Play", "Joseph Finder");
FileWriter writer = new FileWriter("book.xml");
Marshaller.marshal(book, writer);
List book2Authors = new ArrayList();
book2Authors.add("Douglas Preston");
book2Authors.add("Lincoln Child");
Book book2 = new Book("9780446618502", "The Book of the Dead",
book2Authors);
writer = new FileWriter("book2.xml");
Marshaller.marshal(book2, writer);
} catch (Exception e) {
System.err.println(e.getMessage());
e.printStackTrace(System.err);
}
}
}
第一本書的結果不變。打開 book2.xml,看看 Castor 如何處理集合:
<?xml version="1.0" encoding="UTF-8"?>
<book><isbn>9780446618502</isbn><title>The Book of the Dead</title>
<author-names xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:type="java:java.lang.String">Douglas Preston</author-names>
<author-names xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:type="java:java.lang.String">Lincoln Child</author-names>
</book>
Castor 顯然應付得來姓名清單。更值得注意的是,它沒有只包一層通用容器了事,而是真的看進了集合內部,辨識出成員是字串(別忘了這不是參數化清單,型別得靠 Castor 自行推斷),因而在 XML 中做了相當明確的型別標記。若你打算在把 XML 轉回 Java 之前先做一輪處理,這個特性相當實用。
再往前一步就接近真正實用的程式了。用字串存作者姓名,最終一定會遇到資料重複的問題——多數作者寫過不只一本書。清單 7 引入一個新的 Author 類。
package ibm.xml.castor;
public class Author {
private String firstName, lastName;
private int totalSales;
public Author(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}
public String getFirstName() { return firstName; }
public String getLastName() { return lastName; }
public void setTotalSales(int totalSales) {
this.totalSales = totalSales;
}
public void addToSales(int additionalSales) {
this.totalSales += additionalSales;
}
public int getTotalSales() { return totalSales; }
}
接著調整 Book 類,讓它使用新的 Author。
package ibm.xml.castor;
import java.util.LinkedList;
import java.util.List;
public class Book {
private String isbn;
private String title;
/** The authors */
private List authors;
public Book(String isbn, String title, List authors) {
this.isbn = isbn;
this.title = title;
this.authors = authors;
}
public Book(String isbn, String title, Author author) {
this.isbn = isbn;
this.title = title;
this.authors = new LinkedList();
authors.add(author);
}
public String getIsbn() { return isbn; }
public void setTitle(String title) { this.title = title; }
public String getTitle() { return title; }
public void setAuthors(List authors) { this.authors = authors; }
public List getAuthors() { return authors; }
public void addAuthor(Author author) { authors.add(author); }
}
編組器只需略作調整:
package ibm.xml.castor;
import java.io.FileWriter;
import java.util.ArrayList;
import java.util.List;
import org.exolab.castor.xml.Marshaller;
public class BookMarshaller {
public static void main(String[] args) {
try {
Author finder = new Author("Joseph", "Finder");
Book book = new Book("9780312347482", "Power Play", finder);
FileWriter writer = new FileWriter("book.xml");
Marshaller.marshal(book, writer);
List book2Authors = new ArrayList();
book2Authors.add(new Author("Douglas", "Preston"));
book2Authors.add(new Author("Lincoln", "Child"));
Book book2 = new Book("9780446618502", "The Book of the Dead",
book2Authors);
writer = new FileWriter("book2.xml");
Marshaller.marshal(book2, writer);
} catch (Exception e) {
System.err.println(e.getMessage());
e.printStackTrace(System.err);
}
}
}
編譯執行後看看兩個輸出檔。這裡只列 book2.xml,因為它比較有意思:
<?xml version="1.0" encoding="UTF-8"?>
<book>
<authors xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
total-sales="0" xsi:type="java:ibm.xml.castor.Author">
<last-name>Preston</last-name>
<first-name>Douglas</first-name>
</authors>
<authors xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
total-sales="0" xsi:type="java:ibm.xml.castor.Author">
<last-name>Child</last-name>
<first-name>Lincoln</first-name>
</authors>
<isbn>9780446618502</isbn>
<title>The Book of the Dead</title>
</book>
Castor 同樣辦到了,而且同時處理了 Book 與 Author 兩個類(再看一次 authors 清單)。它甚至把 Author 的 totalSales 屬性也寫了進去——這個值你可以試著設定看看效果。
聽起來或許像電視購物,但 Castor 確實支援泛型與參數化清單。若你習慣 Java 5 或 6 的寫法,可以這樣調整 Book:
package ibm.xml.castor;
import java.util.LinkedList;
import java.util.List;
public class Book {
private String isbn;
private String title;
/** The authors */
private List<Author> authors;
public Book(String isbn, String title, List<Author> authors) {
this.isbn = isbn;
this.title = title;
this.authors = authors;
}
public Book(String isbn, String title, Author author) {
this.isbn = isbn;
this.title = title;
this.authors = new LinkedList<Author>();
authors.add(author);
}
public String getIsbn() { return isbn; }
public void setTitle(String title) { this.title = title; }
public String getTitle() { return title; }
public void setAuthors(List<Author> authors) { this.authors = authors; }
public List<Author> getAuthors() { return authors; }
public void addAuthor(Author author) { authors.add(author); }
}
現在作者清單只接受 Author 實例,這是相當實用的收斂。同步調整 BookMarshaller、重新編譯,你會得到一模一樣的 XML 輸出。換句話說,你可以為 Castor 定義非常嚴謹的類別設計。
值得停下來注意一件事:前面對類別做的所有調整——泛型、自訂類、集合——都沒有讓編組程式碼更動分毫。無論結構多複雜,Castor API 那一行 marshal 呼叫始終如一。
花了這麼多篇幅談編組,解組聽起來應該很輕鬆。有了 XML 文件,也有對應的 Java 類,剩下的交給 Castor 就好。我們來還原前面產生的兩份文件。
package ibm.xml.castor;
import java.io.FileReader;
import java.util.Iterator;
import java.util.List;
import org.exolab.castor.xml.Unmarshaller;
public class BookUnmarshaller {
public static void main(String[] args) {
try {
FileReader reader = new FileReader("book.xml");
Book book = (Book) Unmarshaller.unmarshal(Book.class, reader);
System.out.println("Book ISBN: " + book.getIsbn());
System.out.println("Book Title: " + book.getTitle());
List authors = book.getAuthors();
for (Iterator i = authors.iterator(); i.hasNext(); ) {
Author author = (Author) i.next();
System.out.println("Author: " + author.getFirstName()
+ " " + author.getLastName());
}
System.out.println();
reader = new FileReader("book2.xml");
book = (Book) Unmarshaller.unmarshal(Book.class, reader);
System.out.println("Book ISBN: " + book.getIsbn());
System.out.println("Book Title: " + book.getTitle());
authors = book.getAuthors();
for (Iterator i = authors.iterator(); i.hasNext(); ) {
Author author = (Author) i.next();
System.out.println("Author: " + author.getFirstName()
+ " " + author.getLastName());
}
} catch (Exception e) {
System.err.println(e.getMessage());
e.printStackTrace(System.err);
}
}
}
編譯執行,你很可能会遇到意料之外的結果。我碰到的是這樣的錯誤:
java ibm.xml.castor.BookUnmarshaller
org.exolab.castor.xml.MarshalException:
ibm.xml.castor.Book{File:[not available]; line: 2; column: 7}
at org.exolab.castor.xml.Unmarshaller.unmarshal(...)
at ibm.xml.castor.BookUnmarshaller.main(BookUnmarshaller.java:14)
Caused by: java.lang.InstantiationException: ibm.xml.castor.Book
at java.lang.Class.newInstance0(Class.java:335)
at java.lang.Class.newInstance(Class.java:303)
at org.exolab.castor.util.DefaultObjectFactory
.createInstance(DefaultObjectFactory.java:107)
at org.exolab.castor.xml.UnmarshalHandler
.createInstance(UnmarshalHandler.java:2489)
...
到底怎麼回事?你撞上了直接使用 Castor 做資料綁定時必須接受的第一個妥協。
Castor 主要透過反射,以類似 Class.forName(類名).newInstance() 的方式建立物件,因此它不需要對類別有多少了解就能完成實例化。但前提是:這個類必須能用不帶參數的建構子建立。
好消息是 Book 與 Author 只要小幅修改就能避開這個錯誤——各補上一個 public Book() { } 與 public Author() { } 即可。重新編譯再跑一次。
但請想清楚這意味著什麼。有了無參數建構子,任何程式碼都能造出「沒有 ISBN 的書」或「沒有姓名的作者」,這在領域邏輯上顯然是問題。如果 Castor 沒有更進階的特性可用(下一篇會談),這個缺陷無從避免,你只能在使用時格外小心,並為每個可能觸發 NullPointerException 的欄位準備合理預設值:字串給空字串或預設值,物件要事先初始化。
補上無參數建構子後再跑一次,結果如下:
java ibm.xml.castor.BookUnmarshaller
Book ISBN: null
Book Title: Power Play
Author: null null
Book ISBN: null
Book Title: The Book of the Dead
Author: null null
Author: null null
問題顯然還沒解決。值得注意的是,有幾個欄位是空的。把它們和 XML 比對,你會發現這些值在文件裡明明寫得清清楚楚。那麼癥結在哪?
先觀察線索:書名都正確設定了。第二本書的作者也不是完全沒處理——Castor 確實建立了兩個 Author 物件,只是這兩個物件本身的姓名是空的。所以書名有值、作者物件存在、ISBN 空、作者姓名空。再加一條線索:如果你印出作者的總銷售量,那個值不會是 null。
看出來了嗎?所有為空的字段,都沒有 setter 方法——沒有 setIsbn()、沒有 setFirstName()。這是當初刻意設計的結果:一旦一本書有了 ISBN,就不該再變動,因此我們只在建構子裡要求它。但 Castor 使用反射,正因為它只能靠無參數建構子造物件,也就只能透過 setFieldName() 這類方法來填值。沒有 setter,欄位就永遠停在 null。
所以我們需要為 Book 與 Author 補上幾個方法(實作很直觀,留給你自行完成):
補完重新編譯即可。
再一次執行解組器:
java ibm.xml.castor.BookUnmarshaller
Book ISBN: 9780312347482
Book Title: Power Play
Author: Joseph Finder
Book ISBN: 9780446618502
Book Title: The Book of the Dead
Author: Douglas Preston
Author: Lincoln Child
這才是我們要的結果。前面說解組很簡單,看起來卻改了一堆東西,豈不自相矛盾?其實不矛盾:所有修改都發生在你自己的類裡,跟 Castor 的解組流程無關。Castor 本身用起來確實簡單,前提是類別結構得符合它的要求——每個類都要有無參數建構子,每個欄位都要有 get/set 方法。
改動後的類別跟最初相比變化不算大,功能上幾乎沒有差別。但設計確實留下了瑕疵。我認為一本書必須具備 ISBN,所以「能造出沒有 ISBN 的書」這件事讓我很不自在;同樣地,我也不希望任何人隨意改動既有書的 ISBN,那樣就無法正確表示這個物件了。
作者那邊的疑慮稍微輕一些。姓名對作者而言未必是关键識別碼,名字可以改,現在連姓也可以改。而且兩位同名作者在目前設計下無從區分。即便日後加上更合適的唯一識別碼(身分證號、駕照號等),無參數建構子與 setter 的需求依然存在,問題並沒有真正消失。
於是最終變成一道效益與控制權的權衡題:
這兩個問題只有你能替自己的團隊回答。對多數開發者而言,天平會倒向 Castor,代價則是接受這些約定。少數對設計品質有堅持、或受限於特殊需求而無法妥協的人,可能寧可自己寫一套簡單的 XML 序列化工具。無論如何,把 Castor 放進工具箱是划算的——這個專案不適合,下一個說不定剛好合用。
還有一項關鍵特性本文尚未觸及:對應檔(mapping file)。到目前為止,我們都是直接把 Java 類結構翻譯成 XML,這背後藏著幾個預設假設:
在企業級開發場景裡,這三點很可能都不成立。如果直接把類名與欄位名寫進 XML 被視為安全風險——因為它洩漏了過多應用程式的內部結構——該怎麼辦?如果手上拿到的 XML 檔結構固定,而你希望用不同的命名慣例來對應,該怎麼辦?如果只需要把少數幾個屬性寫入 XML,又該怎麼辦?
這些問題的答案是同一個:Castor 提供了更細緻的手段來控制 Java 與 XML 之間的對應關係。下一篇我們就來談對應檔。在那之前,不妨先想想為了讓 Castor 順利運作所做的那些調整,對你的設計意味著什麼。