J2ME 定位 API 範例實作 (一)：TouristRoute MIDlet 架構、UI 流程與啟動序列

專案簡介：TouristRoute MIDlet

Nokia 官方提供的 JSR-179 參考實作 TouristRoute**，展示完整 LBS 應用架構：從定位服務搜尋、位置更新顯示、地標編輯/儲存、指南針/俯仰翻滾顯示，到接近警示。原始碼可從 Nokia Forum 下載。注意：Series 40 平台無法正常執行** (缺乏 GPS 硬體與 JSR-179 實作)，需在 S60 3rd Edition FP1+ 裝置或模擬器測試。

UI 架構與畫面流程

四大 UI 類別

畫面轉換流程圖

啟動 → 搜尋 Provider → [找到] → Route View (TouristUI)
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
              [Edit 指令]      [Compass 指令]   [Landmarks 指令]
                    │               │               │
                    ▼               ▼               ▼
            LandmarkEditorUI   CompassUI      Landmark List
                    │               │
                    ▼               ▼
              [Save/Delete]    [Pitch/Roll 指令]
                                    │
                                    ▼
                              PitchRollUI

狀態機關鍵點

• 啟動時自動搜尋免費 Provider → 失敗則詢問是否接受付費 → 仍失敗顯示錯誤訊息。
• 首次 locationUpdated 事件到達前，顯示「正在尋找定位服務…」等待畫面 (MessageUI)。
• 收到首次位置更新 → firstLocationUpdateEvent() → 建立 TouristUI 並 display.setCurrent() 進入主畫面。
• 所有 UI 類別持有 TouristData (Model) 參考，透過 ProviderStatusListener 回報 Provider 狀態變更。

Model 層架構 (com.nokia.example.location.tourist.model)

啟動序列詳細時序 (關鍵同步機制)

// TouristMIDlet.startApp()
protected void startApp() {
    display = Display.getDisplay(this);
    if (ConfigurationProvider.isLocationApiSupported()) {
        ConfigurationProvider.getInstance().autoSearch(this); // 非同步搜尋
    } else {
        MessageUI.showApiNotSupported();
    }
}

// ConfigurationProvider.autoSearch() 找到 Provider 後：
listener.providerSelectedEvent(); // 在 TouristMIDlet 執行

// TouristMIDlet.providerSelectedEvent()
public void providerSelectedEvent() {
    synchronized (mutex) {               // 確保 TouristData 只建立一次
        MessageUI.showLocationProviderState(); // 顯示「正在取得位置資料…」
        data = new TouristData(this);    // 建立 Model，內部註冊 LocationListener
    }
}

// TouristData 收到首次 locationUpdated → 回呼 TouristMIDlet.firstLocationUpdateEvent()
public void firstLocationUpdateEvent() {
    synchronized (mutex) {               // 等待 providerSelectedEvent 完成
        TouristUI ui = new TouristUI(data);
        data.setTouristUI(ui);
        display.setCurrent(ui);          // 真正進入主畫面
    }
}

設計亮點：mutex 確保 TouristData 建立與 UI 顯示的原子性，避免競態條件導致 NullPointerException 或重複建立 UI。

需求與執行環境

• S60 3rd Edition FP1 SDK** (含模擬器、Route 工具、NMEA 模擬軌跡)。
• 不支援 Series 40**：缺乏 JSR-179 實作與 GPS 硬體。
• 真機測試：Nokia N95, N82, E71, 6210 Navigator 等內建 GPS 裝置。

原始碼套件結構

com.nokia.example.location.tourist
├── TouristMIDlet.java              // MIDlet 進入點、生命週期、ProviderStatusListener 實作
├── model
│   ├── ConfigurationProvider.java  // Provider 搜尋、Criteria 管理、Orientation 存取
│   ├── TouristData.java            // LocationListener/ProximityListener、資料分發
│   ├── ControlPoints.java          // LandmarkStore 管理
│   ├── ProviderStatusListener.java // 介面
│   └── ProviderSelectedListener.java // 介面
├── ui
│   ├── TouristUI.java              // 主畫面
│   ├── LandmarkEditorUI.java       // 地標編輯
│   ├── CompassUI.java              // 指南針
│   ├── PitchRollUI.java            // 俯仰/翻滾
│   ├── ProviderQueryUI.java        // 詢問付費 Provider 對話框
│   └── MessageUI.java              // 等待/錯誤訊息
└── util
    └── Utils.java                  // formatDouble() 等工具方法

圖片資源 (原文保留連結)

• MIDlet 畫面流程圖：https://code.yunyiwangluo.com/bianchen/UploadFiles_4619/201701/2017011209312041.jpg
• UI 類別轉換圖：https://code.yunyiwangluo.com/bianchen/UploadFiles_4619/201701/2017011209312122.jpg
• 類別關係圖 (Model/UI 分層)：https://code.yunyiwangluo.com/bianchen/UploadFiles_4619/201701/2017011209312159.jpg
• 啟動與定位搜尋流程圖：https://code.yunyiwangluo.com/bianchen/UploadFiles_4619/201701/2017011209312105.jpg

下一步預告

下一篇將深入 ConfigurationProvider 靜態 Criteria 建構、TouristData 事件處理執行緒模型、ControlPoints 地標存儲實作細節，以及 Utils.formatDouble() 格式化工具。