J2ME 打包發布：使用 Ant + Antenna 解決行動平台 API 相容性問題

問題背景：JAD/JAR 直打包的平台相容性地雷

J2ME 遊戲/應用提交至行動平台 (如 Nokia、Siemens、Motorola 等運營商商店) 時，若直接使用 J2ME Wireless Toolkit (WTK) 或 IDE 內建打包：

• **MANIFEST.MF / JAD 屬性不全**：缺少平台要求的強制屬性 (如 `MicroEdition-Profile`、`MicroEdition-Configuration`、價格、權限等)
• **API 簽名衝突**：引用廠商專有 API (Nokia UI、Siemens Game API、MIDP 2.0/3.0 選擇性套件) 時，標準打包不會預驗證類別檔
• **預驗證缺失**：CLDC 要求類別檔經過**預驗證** (Preverify) 才能在裝置上執行，IDE 打包常漏掉此步驟
• **混淆/優化缺失**：未進行代碼混淆，包體過大、易逆向、效能未優化

解決方案：Ant + Antenna 自動化構建

Antenna 是專為 J2ME 設計的 Ant Task 库，封裝 WTK 的編譯、預驗證、打包、混淆、模擬器啟動等功能，實現**可重現、可配置、可整合 CI** 的自動化構建流程。

環境準備

1. 下載 Apache Ant 1.6.2+
2. 下載 Antenna 0.9.13 (`antenna-bin-0.9.13.jar`)
3. 將 `antenna-bin-0.9.13.jar` 複製到 `$ANT_HOME/lib`
4. 將廠商 API 複製到 `$ANT_HOME/lib`：
   • `nokiaui.jar` (Nokia UI API)
   • `gx.jar` (Siemens/其他廠商 API)
   • 其他平台專用 API jar
5. 設定環境變數：
   • `ANT_HOME` = Ant 安裝目錄
   • `PATH` 包含 `%ANT_HOME%/bin`

build.xml 完整範例 (Nokia S40 平台)

<?xml version="1.0" encoding="UTF-8"?>
<project name="LoveNote_S40" default="build" basedir=".">
    <!-- 使用 classic 編譯器 (相容舊版 JDK) -->
    <property name="build.compiler" value="classic"/>

    <!-- WTK 安裝路徑 (關鍵：提供 bootclasspath、預驗證器、模擬器) -->
    <property name="wtk.home" value="C:/WTK104"/>

    <!-- 專案屬性 -->
    <property name="midlet.name" value="LoveNote_S40"/>
    <property name="midlet.home" value="."/>

    <!-- 載入 Antenna Tasks -->
    <taskdef resource="antenna.properties"/>

    <target name="clean">
        <delete failonerror="false" dir="classes"/>
        <delete failonerror="false">
            <fileset dir=".">
                <exclude name="build.xml"/>
            </fileset>
        </delete>
    </target>

    <target name="build">
        <!-- 1. 產生 JAD 檔 (含 MIDlet 資訊、圖示、類別名) -->
        <wtkjad jadfile="${midlet.name}.jad"
              jarfile="${midlet.name}.jar"
              name="LoveNote"
              vendor="websurf tech co., inc."
              manifest="MANIFEST.MF"
              version="1.0">
            <midlet name="LoveNote" icon="/icons/icon.png" class="GameMidlet"/>
        </wtkjad>

        <!-- 2. 清理並建立編譯輸出目錄 -->
        <delete dir="classes"/>
        <mkdir dir="classes"/>

        <!-- 3. 編譯 Java 原始碼 (不預驗證) -->
        <wtkbuild srcdir="${midlet.home}" 
                  destdir="classes" 
                  preverify="false" 
                  encoding="utf-8"/>

        <!-- 4. 打包 JAR (含資源檔、混淆) -->
        <wtkpackage jarfile="${midlet.name}.jar"
                    jadfile="${midlet.name}.jad"
                    manifest="MANIFEST.MF"
                    obfuscate="true">
            <fileset dir="classes"/>
            <fileset dir="res"/>
        </wtkpackage>

        <!-- 5. 預驗證 (關鍵步驟！) -->
        <wtkpreverify jarfile="${midlet.name}.jar"
                      jadfile="${midlet.name}.jad"
                      bootclasspath="${wtk.home}/lib/midpapi.zip"
                      classpath="${wtk.home}/lib/ext/nokiaui.jar"/>

        <!-- 6. (可選) 啟動模擬器測試 -->
        <!-- 
        <wtkrun jadfile="${midlet.name}.jad" 
              wait="false" 
              device="DefaultColorPhone"/>
        -->
    </target>
</project>

關鍵 Task 解析

Task	功能	關鍵屬性
`wtkjad`	產生 JAD 描述檔	`jadfile`、`jarfile`、`name`、`vendor`、`version`、`midlet` 子元素
`wtkbuild`	編譯 Java 源碼	`srcdir`、`destdir`、`preverify` (建議 false，分步驟)、`bootclasspath`、`classpath` (廠商 API)
`wtkpackage`	打包 JAR、可選混淆	`jarfile`、`jadfile`、`manifest`、`obfuscate="true"`、嵌套 `fileset`
`wtkpreverify`	**CLDC 預驗證** (核心！)	`jarfile`、`jadfile`、`bootclasspath` (midpapi.zip)、`classpath` (廠商 API)
`wtkrun`	啟動模擬器測試	`jadfile`、`device`、`wait`

平台強制屬性：JAD 手工補充

構建完成後，`build.xml` 同目錄產生 `MANIFEST.MF`，建議**手工編輯 JAD** 補充平台要求屬性：

MicroEdition-Profile: MIDP-1.0
MicroEdition-Configuration: CLDC-1.0
Media-Price: 5元每次
Nokia-MIDlet-Category: Game
Nokia-MIDlet-Original-File-Name: LoveNote_S40.jar
...

將修改後的 JAD 替換進 JAR (或重新打包)，可減小體積並通過平台審核。

常見問題與解決

| 問題 | 原因 | 解決方案 | |------|------|----------| | `ClassNotFoundException: com.nokia.mid.ui.*` | 編譯/預驗證缺少 `nokiaui.jar` | `wtkbuild`/`wtkpreverify` 的 `classpath` 加入 `nokiaui.jar` | | `VerifyError` 裝置安裝失敗 | 未預驗證或預驗證 bootclasspath 錯誤 | 確認 `wtkpreverify` 的 `bootclasspath="${wtk.home}/lib/midpapi.zip"` | | 包體過大超過平台限制 (如 64KB/100KB) | 未混淆、資源未壓縮 | `wtkpackage obfuscate="true"`、PNG 壓縮、移除無用資源 | | 模擬器跑得動真機裝不上 | 真機 CLDC/MIDP 版本更低、API 不相容 | 針對目標裝置最低版本編譯、條件編譯/反射隔離高版本 API | | Ant 執行 `taskdef` 失敗 | `antenna.properties` 未在 classpath | 確認 `antenna-bin.jar` 在 `$ANT_HOME/lib`，重啟終端機 |

進階技巧

1. 多平台構建： 定義多個 target (`build-nokia`, `build-siemens`)，切換 `classpath`、`wtk.home`、`device` 參數
2. 版本號自動遞增： 使用 `buildnumber` task 或 Shell 腳本更新 `version` 屬性
3. CI 整合： Jenkins/GitLab CI 執行 `ant clean build`，產物上傳至制品庫
4. 條件編譯： Antenna 支援 `#ifdef`/`#endif` 註解預處理，隔離平台專用代碼

總結

J2ME 發布的核心痛點在於**平台碎片化**導致的 API 相容與預驗證要求。**Ant + Antenna** 提供標準化、自動化、可配置的構建流程，解決：

• 編譯時正確引用廠商 API (`classpath`)
• **強制預驗證** (`wtkpreverify`)，保證裝置可執行
• 混淆優化 (`obfuscate`)，縮小包體、保護代碼
• 標準化 JAD/MANIFEST 產生，滿足平台審核
• 可整合 CI/CD，實現持續交付

雖然 J2ME 時代已遠去，但**構建自動化、平台適配、預驗證/驗證機制**的工程思維，在 Android (Gradle + ProGuard/R8)、iOS (xcodebuild + Bitcode)、嵌入式交叉編譯等現代場景依然完全適用。