XML 結構描述(Schema)說明了 XML 的型別、元素與嵌套結構,但 SAX、DOM、XOM 這類通用工具若要利用這些資訊做事,往往得寫下一大堆樣板程式碼。XMLBeans 屬於資料綁定(data binding)框架,它能依 XSD 直接產生 POJO,讓讀取、操作與輸出 XML 變得像操作普通 Java 物件一樣自然。
資料一旦變成 POJO,新的需求就跟著出現——尤其在胖客戶端(thick client)場景中,我們需要知道物件「何時被改動」,也就是所謂的事件(eventing)或通知(notification)。事件是 MVC 與 Model 2 模式的核心元素,其目的在於讓 GUI 程式碼與模型程式碼之間保持鬆耦合。本文以一個 Sudoku 遊戲為例,說明如何運用 XMLBeans 的擴充機制,為以 XML 為資料基礎的 Java 應用程式加上事件能力。
Sudoku 的盤面是一個 9×9 的格狀矩陣,再細分成 9 個 3×3 的子網格。開局時部分格子已填入 1 到 9 的數字,玩家要在下列限制下把其餘格子補完:
圖 1 是盤面的示意圖。我們實作的應用程式會透過 XMLBeans 的事件機制檢驗第 2 到第 4 條限制;一旦某格與限制衝突,視圖就把該格標成紅色。
圖 1. Sudoku 盤面示例

關於 Sudoku 的歷史與解題策略,可參考文末的相關資料。
Observer 設計模式正是為了解決「把變更通知給關心它的物件」這個問題,而本文描述的 XMLBeans 事件機制就是這個模式的具體實作。核心概念是:讓物件在執行期向 XMLObject 註冊,請求接收模型變更通知。如此一來,我們就能在每個 Sudoku 格子上掛上監聽器,對每一次變更逐一檢驗。
XMLBeans 允許透過設定檔(一般稱為 XSDCONFIG 檔)自訂程式碼產生過程,可配置的項目包括:
第四項正是產生事件程式碼的關鍵,但它有個前提:必須在編譯期就知道哪些物件關心變更。實務上我們通常無從預先得知,因此需要靠自訂的監聽器註冊機制來補足。XSDCONFIG 的詳細語法可參考文末資料。
啟用事件需要動用上述第三、第四項能力,實作上分為四個步驟:
XMLBeans 的介面擴充特性允許我們在產生的 POJO 上加入自訂實作的方法。使用方式是先定義一個介面,並為介面中的每個方法提供「靜態實作」。我們定義的介面是 com.ibm.xmlbeans.eventing.IModelChangeEmitter,內含四個方法,如清單 1 所示。
清單 1. com.ibm.xmlbeans.eventing.IModelChangeEmitter.java
public interface IModelChangeEmitter {
public void fireModelChangeEvent(ModelChangeEvent event);
public void addModelChangeListener(IModelChangeListener modelChangeListener);
public void removeModelChangeListener(IModelChangeListener modelChangeListener);
public boolean hasModelChangeListeners();
}
其中 addModelChangeListener() 與 removeModelChangeListener() 負責監聽器的生命週期管理,hasModelChangeListeners() 用來判斷目前是否有監聽者,而 fireModelChangeEvent() 則是把模型變更廣播給所有已註冊監聽器的工具方法。
當應用程式呼叫這些方法時,XMLBeans 會把呼叫者(也就是那個 XmlObject)連同參數一起轉交給靜態實作。本例的靜態實作放在 com.ibm.xmlbeans.eventing.ModelChangeEmitterHandler。由於它是靜態的、無法在 XMLObject 上存放執行期狀態,因此監聽器清單必須另尋去處;這裡我們用一個靜態的 HashMap 來保存,如清單 2。
清單 2. com.ibm.xmlbeans.eventing.ModelChangeEmitterHandler.java
public class ModelChangeEmitterHandler {
private static HashMap<XMLObject, LinkedList<IModelChangeListener>> listeners =
new HashMap<XMLObject, LinkedList<IModelChangeListener>>();
public static void fireModelChangeEvent(XMLObject xo, ModelChangeEvent event) {
LinkedList<IModelChangeListener> list = listeners.get(xo);
if (list == null)
return;
for (IModelChangeListener listener : list)
listener.modelChange(event);
}
public static void addModelChangeListener(XMLObject xo,
IModelChangeListener modelChangeListener) {
LinkedList<IModelChangeListener> list = listeners.get(xo);
if (list == null) {
list = new LinkedList<IModelChangeListener>();
listeners.put(xo, list);
}
list.add(modelChangeListener);
}
public static void removeModelChangeListener(XMLObject xo,
IModelChangeListener modelChangeListener) {
LinkedList<IModelChangeListener> list = listeners.get(xo);
if (list == null)
return;
list.remove(modelChangeListener);
// 清單空了就把整筆對應移除,避免殘留參考
if (list.isEmpty())
listeners.remove(xo);
}
public static boolean hasModelChangeListeners(XMLObject xo) {
return listeners.containsKey(xo);
}
}
addModelChangeListener() 很能代表整個清單操作的套路:先查這個 XMLObject 是否已有對應的監聽器清單,沒有就建立一個,最後把新監聽器掛上去。removeModelChangeListener() 則多做了一步善後——清單清空時順手把 HashMap 中的項目移除,讓物件得以被回收。
PrePostSet 擴充讓我們能在 XMLBeans 的寫入流程中插入自訂處理。做法是提供一個靜態類別,內含會在 XMLObject 變更「之前」與「之後」被呼叫的方法,如清單 3 的虛擬碼。
清單 3. PrePostSet 擴充虛擬碼
if (PrePostSetExtension.preSet())
updateXMLObject();
PrePostSetExtension.postSet();
靜態方法 preSet() 與 postSet() 共用同一組簽名:*Set(int opType, XMLObject xo, QName propertyName, boolean isAttr, int index)。乍看之下,把事件程式碼全塞進 postSet() 似乎就够了,但 postSet() 拿不到觸發事件所需的完整資訊:它必須送出包含「被更新的物件、更新操作、更新前的值、目前的值」的事件,而更新前的值在 postSet() 執行時早已被覆寫。因此我們得把舊值靜態地存起來。
舊值保存在靜態的 HashMap oldValues 中:preSet() 負責把原值複製進去,postSet() 負責真正觸發事件。清單 4 是 preSet() 的程式碼。
清單 4. ModelChangePrePostHandler.preSet()
public static boolean preSet(int opType, XMLObject xo, QName propertyName,
boolean isAttr, int index) {
IModelChangeEmitter emitter = (IModelChangeEmitter) xo;
if (!emitter.hasModelChangeListeners())
return true;
// 取出即將被變更的子節點
XMLObject oldXO = null;
if (isAttr)
oldXO = xo.selectAttribute(propertyName);
else {
switch (opType) {
case PrePostExtension.OPERATION_SET:
case PrePostExtension.OPERATION_REMOVE:
oldXO = getChildXO(xo, propertyName, index);
break;
case PrePostExtension.OPERATION_INSERT:
break;
}
}
// 保存舊值
int hash = hashCode(xo, propertyName, isAttr, index);
Object oldValue = null;
if (oldXO == null)
oldValue = null;
else if (oldXO instanceof SimpleValue) {
oldValue = ((SimpleValue) oldXO).getObjectValue();
if (oldValue instanceof XMLObject)
oldValue = ((XMLObject) oldValue).copy();
} else
oldValue = oldXO.copy();
oldValues.put(hash, oldValue);
return true;
}
這段程式先確認模型物件上是否掛了監聽器;若沒有就直接放行,不做多餘工作。有的話就快取目前的屬性值;如果目標不是屬性,改呼叫工具方法 getChildXO() 取得子節點。最後,若取到的不是單值節點,就複製一份,再把副本(或原值)放進 oldValues。清單 5 是 postSet()。
清單 5. ModelChangePrePostHandler.postSet()
public static boolean postSet(int opType, XMLObject xo, QName propertyName,
boolean isAttr, int index) {
IModelChangeEmitter emitter = (IModelChangeEmitter) xo;
if (!emitter.hasModelChangeListeners())
return true;
// 取回舊值
int hash = hashCode(xo, propertyName, isAttr, index);
Object oldValue = oldValues.get(hash);
oldValues.remove(hash);
ModelChangeEvent.Action action = ModelChangeEvent.Action.UPDATE;
// 取得新的 XML 物件
XMLObject newXO = null;
if (isAttr)
newXO = xo.selectAttribute(propertyName);
else {
switch (opType) {
case PrePostExtension.OPERATION_SET:
newXO = getChildXO(xo, propertyName, index);
break;
case PrePostExtension.OPERATION_INSERT:
XMLObject[] children = xo.selectChildren(propertyName);
// 插入時新元素一定是最後一個
newXO = children[children.length - 1];
action = ModelChangeEvent.Action.CREATE;
break;
case PrePostExtension.OPERATION_REMOVE:
action = ModelChangeEvent.Action.DELETE;
break;
}
}
// 取得新值
Object newValue = null;
if (newXO == null)
newValue = null;
else if (newXO instanceof SimpleValue)
newValue = ((SimpleValue) newXO).getObjectValue();
else
newValue = newXO;
// 只有新舊值真的不同才觸發事件
if (((newValue == null) && (oldValue != null)) || ((newValue != null)
&& (!newValue.equals(oldValue))))
emitter.fireModelChangeEvent(new ModelChangeEvent(propertyName,
emitter, oldValue, newValue, action, index));
return true;
}
postSet() 的流程是:先確認有監聽器,再從 oldValues 取回舊值並清掉該筆記錄,接著依操作型別判斷新值與事件類型(新增、更新、刪除),最後只有在新舊值確實不同時才建立並觸發模型變更事件。這個「先比對再發散」的設計可以避免無意義的噪音事件。清單 6 是两个輔助方法。
清單 6. ModelChangePrePostHandler 的工具方法
private static XMLObject getChildXO(XMLObject xo, QName propertyName, int index) {
XMLObject childXO = null;
XMLObject[] values = xo.selectChildren(propertyName);
if (values.length != 0) {
if (index == -1)
childXO = values[0];
else if (index < values.length)
childXO = values[index];
}
return childXO;
}
private static int hashCode(XMLObject xo, QName propertyName, boolean isAttr, int index) {
final int prime = 31;
int result = 1;
result = prime * result + index;
result = prime * result + (isAttr ? 1231 : 1237);
result = prime * result + ((propertyName == null) ? 0 : propertyName.hashCode());
result = prime * result + ((xo == null) ? 0 : xo.hashCode());
return result;
}
getChildXO() 負責取出子節點:先以 selectChildren() 撈出候選集合,再依 index 挑出正確的那一個(index 為 -1 時視為單值,取第一個)。hashCode() 則把 XMLObject、屬性名稱、是否為屬性、索引位置混算出唯一雜湊,作為 oldValues 的鍵;這個方法在 Eclipse 中可由IDE自動產生。
要在 XMLBeans 上落實事件機制,需要同時啟用介面擴充與 PrePostSet 擴充,兩者都寫在同一份 XSDCONFIG 檔裡,如清單 7。
清單 7. 事件機制的 XSDCONFIG 檔
<xb:config xmlns:xb="https://xml.apache.org/xmlbeans/2004/02/xbean/config">
<xb:extension for="*">
<xb:interface name="com.ibm.xmlbeans.eventing.IModelChangeEmitter">
<xb:staticHandler>
com.ibm.xmlbeans.eventing.ModelChangeEmitterHandler
</xb:staticHandler>
</xb:interface>
</xb:extension>
<xb:extension for="*">
<xb:prePostSet>
<xb:staticHandler>
com.ibm.xmlbeans.eventing.ModelChangePrePostHandler
</xb:staticHandler>
</xb:prePostSet>
</xb:extension>
</xb:config>
第一個 xb:extension 元素負責介面擴充設定:for="*" 表示套用到所有產生的 XmlObject,让它们都實作 IModelChangeEmitter,而實際行為委派給 ModelChangeEmitterHandler。第二個 xb:extension 元素則是 PrePostSet 設定,指示 XMLBeans 在屬性被修改的前後分別呼叫 ModelChangePrePostHandler 的 preSet() 與 postSet()。
最後一步是把這份設定檔交給產生器:在呼叫 scomp 時,把 XSDCONFIG 檔當作最後一個參數傳入。本範例把這些參數寫在一個 Java 類別裡,如清單 8。
清單 8. com.ibm.xmlbeans.generator.SudokuSchemaGenerator.java
public class SudokuSchemaGenerator {
public static void main(String[] args) {
String[] xmlBeanArgs = new String[] {
"-d", "xb_bin",
"-src", "xb_src",
"-out", "lib/sudokuXB.jar",
"-javasource", "1.5",
"schema/sudokuXBE.xsd",
"schema/eventing.xsdconfig"
};
org.apache.xmlbeans.impl.tool.SchemaCompiler.main(xmlBeanArgs);
}
}
scomp 與其命令列參數的細節可參考文末資料。執行完成後,我們就得到一批由 sudokuXBE.xsd 產生的 POJO,而且它們天生就具備在資料變動時通知關心者的能力。
Sudoku 是個 RCP 應用程式:當玩家填入不合法的值時,程式會即時回饋。程式會依列、行與子網格中的其他格子檢驗該值,若有衝突就把格子標成紅色,如圖 2。
圖 2. Sudoku 遊戲畫面

實作圖形介面(UI)的步驟如下:
設計上的重點是消除視圖與模型之間的耦合。控制器是一個 SWT 鍵盤監聽器,它先改動模型;模型接著把變更通知給檢驗器;檢驗器判斷自己負責的格子是否合法並設定「有效」旗標;框架隨即觸發第二個事件,由視圖(格子)接收並更新背景顏色。圖 3 用流程圖呈現這四個階段。
圖 3. Sudoku RCP 應用程式的事件流

結構描述本身相當樸素:先定義盤面,盤面由 9 個 row 元素組成,如圖 4。
圖 4. BoardType 結構描述型別

接著定義 row 型別,如圖 5。這樣就足以描述整個 9×9 的網格。
圖 5. RowType 結構描述型別

row 型別由 9 個 cell 元素組成,透過這個拆分,我們得以逐一描述列中每格的值,如圖 6。
圖 6. CellType 結構描述型別

cell 型別是個簡單元素,內容限定為 1 到 9 或點號(.,代表空格);此外它還有一個屬性,用來記錄此格依列、行、子網格檢驗後是否有效,如圖 7。
圖 7. CellStringType 結構描述型別

CellStringType 進一步把 cell 的值約束為 1 到 9 與點號的列舉。
把這份結構描述,加上前一節定義好的 XSDCONFIG 設定一起餵給產生器,就能得到一批既代表這個模型、又具備事件通知能力的 POJO——模型一有變動,UI 便會收到通知。
因為事件能力已內建在產生的 XMLBeans 中,UI 可以照典型的 MVC 方式撰寫。視圖以 Eclipse 平台開發,這個 RCP 應用程式基本上就是一個 Eclipse 外掛,並在外掛啟動時初始化視圖。建立每個 SWT 文字元件時,透過 text.addKeyListener() 掛上鍵盤監聽器,攔截使用者在空格中的按鍵輸入,如清單 9。
清單 9. View.addKeyListeners() 中的 KeyAdapter
public void keyPressed(KeyEvent e) {
switch (e.keyCode) {
case '1':
case '2':
case '3':
case '4':
case '5':
case '6':
case '7':
case '8':
case '9':
if (text.getEditable()) {
final CellStringType.Enum newValue =
CellStringType.Enum.forString(String.valueOf(e.character));
Job job = new Job("Run Validation") {
protected IStatus run(IProgressMonitor arg0) {
XbeUtilities.getCell(Activator.getDefault().getBoard(), myRow, myCol)
.setCellValue(newValue);
return Status.OK_STATUS;
}
};
text.setText(String.valueOf(e.character));
job.schedule();
}
break;
case SWT.BS:
case SWT.DEL:
case '.':
case ' ':
if (text.getEditable()) {
Job job = new Job("Run Validation") {
protected IStatus run(IProgressMonitor arg0) {
XbeUtilities.getCell(Activator.getDefault().getBoard(), myRow, myCol)
.setCellValue(CellStringType.X);
return Status.OK_STATUS;
}
};
job.schedule();
text.setText(" ");
}
break;
// ... 方向鍵導覽程式碼 ...
}
e.doit = false;
}
接著以 setCellValue(newValue) 寫入模型中的值。這次呼叫會更新由結構描述定義的模型,而 XMLBeans 的事件程式碼隨即觸發事件,通知所有監聽器模型已經改變。
事件模型的關鍵一環,是依格子所在的列、行與子網格位置來判定其有效性。在 modelChange(ModelChangeEvent event) 中會呼叫 runValidation() 進行檢驗,如清單 10。
清單 10. CellValidatorListener.modelChange(ModelChangeEvent)
public void modelChange(ModelChangeEvent event) {
if (XbeUtilities.CELLVALUE_QNAME.equals(event.getPropertyName())) {
// 只有真的有值才需要檢驗
if (!CellStringType.X.equals(cell.getCellValue())) {
if (cell.equals(event.getSource())) {
// 自己就是來源,跑一次完整檢驗
int count = runValidation();
numInvalid = count;
} else {
// 來源是別的格子,只做增量維護
if (cell.getCellValue().equals(CellStringType.Enum.forString(
(String) event.getNewValue())))
numInvalid++;
else {
if (cell.getCellValue().equals(CellStringType.Enum.forString(
(String) event.getOldValue())))
numInvalid--;
}
}
} else if (cell.equals(event.getSource()))
numInvalid = 0;
if (numInvalid == 0)
cell.setValid(true);
else if (numInvalid < 0) {
Activator.getDefault().getLog().log(
new Status(IStatus.WARNING, Activator.PLUGIN_ID,
"Cell validator has a negative number of invalid cells. This is impossible."));
} else
cell.setValid(false);
}
程式首先確認變更的是哪個屬性——在這裡必須是 CELLVALUE_QNAME。若事件來源正是自己,就呼叫 runValidation() 對所有條件做一次完整檢驗;若來源是其他格子,則改用增量方式維護計數:值等於新值就 numInvalid++,若原本等於舊值則 numInvalid--。最後,numInvalid 為 0 時呼叫 cell.setValid(true),否則設為 false;計數若變成負數代表邏輯有誤,於/write 入警告日誌。設定有效旗標的動作本身又會觸發一次 XMLBeans 事件,由視圖監聽器接手更新背景顏色,如清單 11。
清單 11. View 中的 IModelChangeListener
public void modelChange(ModelChangeEvent event) {
if (XbeUtilities.VALID_QNAME.equals(event.getPropertyName())) {
// 可能不在 display 執行緒上,必須切回去才能改背景色
text.getDisplay().asyncExec(new Runnable() {
public void run() {
if (cell.getValid())
text.setBackground(text.getDisplay().getSystemColor(SWT.COLOR_WHITE));
else
text.setBackground(text.getDisplay().getSystemColor(SWT.COLOR_RED));
}
});
}
}
每個格子在建立時都掛上了 modelChangeListener(),所以格子會收到通知;處理事件時它判斷自己是否有效,據此設定對應文字元件的背景色。這裡刻意用 asyncExec() 切回 display 執行緒,因為 SWT 規定介面元件只能在該執行緒上操作。
導入事件之後,我們得以用簡單的程式設計模型解除使用者介面對模型的依賴,既快速做出 Sudoku 這樣的應用程式,也避免了視圖與模型之間的糾纏。
整件事的做法可以濃縮成三句話:透過 XMLBeans 的兩個擴充點——介面擴充與 PrePostSet——分別負責「掛監聽器」與「捕捉變更並發散通知」,最後再靠一份設定檔把兩者整合進程式碼產生流程。這套模式並不限於遊戲;任何需要讓 XML 模型與呈現層保持鬆耦合的 Java 應用,都能沿用同樣的骨架。
| 描述 | 名稱 | 大小 | 下載方式 |
|---|---|---|---|
| XMLBeans 事件與 Sudoku 遊戲 Eclipse 專案 | SudokuProject.zip | 2694KB | HTTP |
| 以 XML 描述的 Sudoku 盤面集合 | SudokuBoards.zip | 4KB | HTTP |
| Windows 平台已編譯的 Sudoku 遊戲 | SudokuApplication-Win32.zip | 146346KB | HTTP |