Visual Web JSF 應用中的資料轉換與驗證完整教學

教學目標

掌握 JSF 1.2 (Woodstock) 轉換器 與 驗證器：

• 轉換器：將字串輸入轉為 Java 型別（數值、日期、貨幣）供運算。
• 驗證器：確保輸入落於指定範圍/格式，失敗時顯示錯誤訊息。

建立兩個應用：

1. 溫度轉換器（攝氏 ↔ 華氏）
2. 貨幣轉換與日期顯示

第一部分：溫度轉換應用

1. 建立專案

File → New Project → Web → Web Application，名稱 ValidatorConverter，啟用 Visual Web JSF。

2. 版面配置

• 文字框：Label Celsius，Text 0.0，Required true（紅星標示）。
• 標籤：Fahrenheit。
• 靜態文本：Text 32.0（水冰點）。
• 訊息：Ctrl+Shift 連線至文字框，顯示驗證/轉換錯誤。

3. 加入雙精度範圍驗證器

• 調色盤 Validators 拖 Double Range Validator 至文字框。
• 屬性：minimum = -273.15（絕對零度），maximum = 1000.0。

4. 加入雙精度轉換器

• 調色盤 Converters 拖 Double Converter 至文字框。
• 自動將輸入字串轉為 Double 物件。

5. 數值變更事件處理

雙擊文字框，在 textField1_processValueChange() 加入：

public void textField1_processValueChange(ValueChangeEvent event) {
    double celsius = ((Double) textField1.getText()).doubleValue();
    double fahrenheit = 9.0 * celsius / 5.0 + 32.0;
    staticText1.setText(new Double(fahrenheit));
}

6. 測試驗證與轉換錯誤

• 空白送出 → Required 驗證失敗。
• 輸入 100 → 正常轉換顯示 212.0。
• 輸入 -1000 → 超出範圍驗證失敗。
• 輸入 20x → 轉換失敗（非數值）。

第二部分：貨幣轉換與日期格式化

1. 新增 Currency.jsp 頁面並設為首頁

2. 版面配置

• 文字框：Label Dollar Amount:，Required true。
• 按鈕：Convert。
• 兩組 標籤 + 靜態文本：Converted to Euros:、Date and Time:。
• 訊息：連線至文字框。

3. 數值轉換器（貨幣模式）

• 文字框加入 Number Converter → 類型 Currency，小數位 2，Locale English (US) → 預設貨幣 USD。
• Euros 靜態文本加入 Number Converter → 類型 Currency，Locale German (Germany) → 預設 EUR。

4. 日期時間轉換器

• Date Time 靜態文本加入 Date Time Converter。
• Pattern 設 EEE, d MMM yyyy HH:mm:ss zzzz（如 Wed, 14 Jan 2009 15:30:00 CST）。

5. 按鈕動作邏輯

private static final double USD_TO_EUR = 0.74;

public String button1_action() {
    Number dollars = (Number) textField1.getValue();
    double euros = dollars.doubleValue() * USD_TO_EUR;
    staticText1.setText(new Double(euros));
    staticText2.setText(new java.util.Date());
    return null;
}

6. 測試貨幣格式規則

• 輸入 $100.00 → 正常轉換顯示歐元與日期。
• 輸入 100（缺 $） → 轉換錯誤，上次結果保留。
• 支援逗號分隔 $1,234.56，自動忽略錯誤位置逗號。
• 小數點後超過兩位自動四捨五入。

第三部分：自訂驗證器

需求：輸入必須為三位數字（000-999）。

1. 新增文字框 textField2，Required true，加入訊息組件。
2. 右鍵文字框 Edit Event Handlers → validate。
3. 實作 textField2_validate()：

public void textField2_validate(FacesContext ctx, UIComponent comp, Object value) {
    String s = String.valueOf(value);
    if (!s.matches("\\d\\d\\d")) {
        throw new ValidatorException(new FacesMessage("Not a three-digit number."));
    }
}

• matches("\\d\\d\\d") 正則表達式限定三位數字。
• 拋出 ValidatorException 將錯誤訊息加入 FacesContext，渲染時顯示於訊息組件。

第四部分：客製化標準驗證訊息

建立資源包 MyResources.properties 覆蓋預設錯誤訊息（全域生效）：

1. New → Other → Properties File，名稱 MyResources，放入 src/java/validatorconverter/。
2. 加入鍵值：javax.faces.component.UIInput.REQUIRED = Please enter a value and then press Enter.
3. 編輯 faces-config.xml（XML 模式）：

<application>
  <message-bundle>validatorconverter.MyResources</message-bundle>
</application>

重新執行，空白送出顯示自訂訊息。

標準訊息鍵對照表

鍵	用途
javax.faces.component.UIInput.CONVERSION	轉換錯誤
javax.faces.component.UIInput.REQUIRED	必填欄位
javax.faces.component.UISelectOne.INVALID	無效單選值
javax.faces.component.UISelectMany.INVALID	無效多選值
javax.faces.validator.NOT_IN_RANGE	超出範圍 {0}-{1}
javax.faces.validator.DoubleRangeValidator.MAXIMUM	超過最大值 {0}
javax.faces.validator.DoubleRangeValidator.MINIMUM	低於最小值 {0}
javax.faces.validator.DoubleRangeValidator.TYPE	型別不符
javax.faces.validator.LengthValidator.MAXIMUM	長度超過最大值 {0}
javax.faces.validator.LengthValidator.MINIMUM	長度低於最小值 {0}
javax.faces.validator.LongRangeValidator.MAXIMUM	超過最大值 {0}
javax.faces.validator.LongRangeValidator.MINIMUM	低於最小值 {0}
javax.faces.validator.LongRangeValidator.TYPE	型別不符

總結

• 轉換器：字串 ⇄ Java 型別（數值、貨幣、日期）。
• 驗證器：範圍、長度、格式檢查。
• 自訂驗證：validate 事件 + 正則表達式 + ValidatorException。
• 訊息客製化：資源包 + faces-config.xml message-bundle。